Inleiding

Dit document beschrijft de aanlevering van artikelgegevens van de uitgever naar Bureau ISBN en CB, deze is gebaseerd op de internationale ONIX standaard die wordt beheerd door EDItEUR. Beschreven worden de verschillende aspecten van de gegevensuitwisseling tussen uitgevers en CB met betrekking tot:

• Interpretatie van het ONIX bericht. Welke gegevens zijn nodig om welke artikelgegevens op te nemen in het artikelbestand van Bureau ISBN en CB (fysieke artikelen en e-books)?

• Omgaan met mutaties. Welke soorten mutaties kan een uitgever doorsturen op zijn titels en wanneer moet dat gebeuren?

• Verwerking en foutafhandeling. Op welke manier worden de ONIX berichten verwerkt en gecontroleerd en hoe vindt hierover terugkoppeling plaats, zowel over de technische als de inhoudelijke verwerking?

• Afspraken over de aanlevering. Op welke wijze en via welk communicatiemedium worden de berichten aangeleverd?

• Welke activiteiten rondom het onderhouden van artikelgegevens kunnen niet worden aangeleverd via ONIX?

Gebruik document

De volledige ONIX berichtdefinitie is zo opgebouwd dat de geneste structuur, met blocks, composites en elementen (tags) zichtbaar is in de inhoudsopgave. Hiermee wordt tevens de volgorde van de composites en elementen weergegeven. Vanuit de inhoudsopgave kan eenvoudig worden doorgeklikt naar de betreffende onderdelen.

Zoekadvies 

Zoeken kan het best vanuit de inhoudsopgave op hoofd- en sub-pagina of door gebruik te maken van de functietoets F3 of CTRL + F op de betreffende pagina en niet het zoekveld rechts bovenaan in het CB Wiki scherm (zie onderstaande schermprint). Het document is opgebouwd uit diverse componenten, bij zoeken via het zoekveld wordt er gezocht in de componenten database en verlaat u het document en daarmee ook het overzicht op de structuur van de gebruikershandleiding en berichtdefinitie.

Open

Uitgangsdocumentatie

De volledige documentatie betreffende de ONIX 3 standaard is te vinden en te downloaden op www.editeur.org.  In de ONIX 3 bericht standaard is een zeer groot aantal gegevens opgenomen. De gehele standaard wordt aanvaard. Voor ontwikkeling van de berichtuitwisseling gaan we uit van de onderstaande versie van de ONIX standaard:

ONIX for Books Product Information Format Specification Release 3.1. March 2025

Versie ONIX Code Lists 69

XSD Schema’s: ONIX_BookProduct_3.1_XSDs+codes_Issue_69.zip

Opbouw Product record

Beschrijving van een Data element 

Aanlevering ONIX 3 metadata en content via FTP

De uitgever krijgt bij CB de beschikking over een FTP account, via een gebruikersnaam en wachtwoord krijgt de uitgever toegang.

Een ONIX 3 bericht met metadata en eventueel daarbij behorende content wordt aangeleverd als een zip bestand. In het zip bestand zitten de metadata in de vorm van het ONIX bericht en de bijbehorende bestanden (content) waarnaar wordt verwezen in het ONIX bericht.

Voor Cover afbeeldingen geldt dat naast het originele aangeleverde formaat door CB nog in drie formaten worden opgeslagen, 1400 x 1400 pixels, 800 x 800 pixels en 150 x 150 pixels (tumbnail)

Covers en e-book bestanden zonder bijbehorend ONIX bericht indienen

Het is ook mogelijk om covers en e-book bestanden als losse bestanden in te sturen. Om dit te kunnen doen dient het ISBN aanwezig te zijn in de CB systemen en dat de commerciële aanmelding voor het CB assortiment succesvol is verwerkt. Tijdens de verwerking van de bestanden moet het ISBN kunnen worden herkend.

Verwerking van het ONIX bericht en de content

De content en het ONIX bericht met de metadata worden opgehaald van de FTP server en gescheiden verwerkt, maar in dezelfde queue geplaatst qua prioriteit.

Zodra het *_onx.zip bestand  geplaatst is op de FTP server wordt er een ontvangstbevestiging teruggeplaatst in de out-map van het ftp account.  

Vervolgens wordt het *_onx.zip bestand uitgepakt en vindt er direct een syntactische controle plaats. Het resultaat van deze controle wordt teruggekoppeld in de vorm van een .err of een .ok bestand wat in de out-map van het ftp account van de uitgever wordt geplaatst. 

Door middel van dit .ok bericht is het verband te leggen tussen de berichtidentificatie die het systeem van de uitgever heeft toegekend aan het bericht en de berichtidentificatie die het systeem van CB heeft toegekend aan het bericht.
Na de syntactische controle zullen de afzonderlijke Product records individueel verwerkt worden in de CB processen. Iedere 10 minuten wordt door het verwerkingssysteem de status van verwerking van het Product record gecheckt en waar nodig bijgewerkt. De status wordt via een O3AMLDNG (xml) bericht teruggekoppeld, wordt teruggeplaatst in de out map van het FTP account van de klant. In dit .xml bericht wordt de koppeling met het originele ONIX bericht gelegd door de interne berichtidentificatie van CB.

XSD validatie

ONIX berichten moeten qua structuur voldoen aan de algemene standaard voor XML berichten, dat wil zeggen, de berichten moeten valide XML bevatten. Bijvoorbeeld, de ‘ampersand’ en het ‘kleiner-dan’ teken hebben een specifieke betekenis binnen XML. Wanneer deze in een tekst worden gebruikt, zoals bijvoorbeeld in de titel van een boek of bij een boekbeschrijving, leidt dit tot niet valide XML.

Een ONIX bericht is opgebouwd uit voorgeschreven dataelementen in een voorgeschreven volgorde. Veel van deze dataelementen worden gevuld met waardes uit voorgeschreven codelijsten. Codelijsten kunnen worden gezien als eenduidige vocabulaires waardoor wordt bewaakt dat er bij het doorgeven van artikelgegevens in het gehele kanaal geen interpretatieverschillen en misverstanden ontstaan.

Om te garanderen dat een ONIX berichten aan de voorgeschreven opbouw van de dataelementen en inhoud voldoet zijn er schema’s ontwikkeld waarmee de validiteit van het ONIX bericht gecontroleerd kan worden. Deze schema’s zijn gratis te downloaden vanaf de website van EDItEUR, www.editeur.org. Door deze schema’s te plaatsen in een directory waar ook het te valideren bericht wordt neergezet kan met behulp van een XML editor de validatie worden uitgevoerd. Er zijn 3 verschillende schema’s in omloop waarmee het bericht gevalideerd kan worden, RNG, DTD en XSD schema. RNG en XSD valideren op basis van de combinatie van structuur van het bericht en codelijsten en hebben daarom de voorkeur.

Codelijsten

CB valideert de binnenkomende ONIX 3 berichten op basis van het XSD schema. Dat wil zeggen dat de volledige set met codes die voorkomen in de laatste issue van de codelijsten die CB heeft geimplementeerd "technisch" worden toegelaten. Dat wil niet zeggen dat CB ook al die codes actief gebruikt in de CB-systemen. De partij die het ONIX 3 artikelbericht genereert voor het melden van artikelgegevens bij CB wordt verzocht om zelf ook een validatie uit te voeren.

Reference names/long tags of short tags

Er zijn 2 systematieken om de naam van de diverse elementen in een ONIX 3.0 bericht aan te geven die equivalent aan elkaar zijn maar niet door elkaar zijn te gebruiken. Voor elk van deze 2 systematieken bestaat een specifiek validatieschema. Iedere partij die gegevens aanlevert in ONIX formaat moet een van deze twee systematieken kiezen en doorvoeren in het volledige bericht. De voorkeur van CB gaat uit naar ‘reference names’ bij deze systematieken wordt in tekst aangegeven wat de inhoud van de tag is. Het is echter ook mogelijk om gebruik te maken van ‘short tags’, hierin wordt d.m.v. een voorgeschreven codering aangegeven wat de inhoud van de tag is. CB zet ONIX 3.0 berichten met 'short tags' direct na binnenkomst om in 'reference names'. 
Bij EDItEUR is desgewenst een script verkrijgbaar om long tag berichten te converteren naar short tag berichten vice versa.

Validatie schema's

Voor informatie over het DTD schema zie: XML Standard: W3C Recommendation Extensible Markup Language (XML) 1.0 (Fourth Edition) – see http://www.w3.org/TR/xml/
Voor informatie over de XML Schema Definition (XSD) format zie W3C Recommendation XML Schema Part 1: Structures (Second Edition) – see http://www.w3.org/TR/xmlschema-1/

Het RELAX NG (RNG) format is gedefinieerd in een ISO standard: ISO/IEC 19757-2:2008, published by ISO,Geneva

Nieuwe issues van codelijsten en XSD validatie

EDItEUR publiceert een aantal keer per jaar een nieuwe uitgave (issue) van de codelijsten en XSD schema validatie waarin de nieuwe  codelijsten en waardes zijn verwerkt.
CB gaat hier als volgt mee om:

Bij nieuwe codelijst;

• Kijkt CB naar de impact

• Wordt de aanpassing/upgrade ingepland

• Wordt er 6 weken van te voren een aankondiging aan de ONIX-gebruikers

• Bij een versie overgang ondersteunt CB tijdelijk 2 versies

• Voor uitgaande ONIX-berichten wordt de meest recente verstrekt 

Wie mag wat indienen?

In het ONIX bericht wordt op twee plaatsen informatie meegeleverd die in de verwerking wordt gebruikt om te controleren dat de indiener van het bericht mag optreden namens de eigenaar van het ISBN. In het Message Header record zit de relatie die het bericht indient. In het Product record zit de relatie die de eigenaar van het artikel is of wordt.

Prefixhouder en commerciële eigenaar van het artikel

We kennen twee relaties tussen een uitgever en een artikel, de twee relaties hoeven niet hetzelfde te zijn:

1. Aan een artikel is altijd een prefixhouder gekoppeld. De prefixhouder is eigenaar van een prefixrange waarbinnen ISBN’s worden uitgegeven. Deze prefixhouder wordt geregistreerd door Team ISBN. 

2. Als een artikel tot het CB assortiment behoort, is er tevens een artikel eigenaar. De artikeleigenaar heeft het artikel in eigendom en is degene voor wie CB dienstverlening verricht.

In principe is het zo dat alleen de prefixhouder een ISBN registratie mag aanmelden. De prefixhouder moet bij CB aangeven wie eigenaar wordt van het artikel. In de praktijk blijkt dat met name binnen concerns artikelen worden aangemeld door uitgevers die niet zelf de prefixhouder van het ISBN zijn.

Voorbeeld: Uitgeverij A en B vallen beide binnen concern Z. Een artikel valt binnen de prefixrange van uitgeverij A, maar wordt door uitgeverij B als artikel in het assortiment opgenomen en verkocht aan de boekhandel. Om het artikel automatisch te kunnen verwerken moet vastgelegd worden wat de relatie is tussen uitgever A en uitgever B.

Bij de verwerking van de ISBN registratie en de aanmelding voor het CB assortiment is voor de volgende oplossing gekozen:

• Uit het ISBN is de prefix af te leiden en daarmee de prefixhouder.

• Een ISBN registratie mag alleen door de prefixhouder worden uitgevoerd, of als de indiener van het bericht met de prefixhouder van het artikel een commissionairrelatie heeft.

• Een uitgever mag een titel bij CB aanmelden indien hij prefixhouder is, of als hij met de prefixhouder van het artikel een commissionairrelatie heeft.

• Een uitgever mag artikelgegevens wijzigen indien hij eigenaar is van het artikel, of met de eigenaar van het artikel een commissionairrelatie heeft.

• Bij het indienen van het bericht wordt per artikelrecord gecontroleerd of de registratie en/of aanmelding of de wijziging door de betreffende indiener mag worden uitgevoerd. Indien dit niet het geval is, wordt het productrecord niet verwerkt.

De controles zijn:

• Mag de indiener van het bericht ISBN’s aanmelden voor deze prefixhouder?

• Mag de indiener van het bericht titels aanmelden voor deze eigenaar voor het assortiment van CB?

• Mag de eigenaar die bij het product record is aangegeven titels aanmelden voor het assortiment van het CB van de prefixhouder van het ISBN?

Een titel enkel aanmelden voor ISBN registratie

Om een titel enkel aan te melden voor ISBN registratie en niet op te laten nemen in het CB assortiment dienen de blokken DescriptiveDetail,  PublishingDetail en het blok ProductSupply te worden opgenomen in het ONIX ProductRecord. In het blok ProductSupply dient element SupplierName een andere waarde dan CB te bevatten, bijvoorbeeld <SupplierName>@@</SupplierName>.

Samenhang Levenscyclus en verschijningsdatum - Statusovergangen

Uitgevers kunnen via ONIX artikelmutaties doorgeven op o.a. de prijs en het stadium levenscyclus (de beschikbaarheidsstatus) van een titel. Als een uitgever een titel voor het eerst aanmeldt voor opname in het CB assortiment wordt deze altijd opgenomen met stadium levenscyclus Aangekondigd en stadium dienstverlening In voorbereiding, ongeacht de meegegeven ProductAvailability.

Daarbij controleert CB in de verwerking op een aantal zaken:

• De waarde voor ProductAvailability moet identiek zijn aan het actuele stadium levenscyclus van de titel, of moet een toegestane statusovergang van het actuele stadium levenscyclus aangeven

• Bij aangekondigde titels en herdrukken moet de SupplyDate in de toekomst liggen

• Bij een prijswijziging moet de ingangsdatum van de prijs in de toekomst liggen

• Als er geen prijswijziging wordt doorgegeven moet de ingangsdatum van de prijs overeenkomen met de ingangsdatum van de prijs die in het assortimentssysteem van CB zit.

ONIX kent geen element/tag voor de ingangsdatum van een statusovergang in de toekomst. CB zal een statusovergang daarom standaard laten ingang op 1 dag na de systeemdatum.
De PublicationDate en de SupplyDate moeten bij een aangekondigde titel in de toekomst liggen. Bij een herdruk moet de SupplyDate in de toekomst liggen.

Doorgeven van akkoord voor vrijgave

Voor het vrijgeven (= beschikbaar stellen voor uitlevering) van zowel fysieke boeken als e-books is toestemming nodig van de uitgever. Deze toestemming heet vrijgave-akkoord. Dit vrijgave-akkoord kan direct worden meegegeven bij de commerciële aanmelding of kan ook achteraf door de uitgever worden gegeven.

Het doorgeven van een vrijgave-akkoord kan plaatsvinden d.m.v. een mutatierecord in het ONIX bericht. De werkwijze daarvoor is als volgt:

Vrijgeven op een specifieke datum vanwege embargo en pre-sales

Het is mogelijk om ook via ONIX 3.0 aan te geven dat een fysiek boek of e-book pas mag worden uitgeleverd vanaf een door de uitgever bepaalde, specifieke datum. Dit gebeurt door het aangeven van een “MarketDate” in block 6 Product Supply. (P.25)