onix-parser
Version:
Parse ONIX 3.0 XML files and extract structured product data for publishing and digital books
347 lines (290 loc) • 8.44 kB
Markdown
[](https://badge.fury.io/js/onix-parser)
[](https://opensource.org/licenses/ISC)
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.
- ✅ 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
```bash
npm install onix-parser
```
## Usage
### Basic Example
```js
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);
}
})();
```
```js
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));
```
Parses an ONIX 3.0 XML file and returns structured product data.
**Parameters:**
- `onixFilePath` (string): Path to the ONIX XML file
**Returns:**
`Promise<OnixResult>`
```typescript
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
The parsed data includes the following main sections:
```js
{
sentDateTime: "2022-06-29 20:04",
senderName: "Publisher Name"
}
```
```js
{
identifiers: [
{
productIDTypeCode: "15",
productIDType: "ISBN-13",
iDValue: "9781234567890"
}
],
iSNB13: "9781234567890" // Convenience field for ISBN-13
}
```
```js
{
title: {
titleText: "Sample Book Title",
subtitle: "Optional Subtitle"
}
}
```
```js
{
contributors: [
{
contributorRoleCode: "A01",
contributorRole: "Author",
personName: "Sample Author",
// ... additional contributor fields
}
]
}
```
```js
{
price: [
{
priceTypeCode: "02",
priceType: "RRP including tax",
priceAmount: "29.99",
currencyCode: "BRL",
countriesIncluded: ["BR"]
}
],
priceBRL: "29.99" // Convenience field for BRL price
}
```
```js
{
details: {
description: "Book description...",
shortDescription: "Brief description...",
toc: "Table of contents..."
}
}
```
```json
{
"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": []
}
}
```
The parser performs validation and returns detailed error messages:
```js
{
"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
```bash
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](https://github.com/henriesteves/onix-parser/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](LICENSE) file for details.
## Related
- [ONIX for Books](https://www.editeur.org/83/Overview/) - Official ONIX specification
- [xml-mapping](https://www.npmjs.com/package/xml-mapping) - XML parsing library used internally