onix-parser

A Node.js library for parsing ONIX 3.0 XML files and extracting structured product data for publishing and digital books. ONIX (ONline Information eXchange) is the international standard for representing and communicating book industry product information in electronic form.

Features

• ✅ Parses ONIX 3.0 XML files
• ✅ Extracts comprehensive product metadata (identifiers, titles, contributors, prices, descriptions, etc.)
• ✅ Supports both EPUB and Audiobook ONIX files
• ✅ Validates required fields and provides detailed error messages
• ✅ Returns structured JSON data for easy integration
• ✅ Handles multiple product variants (digital vs print)
• ✅ Includes extensive code lists for ONIX field mappings

Installation

npm install onix-parser

Usage

Basic Example

const onix = require('onix-parser');

(async () => {
  try {
    const result = await onix('./path/to/your/onix-file.xml');

    if (result.status) {
      console.log('✅ ONIX file parsed successfully!');
      console.log('Product:', result.data.title.titleText);
      console.log('ISBN:', result.data.iSNB13);
      console.log('Price:', result.data.priceBRL);
    } else {
      console.error('❌ Parsing failed:', result.message);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Advanced Usage

const onix = require('onix-parser');

async function processOnixFile(filePath) {
  const result = await onix(filePath);

  if (!result.status) {
    throw new Error(`ONIX parsing failed: ${result.message.join(', ')}`);
  }

  const { data } = result;

  // Extract key information
  const productInfo = {
    isbn: data.iSNB13,
    title: data.title.titleText,
    subtitle: data.title.subtitle,
    authors: data.contributors
      .filter(c => c.contributorRoleCode === 'A01') // Author
      .map(c => c.personName),
    publisher: data.publishing.publisherName,
    description: data.details.description,
    price: data.priceBRL,
    format: data.productFormDetail.detail,
    language: data.language?.languageCode,
    publicationDate: data.publishing.publicationDate
  };

  return productInfo;
}

// Usage
processOnixFile('./books/sample.xml')
  .then(info => console.log('Book info:', info))
  .catch(err => console.error('Error:', err.message));

API

onix(onixFilePath)

Parses an ONIX 3.0 XML file and returns structured product data.

Parameters:

• onixFilePath (string): Path to the ONIX XML file

Returns: Promise<OnixResult>

interface OnixResult {
  status: boolean;
  data?: ProductData;
  message?: string[];
}

Supported Product Forms:

• EA - Digital (delivered electronically)
• ED - Digital download
• AJ - Downloadable audio file

Supported Product Form Details:

• E101 - EPUB format
• A103 - MP3 format

Data Structure

The parsed data includes the following main sections:

Header Information

{
  sentDateTime: "2022-06-29 20:04",
  senderName: "Publisher Name"
}

Product Identifiers

{
  identifiers: [
    {
      productIDTypeCode: "15",
      productIDType: "ISBN-13",
      iDValue: "9781234567890"
    }
  ],
  iSNB13: "9781234567890" // Convenience field for ISBN-13
}

Title Information

{
  title: {
    titleText: "Sample Book Title",
    subtitle: "Optional Subtitle"
  }
}

Contributors

{
  contributors: [
    {
      contributorRoleCode: "A01",
      contributorRole: "Author",
      personName: "Sample Author",
      // ... additional contributor fields
    }
  ]
}

Pricing

{
  price: [
    {
      priceTypeCode: "02",
      priceType: "RRP including tax",
      priceAmount: "29.99",
      currencyCode: "BRL",
      countriesIncluded: ["BR"]
    }
  ],
  priceBRL: "29.99" // Convenience field for BRL price
}

Content Details

{
  details: {
    description: "Book description...",
    shortDescription: "Brief description...",
    toc: "Table of contents..."
  }
}

Complete Output Example

{
  "status": true,
  "data": {
    "sentDateTime": "2022-06-29 20:04",
    "senderName": "Sample Publisher",
    "recordReference": "1234567890_9781234567890",
    "notificationType": "03",
    "notification": "Notification confirmed on publication",
    "productFormDetail": {
      "code": "E101",
      "detail": "EPUB",
      "isFixedFormat": false
    },
    "primaryContentTypeCode": "10",
    "primaryContentType": "Text (eye-readable)",
    "epubTechnicalProtectionCode": "01",
    "epubTechnicalProtection": "DRM",
    "identifiers": [
      {
        "productIDTypeCode": "15",
        "productIDType": "ISBN-13",
        "iDValue": "9781234567890"
      }
    ],
    "iSNB13": "9781234567890",
    "title": {
      "titleText": "Sample Book Title",
      "subtitle": "An Example Subtitle"
    },
    "details": {
      "description": "This is a sample book description that demonstrates the structure of parsed ONIX data without revealing any actual content...",
      "shortDescription": "",
      "toc": ""
    },
    "publishing": {
      "publishingRoleCode": "01",
      "publishingRole": "Publisher",
      "publisherName": "Sample Publisher",
      "publishingStatusCode": "04",
      "publishingStatus": "Active"
    },
    "contributors": [
      {
        "contributorRoleCode": "A01",
        "contributorRole": "Author",
        "personName": "Sample Author"
      }
    ],
    "price": [
      {
        "priceTypeCode": "02",
        "currencyCode": "BRL",
        "priceAmount": "19.99",
        "countriesIncluded": ["BR"]
      }
    ],
    "priceBRL": "19.99",
    "resources": [],
    "extent": [],
    "keywords": [],
    "chapters": [],
    "categories": [],
    "language": {
      "languageCode": "por",
      "languageRole": "Language of text"
    },
    "related": [],
    "audienceRange": []
  }
}

Error Handling

The parser performs validation and returns detailed error messages:

{
  "status": false,
  "message": [
    "No ISBN-13 identifier found",
    "No title found",
    "No detail found"
  ]
}

Common validation errors:

• Invalid ONIX version (only 3.0 supported)
• Unknown ProductForm (must be EA, ED, or AJ)
• Missing required identifiers (ISBN-13)
• Missing title, description, contributors, or pricing
• No BRL pricing for Brazilian market
• Missing chapters for audiobooks

Requirements

• Node.js 8.0 or higher
• ONIX 3.0 XML files
• Digital products only (EPUB or MP3 audiobooks)

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests if applicable
4. Commit your changes: git commit -m 'Add some amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Development Setup

git clone https://github.com/henriesteves/onix-parser.git
cd onix-parser
npm install
npm test

Code Style

• Follow existing code patterns
• Add comments for complex logic
• Update documentation for API changes

Issues and Support

If you encounter any problems or have questions:

1. Check the existing issues
2. Create a new issue with:
   • Clear description of the problem
   • Sample ONIX file (if possible)
   • Expected vs actual behavior
   • Node.js version and OS

Changelog

v1.0.40

• Improved package.json metadata
• Enhanced README documentation
• Better error handling and validation

License

ISC License - see the LICENSE file for details.

Related

• ONIX for Books - Official ONIX specification
• xml-mapping - XML parsing library used internally