XML Response

Each XML document response will:

  • echo the API version and the client query
  • provide diagnostics as appropriate
  • report the results and some data derived from the query that can be used, for example, for detecting circular links.

The schema file provides the formal definition of the output to be generated.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:dcterms="http://purl.org/dc/terms/"
   xmlns:dc="http://purl.org/dc/elements/1.1/"
   xmlns:ssdiag="http://xml.serialssolutions.com/ns/diagnostics/v1.0" elementFormDefault="qualified"
   targetNamespace="http://xml.serialssolutions.com/ns/openurl/v1.0"
   xsi:schemaLocation="http://xml.serialssolutions.com/ns/openurl/v1.0 ssopenurl.xsd "
   xmlns:ssopenurl="http://xml.serialssolutions.com/ns/openurl/v1.0">

   <xs:annotation>
      <xs:documentation xml:lang="en"> Schema definition for Serials Solutions' OpenURL Link Resolver
         XML API. This schema defines the data elements returned in response to an openURL request.
      </xs:documentation>
   </xs:annotation>

   <xs:import namespace="http://purl.org/dc/elements/1.1/"
      schemaLocation="http://dublincore.org/schemas/xmls/qdc/2006/01/06/dc.xsd"/>
   <xs:import namespace="http://purl.org/dc/terms/"
      schemaLocation="http://dublincore.org/schemas/xmls/qdc/2006/01/06/dcterms.xsd"/>
   <xs:import namespace="http://xml.serialssolutions.com/ns/diagnostics/v1.0"
      schemaLocation="http://xml.serialssolutions.com/ns/diagnostics/v1.0/diagnostics.xsd"/>

   <xs:element name="openURLResponse">
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="1" maxOccurs="1" ref="ssopenurl:version"/>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssdiag:diagnostics"/>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:derivedQueryData"/>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:results"/>
            <xs:element minOccurs="1" maxOccurs="1" ref="ssopenurl:echoedQuery"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <!-- The version of the XML API interface this response is compatible with -->
   <xs:element name="version" type="xs:string"/>

   <!-- Data derived from the openURL query provided -->
   <xs:element name="derivedQueryData">
      <xs:complexType>
         <xs:sequence>
            <!-- identifier of the provider that was the source of the query -->
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:providerId"/>
            <!-- identifier of the database that was the source of the query -->
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:databaseId"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <!-- Unique Serials Solutions identifier for a content provider -->
   <xs:element name="providerId" type="xs:string"/>
   <!-- Unique Serials Solutions identifier for a database -->
   <xs:element name="databaseId" type="xs:string"/>

   <!-- Container for the response to the openURL query -->
   <xs:element name="results">
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="1" maxOccurs="unbounded" ref="ssopenurl:result" />
         </xs:sequence>
         <!-- dbDate is the date when the database was last updated.  Format: YYYY-MM-DD.-->
         <xs:attribute name="dbDate" type="xs:date" use="required"/>
      </xs:complexType>
   </xs:element>

   <!-- Container for a citation and its groups of links -->
   <xs:element name="result">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="ssopenurl:citation"/>
            <xs:element minOccurs="0" ref="ssopenurl:linkGroups"/>
         </xs:sequence>
         <xs:attribute name="format" use="required">
            <xs:simpleType>
               <xs:restriction base="xs:string">
                  <xs:enumeration value="journal"/>
                  <xs:enumeration value="book"/>
                  <xs:enumeration value="patent"/>
                  <xs:enumeration value="dissertation"/>
                  <xs:enumeration value="unknown"/>
               </xs:restriction>
            </xs:simpleType>
         </xs:attribute>
      </xs:complexType>
   </xs:element>

   <!-- Metadata about the the resource being referred to in the OpenURL -->
   <xs:element name="citation">
      <xs:complexType>
         <xs:sequence>
            <!-- The title of the resource being referred to -->
            <xs:element minOccurs="0" ref="dc:title"/>
            <!-- The creator (author, artist, etc.) of the resource being referred to -->
            <xs:element minOccurs="0" ref="dc:creator"/>
            <!-- First name of the creator -->
            <xs:element minOccurs="0" ref="ssopenurl:creatorFirst"/>
            <!-- Middle name or initial of the creator -->
            <xs:element minOccurs="0" ref="ssopenurl:creatorMiddle"/>
            <!-- Last name of the creator -->
            <xs:element minOccurs="0" ref="ssopenurl:creatorLast"/>
            <!-- Name of the source of the resource being referred to -->
            <xs:element minOccurs="0" ref="dc:source"/>
            <!-- Date of publication -->
            <xs:element minOccurs="0" ref="dc:date"/>
            <!-- an ISSN associated with the resource -->
            <xs:element minOccurs="0" maxOccurs="unbounded" ref="ssopenurl:issn"/>
            <!-- an SIBN associated with the resource -->
            <xs:element minOccurs="0" maxOccurs="unbounded" ref="ssopenurl:isbn"/>
            <!-- volume in which the resource being referred to appears -->
            <xs:element minOccurs="0" ref="ssopenurl:volume"/>
            <!-- issue in which the resource being referred to appears -->
            <xs:element minOccurs="0" ref="ssopenurl:issue"/>
            <!-- starting page of the resource being referred to -->
            <xs:element minOccurs="0" ref="ssopenurl:spage"/>
            <!-- Document Object Identifier for the resource being referred to -->
            <xs:element minOccurs="0" ref="ssopenurl:doi"/>
            <!-- PubMed identifier for the resource being referred to -->
            <xs:element minOccurs="0" ref="ssopenurl:pmid"/>
            <!-- publisher of the source this resource -->
            <xs:element minOccurs="0" ref="dc:publisher"/>
            <!-- place of publication of the source this resource -->
            <xs:element minOccurs="0" ref="ssopenurl:publicationPlace"/>
            <!-- institution associated with this resource -->
            <xs:element minOccurs="0" ref="ssopenurl:institution"/>
            <!-- name of the advisor associated with this resource (disseratation) -->
            <xs:element minOccurs="0" ref="ssopenurl:advisor"/>
            <!-- patent number associated with this resource -->
            <xs:element minOccurs="0" ref="ssopenurl:patentNumber"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <!-- and ISSN for a resource -->
   <xs:element name="issn">
      <xs:complexType>
         <xs:simpleContent>
            <xs:extension base="xs:string">
               <xs:attribute name="type" use="required">
                  <xs:simpleType>
                     <xs:restriction base="xs:string">
                        <xs:enumeration value="print"/>
                        <xs:enumeration value="electronic"/>
                     </xs:restriction>
                  </xs:simpleType>
               </xs:attribute>
            </xs:extension>
         </xs:simpleContent>
      </xs:complexType>
   </xs:element>

   <!-- an ISBN for a resource -->
   <xs:element name="isbn" type="xs:string"/>
   <!-- volume in which the resource being referred to appears -->
   <xs:element name="volume" type="xs:string"/>
   <!-- issue in which the resource being referred to appears -->
   <xs:element name="issue" type="xs:string"/>
   <!-- starting page of the resource being referred to -->
   <xs:element name="spage" type="xs:string"/>
   <!-- Document Object Identifier for the resource being referred to -->
   <xs:element name="doi" type="xs:string"/>
   <!-- PubMed identifier for the resource being referred to -->
   <xs:element name="pmid" type="xs:string"/>
   <!-- place of publication of the source this resource -->
   <xs:element name="publicationPlace" type="xs:string"/>
   <!-- institution associated with this resource -->
   <xs:element name="institution" type="xs:string"/>
   <!-- name of the advisor associated with this resource (disseratation) -->
   <xs:element name="advisor" type="xs:string"/>
   <!-- patent number associated with this resource -->
   <xs:element name="patentNumber" type="xs:string"/>
   <!-- First name of the creator -->
   <xs:element name="creatorFirst" type="xs:string"/>
   <!-- Last name of the creator -->
   <xs:element name="creatorLast" type="xs:string"/>
   <!-- Middle name or initial of the creator -->
   <xs:element name="creatorMiddle" type="xs:string"/>

   <!-- collection of groups of links associated with a resource -->
   <xs:element name="linkGroups">
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="1" maxOccurs="unbounded" ref="ssopenurl:linkGroup" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <!-- Group of links associated with a resource -->
   <xs:element name="linkGroup">
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="0" ref="ssopenurl:holdingData"/>
            <xs:element minOccurs="1" maxOccurs="unbounded" ref="ssopenurl:url"/>
         </xs:sequence>
         <xs:attribute name="type" use="required">
            <xs:simpleType>
               <xs:restriction base="xs:string">
                  <xs:enumeration value="holding"/>
                  <xs:enumeration value="termsOfUse"/>
               </xs:restriction>
            </xs:simpleType>
         </xs:attribute>
      </xs:complexType>
   </xs:element>

   <!-- Data about a holding associated with a resource -->
   <xs:element name="holdingData">
      <xs:complexType>
         <xs:sequence>
            <!-- starting date of the holding -->
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:startDate"/>
            <!-- ending date of the holding -->
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:endDate"/>
            <!-- identiefier of the provider from which this holding comes -->
            <xs:element ref="ssopenurl:providerId"/>
            <!-- name of the provider from which this holding comes -->
            <xs:element ref="ssopenurl:providerName"/>
            <!-- identiefier of the database from which this holding comes -->
            <xs:element ref="ssopenurl:databaseId"/>
            <!-- name of the database from which this holding comes -->
            <xs:element ref="ssopenurl:databaseName"/>
            <!-- normalized starting and ending dates -->
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:normalizedData"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <xs:element name="startDate" type="xs:string"/>
   <xs:element name="endDate" type="xs:string"/>
   <xs:element name="databaseName" type="xs:string"/>
   <xs:element name="providerName" type="xs:string"/>
  
   <!-- container for normalized data about a holing or citation -->
   <xs:element name="normalizedData" >
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:startDate"/>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:endDate"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <!-- link created related to a resource -->
   <xs:element name="url">
      <xs:complexType>
         <xs:simpleContent>
            <xs:extension base="xs:anyURI">
               <xs:attribute name="type" use="required">
                  <xs:simpleType>
                     <xs:restriction base="xs:string">
                        <xs:enumeration value="source"/>
                        <xs:enumeration value="article"/>
                        <xs:enumeration value="journal"/>
                        <xs:enumeration value="volume"/>
                        <xs:enumeration value="issue"/>
                        <xs:enumeration value="termsOfUse"/>
                     </xs:restriction>
                  </xs:simpleType>
               </xs:attribute>
            </xs:extension>
         </xs:simpleContent>
      </xs:complexType>
   </xs:element>

   <!-- data about the query that was made to produce the results -->
   <xs:element name="echoedQuery">
      <xs:complexType>
         <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" ref="ssopenurl:library"/>
            <xs:element ref="ssopenurl:queryString"/>
         </xs:sequence>
         <xs:attribute name="timeStamp" type="xs:dateTime" use="required"/>
      </xs:complexType>
   </xs:element>

   <!-- data about the library making the query -->
   <xs:element name="library">
      <xs:complexType>
         <!-- name of the library -->
         <xs:sequence>
            <xs:element ref="ssopenurl:name"/>
         </xs:sequence>
         <!-- unique Serials Solutions identifier for this library -->
         <xs:attribute name="id" use="required"/>
      </xs:complexType>
   </xs:element>

   <xs:element name="name" type="xs:string"/>

   <xs:element name="queryString" type="xs:string"/>
</xs:schema>

Further explanation of the derived query data and results metadata is provided in below.

Derived Query Data

This table details the elements returned in the ssopenurl:derivedQueryData element. These elements, and indeed the ssopenurl:derivedQueryData element itself, are optional.

MetadataElementDescription
Referrer Provider Identifierssopenurl:providerIdUnique Ex Libris identifier for the provider that was the source of this OpenURL query. This data is derived from the sid OpenURL parameter.
Referrer Database Identifierssopenurl:databaseIdUnique Ex Libris identifier for the database that was the source of this OpenURL query. This data is derived from the sid OpenURL parameter.

 

Results Data

The ssopenurl:results element consists of a series of ssopenurl:result elements.

Each ssopenurl:result element consists of a ssopenurl:citation element.

The ssopenurl:citation element contains 1) the metadata about the resource being referenced in the OpenURL query, and 2) an optional sequence of ssopenurl:linkGroups elements, which contain the holdings information and links for the resource being referenced.

The citation metadata will be represented using Dublin Core Metadata Elements to the extent possible. Metadata that has no corresponding term in this schema will be represented using terms defined by Ex Libris, which may be refinements of the Dublin Core terms.

 

ssopenurl:citation element

The metadata in the ssopenurl:citation element describes the resource being referenced in the query URL. Many of these metadata elements are taken directly from the URL, but in some cases this data may be altered or removed. For example, if the ISSN provided is invalid, this data will not be included. Or, if the ISSN provided does not match the source title provided, the ISSN will be replaced with an ISSN that matches the title. In all cases, appropriate diagnostics will be reported to indicate when data are altered or removed.

MetadataElementDescription
Title of the referenced workdc:titleThe title of the work referenced in the OpenURL. For example, for articles, this is the article title.
Author or Inventordc:creatorAn author (or creator) of the referenced work. For example, the author of an article or the inventor of a patent.
Author’s first namessopenurl:creatorFirstFirst name of author or creator of referenced work.
Author’s middle name or initialssopenurl:creatorMiddleMiddle name or initial of author or creator of referenced work.
Author’s last namessopenurl:creatorLastLast name of creator of referenced work.
Resource that the referenced item is part ofdc:sourceName of the resource that the referenced item is a part of. For example, for an article, this would be the title of the journal in which the article appears.
Publication datedc:dateDate the resource was published.
ISSNssopenurl:issnAn ISSN associated with this resource. The attribute type indicates the kind of ISSN, either print or electronic. There may be multiple ISSNs listed.
ISBNssopenurl:isbnAn ISBN associated with this resource.
Volumessopenurl:volumeThe volume in which the resource being referenced was published.
Issuessopenurl:issueThe issue in which the resource being referenced was published.
Start pagessopenurl:spageThe starting page of the resource being referenced.
DOIssopenurl:doiThe DOI of the resource being referenced.
PubMed identifierssopenurl:pmidThe PubMed identifier of the resource being referenced.
Publisher namedc:publisherName of the publisher of the resource being referenced
Place of publicationssopenurl:publicationPlaceLocation where the referenced resource was published.
Institutionssopenurl:institutionThe institution associated with the referenced resource.
Advisorssopenurl:advisorThe advisor associated with the referenced resource.
Patent Numberssopenurl:patentNumberThe patent number associated with the referenced resource.

ssopenurl:linkGroups element

The ssopenurl:linkGroups element, when present, contains a sequence of ssopenurl:linkGroup elements. Two types of ssopenurl:linkGroup elements are supported: 1) holding and 2) terms of use. The type is indicated by an attribute of this element.

Each ssopenurl:linkGroup element contains a sequence of ssopenurl:url elements, each with an attribute indicating the type of URL being constructed (e.g., article, volume, terms of use). Holding link groups also contain a ssopenurl:holdingData element that details the provider and database this holding is available from and the coverage dates for the holding as outlined in the table below.

ssopenurl:holdingData element

MetadataElementDescription
Starting Datessopenurl:startDateThe starting date of the holding. When not present, this indicates there is no starting date for this holding.
ssopenurl:normalizedData/ssopenurl:startDateThe starting date normalized into the format YYYY-MM-DD. When not present, this indicates it was not possible to normalize the given value of ssopenurl:startDate.
Ending Datessopenurl:endDateThe ending date normalized into the format YYYY-MM-DD. When not present, this indicates it was not possible to normalize the given value of ssopenurl:endDate.
ssoenpurl:normalizedData/ssopenurl:endDateThe ending date of the holding. When not present, this indicates there is no ending date for this holding.
Provider Identifierssopenurl:providerIdUnique Serials Solutions identifier for the content provider from which this holding comes.
Provider Namessopenurl:providerNameThe (possibly customized) name of the content provider from which this holding comes.
Database Identifierssopenurl:databaseIdUnique Serials Solutions identifier for the database from which this holding comes.
Database Namessopenurl:databaseNameThe (possibly customized) name of the database from which this holding comes.