Version 1.0 Vocabulary Server methods

Select from the following for more information on each method

whatLists — retrieves a list of all available controlled vocabularies
getList — retrieves a selected controlled vocabulary
verifyTerm — indicates if a particular term is valid in a given controlled vocabulary
pvMap — finds equivalent terms in selected vocabularies
getPhenomDict — returns a parameter usage vocabulary term marked up with Geography Markup Language (GML, a schema for the distribution and storage of geographic information from the Open Geospatial Consortium)
whatListsCat — displays a list of categories for grouping the controlled vocabularies into subsets
searchVocab — searches through the controlled vocabularies for a given search term
getMap — retrieves the complete mapping for a selected pair of vocabularies

The methods have been designed to satisfy the following use cases

1. User wants to know what lists are available

2. User wants the entire contents of a given list

3. User wants all the entries from a given list that have been modified since a specified date

4. User wants the term and definition for a given key in a given list

5. User wants to know if a term or abbreviation is valid in a given list

6. User wants the key for a specified term or abbreviation in a given list

7. User wants the terms and definitions from a specified vocabulary that map to a specified Parameter Usage Vocabulary key

8. User wants terms and definitions from a specified vocabulary that map to a specified Parameter Discovery Vocabulary key

9. User wants a GML phenomenon dictionary entry for a specified Parameter Usage Vocabulary key

10. User wants to know what categories are available for grouping sets of vocabulary lists

11. User wants to group the available lists into categories

12. User wants to search all the lists for a particular term

13. User wants to search a given list for a particular term

14. User wants all terms that have been mapped between two vocabularies

15. User wants equivalent, broader or narrower terms from the mapping of two vocabularies (not yet implemented)

whatLists

Use Case: 1, 11

Input

Category Key (string provided by whatListsCat or null)

Output

An array of strings separated by XML tags as follows:

<codeTableRecord>
           <listKey>unique key for a particular vocabulary list</listKey>
           <listLongName>vocabulary list full name</listLongName>
           <listShortName>vocabulary list abbreviated name</listShortName>
           <listDefinition>vocabulary list description</listDefinition>
           <listVersion>version number</listVersion>
           <listLastMod>vocabulary list date last modified "yyyy-mm-dd hh24:mi:ss GMT"</listLastMod>
</codeTableRecord>

Java method call

String[] lists = service.whatLists(catKey);

For example: whatLists("CL06") retrieves the details of all lists used for phenomenon descriptions and qualifications.

Notes

This can be used in conjunction with getList to select a vocabulary list based on the whatLists listKey.
The list key is the concatenation of the BODC list name and BODC section number (e.g. C751, C752 etc).
Time stamps will be generated by the system clocks and therefore be UK local time (GMT or BST).
The list modified timestamp is the version timestamp, not the BODCCDTX records modified timestamp.
In order to output valid XML, any client software requiring this must apply start and end tags to the output array. For example:
    <whatLists>
                <codeTableRecord>...</codeTableRecord>
                <codeTableRecord>...</codeTableRecord>
     </whatLists>

getList

Use cases: 2, 3, 4

Input

List key (string provided by whatLists)
Entry key (string for unique record identifier or null)
Cut-off modification timestamp (string "yyyy-mm-dd" or null)

Output

An array of strings separated by XML tags as follows:

<codeTableRecord>
          <entryKey>unique identifier for a particular entry within a vocabulary list</entryKey>
          <entryTerm>vocabulary term full name</entryTerm>
          <entryTermAbbr>vocabulary term abbreviated name</entryTermAbbr>
          <entryTermDef>vocabulary term definition</entryTermDef>
          <entryTermLastMod>vocabulary term date last modified "yyyy-mm-dd hh24:mi:ss GMT"</entryTermLastMod>
</codeTableRecord>

Java method call

String[] vocabArray = service.getList(listKey, entryKey, datMod);

For example:

getList("P011", null, "2006-01-01") retrieves all Parameter Usage Vocabulary (PUV) terms created after 1st January 2006
getList("P011", "BLENOX01", null) retrieves the PUV term that corresponds to the unique P011 reference key entered

Notes

The cut-off modification timestamp is the earliest modification timestamp to be included in the output records. If no cut-off modification timestamp parameter is supplied the whole list is returned.
If no entry key is specified then the entire list is returned.
In order to output valid XML, any client software requiring this must apply start and end tags to the output array. For example:

verifyTerm

Use cases: 5, 6

Input

List key (string provided by whatLists)
Entry term (string)
Term type (string 'long' or 'short' or null, default = 'long')

Output

Entry key (string array)

Java method call

String[] vocabArray = service.verifyTerm(listKey, entryTerm, termType);

For example: verifyTerm("P021", "Salinity of the water column", "long") returns the unique reference key that corresponds to this term within the Parameter Discovery Vocabulary (PDV). If the term is not in the controlled vocabulary, "invalid" is returned.

Notes

Entry key is set to 'invalid' if the input term is not present in the list.
Term type is set to 'short' to verify abbreviated vocabulary terms or 'long' to search the full-length terms.

pvMap

Use cases: 7, 8

Input

Parameter vocabulary key (string for unique record identifier)
Parameter vocabulary identifier (string 'P011' or 'P021')
Vocabulary to be mapped (string 'P011', 'P021', 'P031', 'P041', 'P051' or 'P061')

Output

An array of strings separated by XML tags as follows:

<codeTableRecord>
          <entryKey>unique identifier for a particular entry within a vocabulary list</entryKey>
          <entryTerm>vocabulary term full name</entryTerm>
          <entryTermAbbr>vocabulary term abbreviated name</entryTermAbbr>
          <entryTermDef>vocabulary term definition</entryTermDef>
          <entryTermLastMod>vocabulary term date last modified "yyyy-mm-dd hh24:mi:ss GMT"</entryTermLastMod>
</codeTableRecord>

Java method call

String vocabArray = service.pvMap(vocabEntryKey, vocabListID, mapVocabID)

For example: pvMap("PSAL", "P021", "P011") retrieves all P011 terms that are related to the P021 term that has entry key "PSAL". In this case all Parameter Usage Vocabulary terms relating to measurements of salinity are retrieved.

Notes

The vocabularies are identified in the input parameters using their list keys, which are:
- P011 — BODC Parameter Usage Vocabulary
- P021 — BODC Parameter Discovery Vocabulary
- P031 — SEASEARCH Agreed Parameter Groups
- P041 — GCMD Parameter Valids
- P051 — ISO Topic Categories
- P061 — BODC data storage units
In order to output valid XML, any client software requiring this must apply start and end tags to the output array. For example:

getPhenomDict

Use cases: 9

Input

BODC parameter usage vocabulary (PUV) key from P011 (string)

Output

Parameter usage vocabulary entry marked up with GML tags

<gml:dictionaryEntry>
          <om:Phenomenon gml:id="puvKey">
                    <gml:description>PUV entry full name</gml:description>
                    <gml:name codespace="http://vocab.ndg.nerc.ac.uk?P011">PUV entry key</gml:name>
          </om:Phenomenon>
</gml:dictionaryEntry>

Example Java method call

String gml = service.getPhenomDict(puvKey);

For example, getPhenomDict("BLENOX01") returns the following:

<gml:dictionaryEntry>: <om:Phenomenon gml:id="BLENOX01">
<gml:description>Length of Ammodytidae (ITIS 171670) by physical measurement</gml:description>: <gml:name codespace="http://vocab.ndg.nerc.ac.uk?P011">BLENOX01</gml:name>
</om:Phenomenon>
</gml:dictionaryEntry>

whatListsCat

Use case: 10

Input

None

Output

An array of strings separated by XML tags as follows:

<codeTableRecord>: <entryKey>unique identifier for a particular entry within a vocabulary list</entryKey>
<entryTerm>vocabulary term full name</entryTerm>: <entryTermAbbr>vocabulary term abbreviated name</entryTermAbbr>
<entryTermDef>vocabulary term definition</entryTermDef>: <entryTermLastMod>vocabulary term date last modified "yyyy-mm-dd hh24:mi:ss GMT"</entryTermLastMod>
</codeTableRecord>

Java method call

String[] cats = service.whatListsCat();

Notes

This can be used in conjunction with whatLists to select a group of lists based on a whatListsCat entryKey.
In order to output valid XML, any client software requiring this must apply start and end tags to the complete output array. For example:

searchVocab

Use cases: 12, 13

Input

List key (string provided by whatLists or null)
Search term (string)
Term type (values 'long', 'short' or 'definition' or null, default = 'long')

Output

<codeTableRecord>: <listKey>unique identifier for a controlled vocabulary</listKey>
<entryKey>unique identifier for a particular entry within a vocabulary list</entryKey>: <entryTerm>vocabulary term full name</entryTerm>
<entryTermAbbr>vocabulary term abbreviated name</entryTermAbbr>: <entryTermDef>vocabulary term definition</entryTermDef>
<entryTermLastMod>vocabulary term date last modified "yyyy-mm-dd hh24:mi:ss GMT"</entryTermLastMod>
</codeTableRecord>

Java method call

String[] terms = service.searchVocab(listKey, searchTerm, termType);

For example: searchVocab("P011","salinity","long") returns all Parameter Usage Vocabulary entries with the word "salinity" in their full name.

Notes

A null list key causes a search of all the vocabulary lists.
Term type 'long' searches the vocabulary term full names; 'short' searches through the abbreviated names; 'definition' searches through the definitions.
In order to output valid XML, any client software requiring this must apply start and end tags to the complete output array. For example:

getMap

Use cases: 14, (15)

Input

fromVoc List Key — the identifier of the vocabulary to be mapped from (legal values are: ‘P011’, for the BODC Parameter Usage Vocabulary; ‘P021’, for the BODC Parameter Discovery Vocabulary.)
toVoc List Key — the identifier of the vocabulary to be mapped to (legal values are: ‘P031’, the SeaSearch agreed parameter groups; ’P041’, the Global Change Master Directory science keywords; ’P051’, ISO 19115 topic categories; ’P061’, BODC units.)
Relationship type (null) — this is not currently implemented. It will be used to select mapped terms that are broader, narrower or equivalent between vocabularies. Legal values will be ‘b’, ’n’ and ‘eq’.

Output

<fromEntryKey>unique identifier for a particular entry within the ‘from’ vocabulary list </fromEntryKey>

<fromTerm>’from’ vocabulary term full name</fromTerm>

<toEntryKey> unique identifier for a particular entry within the ‘to’ vocabulary list </toEntryKey>

<toTerm>’to’ vocabulary term full name</toTerm>

</mapRecord>

Java method call

String[] map = service.getMap(fromListKey, toListKey, null);

Notes

When relationship type is operational, the method call will be String[] map = service.getMap(fromListKey, toListKey, relationship);
In order to output valid XML, any client software requiring this must apply start and end tags to the complete output array. For example:

Resources

In this section

Version 1.0 Vocabulary Server methods

whatLists

Input

Output

Java method call

Notes

getList

Input

Output

Java method call

Notes

verifyTerm

Input

Output

Java method call

Notes

pvMap

Input

Output

Java method call

Notes

getPhenomDict

Input

Output

Example Java method call

whatListsCat

Input

Output

Java method call

Notes

searchVocab

Input

Output

Java method call

Notes

getMap

Input

Output

Java method call

Notes