EDItEUR logo

ONIX Serials Online Holdings Message Formats

Version 1.0 User Guide

This User Guide has been prepared for the EDItEUR / NISO Joint Working Party for the Exchange of Serials Subscription Information by Tim Devenport, David Martin and Francis Cave. It is designed to accompany a machine-readable specification of the formats written in XML Schema, which has been developed by Francis Cave.

Copyright © 2003 EDItEUR Limited. All rights reserved.

The structural diagrams have been produced using XML Spy™ from Altova GmbH.

General guidance on schema use
Guidance on reading the message format specifications
Introduction
ONIX Serials Online Holdings A-to-Z
ONIX Serials Online Holdings A-to-Z sample messages
ONIX Serials Online Holdings By-Host
ONIX Serials Online Holdings By-Host sample messages
Common Components

General guidance on schema use

This schema provides a formal specification of what constitutes valid use of XML to construct ONIX Serials Online Holdings (SOH) messages. As well as specifying the XML tags that may be used and in what sequence, it also specifies valid ranges of data values for data contained in XML elements, i.e. between matching pairs of XML tags.

The schema to which this document refers comprises four files which together form an XML document that conforms to the XML Schema Recommendation of the World Wide Web Consortium (W3C). The four files are:

Filename   Description of content
ONIXSerialsOnlineHoldings_n.n.xsd   definitions of the message-level element and of complex types specific to SOH messages (the number 'n.n' is the version number of this schema)
ONIXSerials-datatypes.xsd   definitions of datatypes common to all ONIX Serials schemas.

For further information see XML Schema Part 1: Structures and XML Schema Part 2: Datatypes.

It is intended that this schema be used to guide implementation of systems for either originating or receiving SOH messages. Used in conjunction with a suitable “schema parser” it may also be used to validate the structure and contents of an individual message.

This schema defines how the substance, or “payload”, of SOH messages are to be represented in XML, but is silent on the question of how this message is to be conveyed from originator to recipient. It is likely that supply chain partners will need to adopt different approaches to message transport, packaging and delivery, depending upon the specific business systems in which this message format is being implemented.

Guidance on reading the message format specifications

In this user guide each successive XML element is illustrated by a graphic which shows any “child” elements. Clicking on any “child” element will take you to the description of that element. Clicking “Back” will return you to the “parent”.

If a “child” element is shown with a solid outline, the element is mandatory in any occurrence of the “parent”. If it is shown with a dotted outline, it is conditional in this context. If it is repeatable, the element box has the legend “1..∞” or “0..∞” immediately below it, indicating “mandatory and repeatable” or “conditional and repeatable”.

All data types are based upon built-in primitive data types defined in XML Schema Part 2: Datatypes. The names of all pre-defined data types are prefixed by “xs:” and include:

xs:string a string of characters
xs:decimal a number that may have a decimal part
xs:int an integer between -2147483648 and +2147483647 inclusive

Introduction

The ONIX Serials Online Holdings (SOH) format is designed to convey information between business partners about library holdings of online serial resources. Typically, the format may be used for messages sent by publication access management services (PAMS), by subscription agents, by hosting or gateway services or indeed directly from publishers. The intended recipients are libraries or other corporate or institutional customers, who need reliable information about the online services they have purchased and the possible access routes available to them.

The ONIX SOH format facilitates information exchange down to the level of each particular manifestation of a serial title. Thus, for example, the message can distinguish between versions of the same title in different electronic file formats (such as XML and HTML), from different hosting services, and at different levels of completeness (such as full content vs. abstracts only). The ranges of each of these “serial versions” held by a particular library can be separately specified, as can any embargo that may apply. In Version 1.0 it is not possible to carry structured information on licence terms, but a free text statement may be included. It is envisaged that this functionality will be further developed in a future release.

The ONIX SOH format is used for two different message types:

[More comprehensive introductory text will be provided as necessary, in the light of feedback from early pilots.]

ONIX Serials Online Holdings A-to-Z

Introduction

The ONIX Serials Online Holdings (SOH) message is designed to convey information between business partners about library holdings of online serial resources. Typically, the message may be sent by publication access management services (PAMS), by subscription agents, by hosting or gateway services or indeed directly from publishers. The intended recipients are libraries or other corporate or institutional customers, who need reliable information about the online services they have purchased and the possible access routes available to them.

The SOH message facilitates information exchange down to the level of each particular manifestation of a serials title. Thus, for example, the message can distinguish between versions of the same title in different formats (such as XML and HTML), from different hosting services, and at different levels of completeness (such as full content vs. abstracts only). The ranges of each of these “serial versions” held by a particular library can be separately specified, as can any embargo or license terms that apply to each.

The A-Z listing supports one particular type of holdings list. In this case, the SOH format details, serial version by serial version, the holdings of one particular customer. Comprehensive information is provided of the online service provider(s) involved, but the information is typically provided in a flat, title-by-title order.

(This structure contrasts with the hierarchical listing by host supported by an alternate SOH format and described elsewhere in this document.)

[More comprehensive introductory text will be provided as necessary, in the light of feedback from early pilots.]

Sample messages

The ONIX Serials Online Holdings (SOH) message is designed to convey information between business partners about library holdings of online serial resources. Typically, the message may be sent by publication access management services (PAMS), by subscription agents, by hosting or gateway services or indeed directly from publishers. The intended recipients are libraries or other corporate or institutional customers, who need reliable information about the online services they have purchased and the possible access routes available to them.

The SOH message facilitates information exchange down to the level of each particular manifestation of a serials title. Thus, for example, the message can distinguish between versions of the same title in different formats (such as XML and HTML), from different hosting services, and at different levels of completeness (such as full content vs. abstracts only). The ranges of each of these “serial versions” held by a particular library can be separately specified, as can any embargo or license terms that apply to each.

The A-Z listing supports one particular type of holdings list. In this case, the SOH format details, serial version by serial version, the holdings of one particular customer. Comprehensive information is provided of the online service provider(s) involved, but the information is typically provided in a flat, title-by-title order.

(This structure contrasts with the hierarchical listing by host supported by an alternate SOH format and described elsewhere in this document.)

[More comprehensive introductory text will be provided as necessary, in the light of feedback from early pilots.]

[Sample messages will be added to this documentation as pilots proceed and the message format becomes less volatile.]

Message specification

<ONIXSerialsOnlineHoldingsAtoZ>

<ONIXSerialsOnlineHoldingsAtoZ> is the first and mandatory element in the opening "wrapper" of a message, specifying in this case an ONIX SOH format applied to a "flat" or A-Z listing of transactions.

Used in this way, the SOH format details, one by one, the serials holdings of a particular customer. Alongside other metadata describing the serial title and versions to which they relate, there is information regarding the online service that hosts the serial resource.

If it is more appropriate to group serial resources by online hosting service, then the <OnlineSerialsHoldingsByHost> construction, detailed elsewhere, may be used instead.

<ONIXSerialsOnlineHoldingsAtoZ> <Header>

The <Header> comprises a mandatory group of elements that identifies and provides administrative information about the message as a whole.

This composite identifies senders and receivers, including the provision for a structured <LibraryIdentifier> if business partners agree to follow this approach. It also carries a sequence number to enable tracking of exchanges, a date and time stamp, and an indication of whether the message conveys a complete or incremental update list of information.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList>

<HoldingsList> comprises a mandatory group of elements that describes the serials holdings of a particular customer and the serial titles and versions to which they relate.

In the A-Z listing, this composite is limited to one occurrence per message.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService>

<OnlineService> comprises a mandatory and repeatable group of elements that identifies and provides URLs for a host, gateway or other supplier of online resources.

In the A-Z listing, there is one occurrence of this composite for each of the online services declared at the start of the message.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <OnlineServiceName>

<OnlineServiceName> is a mandatory element to show the name of a particular online service and to link individual online holdings with the online services where they are held or accessed.

Example: Ingenta

There must be one, and only one, instance of the online service name within each occurrence of the <OnlineService> composite.

To accurately link online holdings with the correct online services, only controlled values matching those used for <OnlineServiceName> within the <OnlinePackage> composite must be used. Note however that a list of controlled values has yet to be defined.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher>

<Publisher> comprises an optional group of data elements that identifies an entity associated with the publishing of a serial and the role of that entity in the publishing process or supply chain.

The composite specifies, in this context, the particular <PublishingRole> of the entity as supplier of an online access service.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublishingRole>

<PublishingRole> is a code specifying the role played by an entity in the publishing of a product.

Example: 05

<PublishingRole> is mandatory within each instance of the <Publisher> composite and here only one code value is permissible:

05     Supplier of an online access service

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherIdentifier>

<PublishingIdentifier> is an optional and non-repeating (?) group of elements that defines an identifier of a publisher.

This composite enables business partners to take advantage of structured authority lists, namespaces or schemas, as well as free-text names or descriptions.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherIdentifier> <PublisherIDType>

<PublisherIDType> is a code identifying the namespace or scheme from which an identifier of a publisher is taken. The code is mandatory within each repeat of the <Publisher> composite and is non-repeating.

Example: 01

Only one code value has yet been defined:

01     Proprietary

The name of the scheme or of its owner may be sent as <IDTypeName>.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherIdentifier> <IDTypeName>

<IDTypeName> is an element signalling a proprietary publisher identifier code. The element is optional and non-repeating. It is only used when the <PublisherIDType> has the value 01, denoting a proprietary scheme.

EXAMPLE PLEASE?

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherIdentifier> <IDValue>

<IDValue> carries an identifier of the type specified in the <PublisherIdentifierIDType>. The element is mandatory within each repeat of the <PublisherIdentifier> composite and is non-repeating.

EXAMPLE PLEASE?

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherName>

<PublisherName> carries the name of an entity associated with the publishing of a product.

Example: Highwire Press

Here <PublisherName> refers specifically to an entity in the <PublishingRole> of supplier of an online access service. Either <PublisherName> or <PublisherIdentifier> or both must be present in each occurrence of the <Publisher> composite.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Publisher> <PublisherName>

<PublisherName> carries the name of an entity associated with the publishing of a product.

Example: Highwire Press

Here <PublisherName> refers specifically to an entity in the <PublishingRole> of supplier of an online access service. Either <PublisherName> or <PublisherIdentifier> or both must be present in each occurrence of the <Publisher> composite.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Website>

<Website> comprises an optional and repeatable group of data elements that identifies, describes and provides pointers to a website.

Here the website composite relates to the online service as a whole, rather than journal-specific URLs.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Website> <WebsiteRole>

<WebsiteRole> is a code that is mandatory and non-repeating within each occurrence of the <Website> composite, indicating the primary role of the website.

Example: 03

Two code values are valid here:

00     Unspecified, see <WebsiteDescription>

03     Home page of the online access service

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <OnlineService> <Website> <WebsiteDescription>

<WebsiteDescription> is a free-text element, optional and non-repeating, describing the nature or function of the website linked through <WebsiteLink>.

EXAMPLE PLEASE?

<WebsiteLink> is an element conveying the URL for a website. <WebsiteLink> is mandatory within each occurrence of the <Website> composite and non-repeating.

Example: http://xyz.com/welcome.htm

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord>

<HoldingsRecord> comprises a group of elements that describes the online holdings of a specified serial version for a particular customer. <HoldingsRecord> is mandatory and repeatable.

The holdings record carries the majority of the information within an ONIX SOH format, including metadata at the work, title and version level, links to the online service providers, and detailed specifications of the holdings ranges, formats and content.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <RecordReference>

<RecordReference> provides a unique identifier of a holdings record assigned by the sender and used for successive updates. <RecordReference> is mandatory and non-repeating.

Example: 9876543

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <NotificationType>

<NotificationType> is a mandatory and non-repeating element specifying the type of notification conveyed.

Example: 07

This element supplies part of the administrative infrastructure for message exchange, and four code values are valid in this context:

00     Unspecified: complete record, may be new or updated: use only when sending a complete replacement file

05     Deletion: the holdings record under this reference is no longer valid

06     New: first notification of a new holdings record

07     Update: complete reissue of a holdings record previously sent, usually but not necessarily with amendments

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion>

<SerialVersion> comprises a group of elements that identifies and describes a particular version of a serial publication.

<SerialVersion> is mandatory in each <OnlineHoldingsRecord>; it is not repeatable in this context, since each holdings record can apply only to one serial version.

It is important to understand that, in ONIX, a <SerialVersion> relates to a particular manifestation of a serial work, for example the online, PDF-format version of a named journal. Relative to this example, the printed version of the same journal would correspond to a different <SerialVersion>, as would another online version containing only the text of the journal articles but not the associated images. A print-plus-online combination for the same journal could well be a subscription product; but it is not itself a <Serial Version> though it may contain two or more such versions.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <SerialVersionIdentifier>

<SerialVersionIdentifier> comprises a group of elements that specifies an identifier of a particular version of a serial publication.

<SerialVersionIdentifier> is required unless the serial version has no unique identifier (e.g., it is identified only by the same identifier assigned to both print and electronic versions, plus a product form code). If there are two or more identifiers of different types then <SerialVersionIdentifier> is repeatable.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <SerialVersionIdentifier> <SerialVersionIDType>

<SerialVersionIDType> is a code identifying the namespace or scheme from which an identifier of a serial version is taken. This is mandatory within each occurrence of the <SerialVersionIdentifier> composite, and non-repeating.

Example: 07

Two code values are defined:

01     Proprietary: the name of the scheme or of its owner may be sent as <IDTypeName>

07     ISSN (always sent unhyphenated in ONIX)

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <SerialVersionIdentifier> <IDTypeName>

<IDTypeName> is an element signalling a proprietary serial version identifier code. This is optional and non-repeating, and is used only when <SerialVersionIDType> takes the proprietary code value 01.

EXAMPLE PLEASE?

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <SerialVersionIdentifier> <IDValue>

<IDValue> carries an identifier of the type specified in the <SerialVersionIdentifierIDType>. This is mandatory within each occurrence of the <SerialVersionIdentifier> composite and non-repeating.

Example: 00068950

This example shows an ISSN (always sent unhyphenated in ONIX).

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Title>

<Title> comprises a group of data elements that carries the title of a <SerialVersion>, including a subtitle where applicable, and specifies its type. This composite is optional, and is repeatable only if there is a need to send more than one form of the title.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Title> <TitleType>

<TitleType> is a code indicating the type of a title. The code is mandatory in each occurrence of the <Title> composite and non-repeating.

Example: 01

The following code values are valid in this context:

00     Unspecified: use only if the source from which the title is taken is such that the title cannot be properly specified

01     Cover title

02     ISSN key title: use only if the key title has been taken from an authoritative ISSN source

04     Title acronym

05     Abbreviated cover title

06     Title in original language (for a translated journal)

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Title> <TitleText>

<TitleText> carries the text of the title specified in <TitleType>. This element is mandatory in each occurrence of the <Title> composite and non-repeating.

Example: Brain

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Title> <Subtitle>

<Subtitle> carries the full text of the subtitle, if any, for the <SerialVersion> described in the <Title> composite. This element is optional and non-repeating.

CONTRIVED example: Research into brain function and brain disorder.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher>

<Publisher> comprises a group of data elements that identifies an entity associated with the publishing of a serial and the role of that entity in the publishing process or supply chain. This composite is mandatory and is repeatable only if the journal has two or more co-publishers.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublishingRole>

<PublishingRole> is a code specifying the role played by an entity in the publishing of a product. <PublishingRole> is mandatory within each instance of the <Publisher> composite and non-repeating.

Example: 01

In this context, only one code value is permissible:

01     Publisher

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherIdentifier>

<PublisherIdentifier> comprises an optional and non-repeating group of elements that defines an identifier of a publisher.

This composite enables business partners to take advantage of structured authority lists, namespaces or schemas, as well as free-text names or descriptions.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherIdentifier> <PublisherIDType>

<PublisherIDType> is a code identifying the namespace or scheme from which an identifier of a publisher is taken. This code is mandatory in each occurrence of the <PublisherIdentifier> composite.

Example: 01

Only one code value has yet been defined:

01     Proprietary

The name of the scheme or of its owner may be sent as <IDTypeName>.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherIdentifier> <IDTypeName>

<IDTypeName> identifies a proprietary publisher identifier code. This is optional and non-repeating.

EXAMPLE PLEASE?

The code is used only when the <PublisherIDType> is proprietary (code 01), to specify whose scheme it is.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherIdentifier> <IDValue>

<IDValue> carries an identifier of the type specified in the <PublisherIdentifierIDType>.

EXAMPLE PLEASE?

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherName>

<PublisherName> carries the name of an entity associated with the publishing of a product. Either <PublisherName> or <PublisherIdentifier> or both must be present in each occurrence of the <Publisher> composite.

Example: Oxford University Press

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <Publisher> <PublisherName>

<PublisherName> carries the name of an entity associated with the publishing of a product. Either <PublisherName> or <PublisherIdentifier> or both must be present in each occurrence of the <Publisher> composite.

Example: Oxford University Press

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage>

<OnlinePackage> comprises a group of elements that describes a serial version holdings package accessible either at a specified host service or at an independent site specific to that serial resource. This composite is mandatory in each occurrence of <SerialVersion>. It is repeatable if the customer has access to the same serial via more than one site.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <OnlineServiceName>

<OnlineServiceName> is a controlled-text element to show the name of a particular online service and to link individual online holdings with the online services where they are held or accessed. Either <OnlineServiceName> or the empty element <NoOnlineService/> must be present. The element is non-repeating.

Example: EBSCOHost

A list of controlled values is still to be defined.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <NoOnlineService>

<NoOnlineService/> is a so-called empty element preceding a list of titles that do not reside on a named host. Either <OnlineServiceName> or the empty element <NoOnlineService/> must be present. The element is non-repeating.

This element is used to give a positive indication that the serial version concerned is accessed at its own independent site and not via another named online service.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <Website>

<Website> comprises a group of data elements that identifies, describes and provides pointers to a website. This composite is optional and repeatable.

Here the website composite relates to one or more journal-specific URLs, rather than any online service itself.

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <Website> <WebsiteRole>

<WebsiteRole> is a code indicating the primary role of the website. This is mandatory within each occurrence of the <Website> composite and is non-repeating.

Example: 04

Three code values are valid here:

00     Unspecified, see <WebsiteDescription>

03     Home page of the online access service: use here only if there is no journal-specific web address

04     Journal home page

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <Website> <WebsiteDescription>

<WebsiteDescription> is a free-text element describing the nature or function of the website linked through <WebsiteLink>. This is optional and non-repeating.

EXAMPLE PLEASE?

<WebsiteLink> is an element conveying the URL for a website. This is mandatory within each occurrence of the <Website> composite and non-repeating.

CONTRIVED Example: http://xy.com/journals/neurology.htm

<ONIXSerialsOnlineHoldingsAtoZ> <HoldingsList> <HoldingsRecord> <SerialVersion> <OnlinePackage> <HoldingsDetail>