NERC DataGrid vocabulary server
The NERC DataGrid (NDG) vocabulary server gives data managers the means to access lists of controlled terms to describe data, thus saving the time and costs associated with unraveling the meaning of a given data set.
- Introduction — a brief summary of the value of implementing the vocabulary server
- Caveats for the V1.1 Vocabulary Server release — warnings for the latest vocabulary server 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
- Vocabulary server methods — summary of the Web Service methods including parameters, outputs and examples
Introduction
The NDG vocabulary server provides access to lists of standardised terms that cover a broad spectrum of disciplines of relevance to the oceanographic and wider community.
Using standardised sets of terms (otherwise known as "controlled vocabularies") in metadata and to label data solves the problem of ambiguities associated with data markup and also enables records to be interpreted by computers. This opens up data sets to a whole world of possibilities for computer aided manipulation, distribution and long term reuse.
An example of how computers may benefit from the use of controlled vocabularies is in the summing of values taken from different data sets. For instance, one data set may have a column labelled "Temperature of the water column" and another might have "water temperature" or even "temperature". To the human eye, the similarity is obvious but a computer would not be able to interpret these as the same thing unless all the possible options were hard coded into its software. If data are marked up with the same terms, this problem is resolved.
In the real world, it is not always possible or agreeable for data providers to use the same terms. In such cases, controlled vocabularies can be used as a medium to which data centres can map their equivalent terms.
The controlled vocabularies delivered by the NDG vocabulary server contain the following information for each term:
- Key — a compact permanent identifier for the term, designed for computer storage rather than human readability
- Term — the text string representing the term in human-readable form
- Abbreviation — a concise text string representing the term in human-readable form where space is limited
- Definition — a full description of what is meant by the term
All of the vocabularies are fully versioned and a permanent record is kept of all changes made.
Version 1.1 of the server represents a complete rewrite of the internal software with both increased functionality and performance. The latter is particularly significant and consequently, although the V1.0 code will remain operational for the foreseeable future, existing users are urged to convert to V1.1 as soon as possible and the development of new V1.0 applications is strongly discouraged. The V1.0 method specifications are maintained as historical documents.
Caveats for the V1.1 Vocabulary Server release
- The term and list URIs include a list version specification. This has no effect on the V1.1 API, which always serves the current version of the list. Fully versioned list serving is planned for the V1.2 release.
- 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. See caveats for versioning limitations with the V1.1 server release.
- 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
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/1/CL03 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
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
Related BODC pages
| BODC Web Services | Vocabulary server method details | |
| NERC DataGrid (NDG) |
Related external links
| NERC DataGrid (NDG) vocabulary server | Open Geospatial Consortium, Inc (OGC) |
 |
 |
 |
