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 model our diagnostic schema on the SRU standard.
The schema for diagnostics contains 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
- a human-readable message, which provides more explicit details about the problem.
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ssdiag="http://xml.serialssolutions.com/ns/diagnostics/v1.0" targetNamespace="http://xml.serialssolutions.com/ns/diagnostics/v1.0" elementFormDefault="qualified" xsi:schemaLocation="http://xml.serialssolutions.com/ns/diagnostics/v1.0 diagnostics.xsd "> <xsd:annotation> <xsd:documentation xml:lang="en"> Schema defintion for Serials Solutions' XML API diagnostics. This is borrowed from the SRU diagnostic schema (http://www.loc.gov/standards/sru/xml-files/diagnostics.xsd). </xsd:documentation> </xsd:annotation> <xsd:element name="diagnostics"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="unbounded" ref="ssdiag:diagnostic"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="diagnostic" type="ssdiag:diagnosticType" nillable="false"/> <xsd:complexType name="diagnosticType"> <xsd:sequence> <xsd:element ref="ssdiag:uri"/> <xsd:element ref="ssdiag:details" minOccurs="0" maxOccurs="1" /> <xsd:element ref="ssdiag:message" minOccurs="0" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> <xsd:element name="uri" type="xsd:anyURI" nillable="false"/> <xsd:element name="details" type="xsd:string" nillable="false"/> <xsd:element name="message" type="xsd:string" nillable="false"/> </xsd:schema>
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. |