ONIX-formaatti
Kirja-alan ONIX (ONIX for Books) on tarkoitettu kirjaan liittyvien tuotetietojen sähköiseen välittämiseen kirja-alan toimijoiden kesken. Tuotetietojen siirto on tehokkaampaa ja nopeampaa, kun kaikki alan toimijat käyttävät samaa formaattia. Sovelluksen avulla vähennetään päällekkäistä työtä ja helpotetaan tiedonsiirtoa eri järjestelmien välillä. ONIXia käytetään sekä uusien tuotteiden ilmoittamisen että aiemmin julkaistujen tuotteiden tietojen päivittämiseen.
Viimeisin versio formaatista on
ONIX for Books
Product Information Format
Specification
Release 3.1, revision 2, October 2024
Viimeisin versio koodilistoista on Issue 69 (maaliskuu 2025).
Koodilistoja voit selailla
• suomeksi täällä
• englanniksi täällä
Koodilistat ovat ladattavissa tiedostoina EDItEURin nettisivuilta ja suomeksi tästä.
Suomenkielinen dokumentaatio
ONIX-spesifikaatio on käännetty suomeksi versioon 3.0.2 asti (huhtikuu 2015) ja koodilistat Issue 67 asti. Koodilistojen käännös pyritään pitämään ajan tasalla, mutta spesifikaation käännöksestä on luovuttu.
Käännöstyöhön ovat osallistuneet Kansalliskirjasto, Storia Logistikka (Kirjavälitys), Kirjastopalvelu (BTJ) sekä kustantajien, kirjakauppojen ja kirjastojen edustajat.
Ohjeita
ONIXin käyttöönotto
Sanoman rakenne
ONIX-sanoman sisältö
ONIX-elementtien nimet
Tietoelementtien järjestys ONIX-sanomassa
Tyhjät tai puuttuvat ONIX-tietoelementit
Sanoman validointi
ONIXin käyttöönotto
Tuotetietojen hallintaa ja välittämästä varten on saatavilla valmiita järjestelmiä. EDItEURin sivuilta löytyy listaus järjestelmätoimittajista.
Kun hallinnoitavien tuotteiden määrä kasvaa suureksi, kannattavin ratkaisu voi olla oman sovelluksen kehittäminen. Tuotetietojen määrä, välitettävien tietojen laajuus ja vastaanottajien vaatimukset määrittävät, millainen järjestelmä sopii parhaiten.
Sanoman rakenne
ONIX for Books on XML-pohjainen formaatti, jonka avulla voidaan välittää tietoja kirjoista ja kirjoihin liittyvistä tuotteista.
ONIX-sanoma koostuu neljästä osasta:
1. Sanoman alku
Sanoman alun muodon ja sisällön määrää XML-standardi. Se koostuu vähintään kahdesta XML-rivistä:
<?xml version="1.0"?>
<ONIXMessage release="3.1">
2. Otsikko-ryhmä
Otsikko-ryhmässä ilmoitetaan mm. sanoman lähettäjä ja lähetysaika.
<Header>
<Sender>
<SenderIdentifier>
<SenderIDType>
06</SenderIDType>
<IDValue>
6418616999993</IDValue>
</SenderIdentifier>
<SenderName>
Yrityksen nimi</SenderName>
<ContactName>
Yhteyshenkilön nimi</ContactName>
<EmailAddress>
tuotetiedot@yritys.fi</EmailAddress>
</Sender>
<Addressee>
<AddresseeName>
Vastaanottajan nimi</AddresseeName>
</Addressee>
<SentDateTime>
20240410T112819</SentDateTime>
</Header>
3. Sanoman sisältämät tuotetietueet
Tuotetietue alkaa XML-elementillä <Product> ja päättyy elementtiin </Product>. ONIX-sanoma voi sisältää yhden tai useampia tuotetietueita. Kerralla voidaan lähettää kuinka monta tietuetta hyvänsä. Spesifikaatio määrittää missä järjestyksessä osiot ja niiden sisältämät tiedot lähetetään.
<Product>
<ensimmäisen tuotetietueen ja tuotteen tunnisteet>
<osio 1, Tuotteen bibliografinen kuvaus>
<osio 2, Markkinointiaineisto>
<osio 7, Tapahtumat>
<osio 3, Tarkentavat tiedot sisällön osista>
<osio 4, Julkaisutiedot ja myyntirajoitukset>
<osio 5, Tuotteeseen liittyvät aineistot>
<osio 8, Tuotantotiedot>
<osio 6, Välitystiedot>
</Product>
4. Sanoman loppu
ONIX-sanoman loppu on rivi:
</ONIXMessage>
Katso esimerkki erilaisia julkaisumuotoja sisältävästä kokonaisesta ONIX-sanomasta
ONIX-formaatissa tuotetietoa välitetään vapaamuotoisena tekstinä ja koodilistojen avulla. Koodilistoja käytetään, jotta tuotetiedot ovat sekä lähettäjälle että vastaanottajalle mahdollisimman yksiselitteisessä muodossa. Koodilistoja päivitetään säännöllisesti ja uusia koodeja lisätään tarpeen mukaan. Koodeja myös poistetaan käytöstä tarpeettomina.
ONIX-sanoman sisältö
ONIX pyrkii kattamaan mahdollisimman laajan valikoiman kirjan toimitusketjun tarpeita, ja siksi se sisältää monia elementtejä, jotka soveltuvat vain tietyille julkaisumuodoille tai markkinoille. Millään tuotteella ei käytetä kaikkia saatavilla olevia elementtejä, ja vain pieni osa niistä on pakollisia. Ainoastaan Onixin teknisesti pakollisten elementtien välittäminen ei kuitenkaan ole riittävää.
Käytettävät elementit riippuvat välitettävistä tuotteista sekä liiketoiminnan ja toimitusketjukumppanien vaatimuksista. Yleisen kirjallisuuden kustantajan tarvitsemat tietoelementit ovat hieman erilaisia kuin akateemisen kustantajan.
Tästä tiedostosta saat listauksen ONIX-sanomilla usein käytetyistä kentistä.
Valmista järjestelmää hankittaessa on varmistettava, että se noudattaa EDItEURin ohjeita ja mahdollisia markkinakohtaisia ohjeita. Vastaanottajien järjestelmät voivat poiketa toisistaan sen suhteen, mitä tietoja ne hyödyntävät. Vastaanottajan ei kuitenkaan pitäisi koskaan hylätä validia viestiä, vaikka se sisältäisi järjestelmän kannalta ylimääräistä tietoa.
ONIX-elementtien nimet
Jokaisella ONIXin elementillä on selväkielinen nimi (esimerkiksi <PersonNameInverted>) ja sitä vastaava koodi (esimerkiksi <b037>). ONIX-skeeman mukaan sanoman tietoelementtien merkitsemiseen voidaan käyttää joko nimiä tai koodeja. Molempia ei kuitenkaan voida sekoittaa samaan sanomaan. Seuraavat kaksi esimerkkiä välittävät molemmat saman tietosisällön (kirjan ensimmäinen tekijä on Jari Tervo roolilla kirjoittaja)
<Contributor>
<SequenceNumber>
1</SequenceNumber>
<ContributorRole>
A01</ContributorRole>
<PersonNameInverted>
Tervo, Jari</PersonNameInverted>
</Contributor>
< Contributor>
<b034>
1</b034>
<b035>
A01</b035>
<b037>
Tervo, Jari</b037>
</Contributor>
Koodien käyttö tekee ONIX-tiedostoista 25-30 % pienempiä, vaikka välitettävä tietosisältö on sama. Nimien käyttö on kuitenkin suositeltavaa, sillä ne helpottavat sanoman lukemista ihmissilmin ja siten myös virheiden havaitsemista ja korjausta. ONIX 3.1:lle on olemassa sovellus, joka muuntaa nimet koodeiksi ja päinvastoin.
Tietoelementtien järjestys ONIX-sanomassa
ONIX-sanoman elementit on toimitettava skeeman määrittelemässä järjestyksessä.
Esimerkki:
<Contributor>
<SequenceNumber>
1</SequenceNumber>
<ContributorRole>
A01</ContributorRole>
<PersonNameInverted>
Tervo, Jari</PersonNameInverted>
</Contributor>
Yllä olevassa esimerkissä ContributorRole-tagin on oltava järjestyksessä ennen PersonNameInverted-tagia ja SequenceNumber-tagin jälkeen. Jos tagien järjestys on virheellinen tai joku niistä puuttuu, ONIX-sanoma ei ole oikein muodostettu, eivätkä vastaanottajat välttämättä pysty vastaanottamaan sitä.
Tyhjät tai puuttuvat ONIX-tietoelementit
Jos pakollinen elementti tai sen tietosisältö puuttuu, ONIX-sanoma ei täytä skeeman vaatimuksia eikä sitä voida lähettää lainkaan. Valinnaisen elementin puuttuminen sen sijaan ei estä sanoman lähettämistä. Esimerkiksi fyysisen kirjan tarkkoja mittoja tai äänikirjan kestoa ei varmuudella voida tietää ennen julkaisua, jolloin painoa tai selkämyksen paksuutta koskeva Measure-ryhmä tai kestoa koskeva Extent-ryhmä jätetään kokonaan pois. Kummassakaan tapauksessa ei ole sallittua lähettää tyhjää elementtiä. Sanoman validointi XSD- tai RNG-skeemalla ilmoittaa virheellisistä tyhjistä elementeistä.
Tyhjiä elementtejä voi esiintyä vain niissä poikkeustapauksissa, joissa elementti on nimenomaisesti määritetty aina tyhjäksi. Tällaisia ovat esimerkiksi MainSubject- ja NoEdition-indikaattorit. Tyhjä elementti toimitetaan muodossa <Tag/>.
Esimerkki MainSubject-indikaattorin käytöstä:
<Subject>
<MainSubject/>
<SubjectSchemeIdentifier>
93</SubjectSchemeIdentifier>
<SubjectSchemeVersion>
1.5</SubjectSchemeVersion>
<SubjectCode>
YPMF</SubjectCode>
<SubjectHeadingText>
Oppimateriaalit: matematiikka</SubjectHeadingText>
</Subject
Sanoman validointi
ONIX-sanoman tulee olla XML-standardin mukainen ja yhteensopiva EDItEURin ylläpitämässä skeemassa määritellyn rakenteen kanssa.
Skeema-tiedostot ovat
ladattavissa EDItEURin sivuilta kolmessa formaatissa: RND, XSD ja DTD. RNG- ja XSD-skeemojen avulla voidaan validoida viesti myös koodilistojen koodien osalta, mutta DTD-skeemalla ei, eikä sen käyttöä siksi suositella. Kukin skeema on saatavana kahdessa muodossa, joista toisessa on käytetty XML-elementtien nimiä (reference names) ja toisessa näitä vastaavia koodeja (short tags).
XSD-skeematiedostosta on saatavilla myös edistyneet versiot tarkkaa tiedostojen tarkistamista varten. Tiedostot sisältävät tarkempia validointisääntöjä kuin tavalliset skeematiedostot ja niiden avulla voi mm.
- tarkistaa, että tuotteen ISBN-numeron tarkistusnumero (viimeinen numero) on laskettu oikein
- tarkistaa, että SalesRights-ryhmä sisältää maa- tai aluetiedot ja että tuotteen hintojen yhteydessä ilmoitetut verotiedot (Tax-ryhmä) ovat sanomalla rakenteellisesti oikein.
- saada varoituksia poistettujen koodien tai elementtien käytöstä.
Huomioi, että skeematiedostot sisältävät myös koodilistat, joten tiedostot on ladattava aina uudestaan sen jälkeen, kun koodilistat päivittyvät.
