Version 1.1 Vocabulary Server

Although the V1.1 code will remain operational for the foreseeable future, existing users are urged to convert to Vocabulary Server version 2.0 as soon as possible and the development of new V1.1 applications is strongly discouraged.

• Caveats for the V1.1.4 Vocabulary Server release — warnings for the Vocabulary Server version 1.1. release
• List and term URIs — summary of lists and terms as URIs
• Connectivity — consumer access options for the Vocabulary Server
• XML data types — summary of the major data types of the service
• Predicate Bit Mask
• Vocabulary Server version 1.1. methods — summary of the Web Service methods including parameters, outputs and examples

Caveats for the V1.1.4 Vocabulary Server release

• The term and list URIs include a list version specification. This has no effect for the getRelatedRecord methods because they reference terms rather than lists. All the other methods fully support versioned lists.
• The methods that access the maps between terms in the vocabulary server include an "inference" parameter. This only exposes inferred relationships that have been manually loaded into the system and are therefore not comprehensive. The parameter is primarily included as a "hook" for future releases incorporating inference engines.

List and term URIs

Lists and terms are presented to the server as URIs (actually URLs) having the syntax

List: http://vocab.ndg.nerc.ac.uk/list/listReference/listVersion
Term: http://vocab.ndg.nerc.ac.uk/term/listReference/listVersion/entryReference

where

• listReference is an internal opaque identifier for the list, e.g. P021 for the BODC Parameter Discovery Vocabulary.
• listVersion may be a valid list version number or 'current' to specify the latest version of the list.
• entryReference is an internal opaque identifier for the list entry, e.g. TEMP for ‘Temperature of the water column’ in the BODC Parameter Discovery Vocabulary.

Connectivity

Consumers may access the vocabulary server either via SOAP or HTTP-POX sometimes wrongly (in this instance) referred to as RESTful access.

SOAP consumers should generate their client implementation from the WSDL available at http://vocab.ndg.nerc.ac.uk/1.1/VocabServerAPI_dl.wsdl.

HTTP-POX consumers should construct a GET request with the URI formed thus

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
whatLists
?categoryKey=http://vocab.ndg.nerc.ac.uk/term/C980/current/CL12

where

• http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/ is the service address
• whatLists is the method name
• ?categoryKey=http://vocab.ndg.nerc.ac.uk/term/C980/current/CL12 are the method arguments

If the cardinality of a parameter indicates you may specify more than one instance of a particular parameter, you may do this by including another key value pair indicating the criteria. For example, requesting the contents of two lists from getList looks like this

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
getList
?recordKey=http://vocab.ndg.nerc.ac.uk/list/C110/4
&recordKey=http://vocab.ndg.nerc.ac.uk/list/C161/0

XML data types

The service returns results as XML documents. The major data types of which are discussed below.

types:codeTableTypeType

XML conforming to the following XML Schema fragment is returned for each matching list.

<xsd:complexType name="codeTableTypeType">

      <xsd:sequence>
              <xsd:element name="listKey" type="xsd:string" />
              <xsd:element name="listLongName" type="xsd:string" />
              <xsd:element name="listShortName" type="xsd:string" />
              <xsd:element name="listDefinition" type="xsd:string" />
              <xsd:element name="listVersion" type="xsd:int" />
              <xsd:element name="listLastMod" type="xsd:dateTime" />
      </xsd:sequence>
</xsd:complexType>

where

• listKey — URI for a particular vocabulary list
  
• listLongName — vocabulary list full name
  
• listShortName — vocabulary list abbreviated name
  
• listDefinition — vocabulary list description
  
• listVersion — version number
  
• listLastMod — vocabulary list date last modified "yyyy-mm-ddThh24:mi:ssZ"
  

types:codeTableRecordType

XML conforming to the following XML Schema fragment is returned for each matching term.

<xsd:complexType name="codeTableRecordType">
      <xsd:sequence>
              <xsd:element name="listKey" type="xsd:string" minOccurs="0" />
              <xsd:element name="entryKey" type="xsd:string" />
              <xsd:element name="entryTerm" type="xsd:string" />
              <xsd:element name="entryTermAbbr" type="xsd:string" nillable="true" />
              <xsd:element name="entryTermDef" type="xsd:string" nillable="true" />
              <xsd:element name="entryTermLastMod" type="xsd:dateTime" />
              <xsd:element name="exactMatch" type="types:codeTableRecordType" minOccurs="0" maxOccurs="unbounded" />
              <xsd:element name="narrowMatch" type="types:codeTableRecordType" minOccurs="0" maxOccurs="unbounded" />
              <xsd:element name="broadMatch" type="types:codeTableRecordType" minOccurs="0" maxOccurs="unbounded" />
              <xsd:element name="minorMatch" type="types:codeTableRecordType" minOccurs="0" maxOccurs="unbounded" />
              <xsd:element name="majorMatch" type="types:codeTableRecordType" minOccurs="0" maxOccurs="unbounded" />
      </xsd:sequence>
</xsd:complexType>

where

• listKey — URI for the particular vocabulary list referenced by this term
  
• entryKey — URI of this vocabulary term
  
• entryTerm — vocabulary term full name
  
• entryTermAbbr — vocabulary term abbreviated name
  
• entryTermDef — vocabulary term definition
  
• entryTermLastMod — vocabulary term date last modified "yyyy-mm-dd hh24:mi:ssZ"
  
• exactMatch — instances of related terms having the predicate “hasExactMatch” will be populated as instances of this optional element which is another instance of codeTableRecordType
  

• narrowMatch — instances of related terms having the predicate “hasNarrowMatch” will be populated as instances of this optional element which is another instance of codeTableRecordType
  

• broadMatch — instances of related terms having the predicate “hasBroadMatch” will be populated as instances of this optional element which is another instance of codeTableRecordType
  

• minorMatch — instances of related terms having the predicate “hasMinorMatch” will be populated as instances of this optional element which is another instance of codeTableRecordType
  

• majorMatch — instances of related terms having the predicate “hasMajorMatch” will be populated as instances of this optional element which is another instance of codeTableRecordType

Null content in both XML data types is represented using W3C convention. For example, an absent abbreviated name is represented by

<ns1:entryTermAbbr xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1" />

Predicate bit mask

The predicate bit mask is calculated by ORing together the following values. The predicate must not be equal to zero.

Predicate name	Value (Hexadecimal)	Value (Decimal)
hasExactMatch	0x01	1
hasNarrowMatch	0x02	2
hasBroadMatch	0x04	4
hasMinorMatch	0x08	8
hasMajorMatch	0x10	16

A description of these terms is available from the W3C: http://www.w3.org/2004/02/skos/mapping.rdf