http://<client identifier>.openurl.xml.serialssolutions.com/openurlxml
Both HTTP POST and GET requests are supported.
| Parameter Name | Mandatory or Optional |
Values | Default | Description |
|---|---|---|---|---|
| version | mandatory | 1.0 | none | Specifies which version of the XML API interface the query is compatible with and which version the response should be compatible with. While we try to maintain backward compatibility between and among versions, this may not always be possible. If a version is no longer supported, an appropriate diagnostic message will be returned. |
| stylesheet | optional | valid URLs | none | A URL for an xml stylesheet to be included in the response. |
| Metadata | Element | Description |
|---|---|---|
| Referrer Provider Identifier | ssopenurl:providerId | Unique Serials Solutions identifier for the provider that was the source of this OpenURL query. This data is derived from the sid OpenURL parameter. |
| Referrer Database Identifier | ssopenurl:databaseId | Unique Serials Solutions identifier for the database that was the source of this OpenURL query. This data is derived from the sid OpenURL parameter. |
The citation metadata will be represented using Dublin Core Metadata Elements to the extent that that is possible. Metadata that has no corresponding term in this schema will be represented using terms defined by Serials Solutions, which may be refinements of the Dublin Core terms.
ssopenurl:citation element
The metadata included 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 not a valid issn,
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.
| Metadata | Element | Description |
|---|---|---|
| Title of the referenced work | dc:title | The title of the work referenced in the OpenURL. For example, for articles, this is the article title. |
| Author or Inventor | dc:creator | An author (or creator) of the referenced work. For example, the author of an article or the inventor of a patent. |
| Author's first name | ssopenurl:creatorFirst | First name of author or creator of referenced work. |
| Author's middle name or initial | ssopenurl:creatorMiddle | Middle name or initial of author or creator of referenced work. |
| Author's last name | ssopenurl:creatorLast | Last name of creator of referenced work. |
| Resource that the referenced item is part of | dc:source | Name 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 date | dc:date | Date the resource was published. |
| ISSN | ssopenurl:issn | An ISSN associated with this resource. The attribute type indicates the kind of ISSN, either print or electronic. There may be multiple ISSNs listed. |
| ISBN | ssopenurl:isbn | An ISBN associated with this resource. |
| Volume | ssopenurl:volume | The volume in which the resource being referenced was published. |
| Issue | ssopenurl:issue | The issue in which the resource being referenced was published. |
| Start page | ssopenurl:spage | The starting page of the resource being referenced. |
| DOI | ssopenurl:doi | The DOI of the resource being referenced. |
| PubMed identifier | ssopenurl:pmid | The PubMed identifier of the resource being referenced. |
| Publisher name | dc:publisher | Name of the publisher of the resource being referenced |
| Place of publication | ssopenurl:publicationPlace | Location where the referenced resource was published. |
| Institution | ssopenurl:institution | The institution associated with the referenced resource. |
| Advisor | ssopenurl:advisor | The advisor associated with the referenced resource. |
| Patent Number | ssopenurl:patentNumber | The patent number associated with the referenced resource. |
ssopenurl:linkGroups element
The ssopenurl:linkGroups element, when present, contains a sequence
of ssopenurl:linkGroup elements. There are two types of
ssopenurl:linkGroup elements currently supported: holding and
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
Metadata
Element
Description
Starting Date
ssopenurl:startDate
The starting date of the holding. When not present, this indicates there is no starting date
for this holding.
ssopenurl:normalizedData/ssopenurl:startDate
The 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 Date
ssopenurl:endDate
The 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:endDate
The ending date of the holding. When not present, this indicates there is no ending date for this holding.
Provider Identifier
ssopenurl:providerId
Unique Serials Solutions identifier for the content provider from which this holding comes.
Provider Name
ssopenurl:providerName
The (possibly customized) name of the content provider from which this holding comes.
Database Identifier
ssopenurl:databaseId
Unique Serials Solutions identifier for the database from which this holding comes.
Database Name
ssopenurl:databaseName
The (possibly customized) name of the database from which this holding comes.
Examples
Depending on the metadata provided in the OpenURL, there may be one, many, or no results returned in the XML.
When the metadata presented in an OpenURL query corresponds to a single resource that the library has holdings for,
there will be a single result element in the
returned XML. If the library has
no holdings for the referenced resource, there will be a single
result element with no
linkGroups element. When the metadata provided
is ambiguous or not sufficient to allow us to distinguish among several resources,
several results and their respective links and holdings data will be
returned. This is true even when there are several resources that match the metadata but the library
has no holdings for any of them.
Diagnostic Messages
Diagnostic messages will be returned when, for example, the query provided is not of the proper
syntax, or the application's server is not responding, or the version requested is not supported.
We borrow a page from the SRU standard
to define our diagnostics.
The schema for diagnostics is very simple
and contains only three elements: an identifier, which can be mapped to the tables below, a details element,
which indicates what parameter or data point gave rise to the diagnostic, and a human-readable message, which
provides more explicit details about the problem.
Diagnostics can be either fatal or
non-fatal, as detailed below.
Fatal Diagnostics
A fatal diagnostic will prevent the server from processing the query. For example, if the client did not provide
enough metadata, the server will not be able to conduct a search for the requested resource. Diagnostics are identified
with the string sersol/diagnostics/ followed by the
corresponding identifier given in the table below.
Identifier
Description
Details Format
1
General system error
Debugging information
2
System temporarily unavailable
3
Authentication error
5
Unsupported version
Versions supported
6
Unsupported parameter value
Name of parameter
7
Mandatory parameter not supplied
Name of missing parameter
8
Not enough metadata supplied
Required metadata
Non-Fatal Diagnostics
A non-fatal
diagnostic will be included when processing is affected but the server can continue. For example, if a
supplied ISSN is not of the proper syntax, the server will simply ignore the ISSN and continue with the
other metadata provided.
Identifier
Description
Details Format
Example
100
Invalid syntax
parameter name
ISSN containing invalid characters or incorrect number of characters.
101
Invalid checksum
parameter name
ISSN of the correct syntax but for which the last character is not the
on expected given the other characters.
102
Identifier with no data
parameter name
DOI provided in the OpenURL parameters is of the valid syntax, but
we could not retrieve data for that identifier.
103
Mismatched metadata
parameter names
DOI provided in the OpenURL references a different source than the
other metadata provide in the OpenURL.
104
Data ignored
parameter names
Author name provided is some variant of "anonymous".
105
Data altered
parameter names
Metadata element contains extraneous data, which would cause problems
in creating links.
©2007 Copyright Serials Solutions. All rights reserved.