This serves as the cover page for a hierarchically arranged 'book' of documentation for the GBIF Vocabulary Server.
You can also download the User and Technical Docmentation in PDF format directly from this page.
| Attachment | Size |
|---|---|
| User Documentation | 1.92 MB |
| Technical Documentation | 516.54 KB |
A controlled Vocabulary, often based on internationally recognized standards (e.g. ISO and TDWG) forms a core component of biodivertsity data integration. A Vocabulary is made up of many concepts each of which can have any number of multilingual terms associated with them.
Darwin Core Extensions are a means by which the Darwin Core [1] standard for observation data can be enhanced with additional data structures. Tools like the IPT make federated sharing data encoded to these extensions possible. For an example of how these extensions can be used, please see examples on the ECAT and IPT Wiki's. To quote the ECAT Wiki on extensions:
They are tied to the core taxon file through a copy of the taxonID used in the core taxon file that is repeated once for each row in the extension file in a manner similar to foreign keys in a relational database. An extension file may include Darwin Core terms as well as terms defined through other means.
The use of extension files allows checklist information to be represented in a one-to-many relation ship between the core taxon file and the extension. For example, a taxon may be known by multiple vernacular names in different languages. A extension describing vernacular names could contain multiple rows that each describe one vernacular name and that use the taxonID in the core taxon file to reference the same taxon in the core file.
The use of a core taxon file and one or more extensions that link to the core file is referred to as a star schema
This site provides a number of web services based around the vocabularies that it is used to maintain. These services are RESTful XML based services which we will try to enhance and add to as demand increases. Possible enhancements that we're thinking about include making the services available as JSON and defining an API to allow other sites to submit alternative terms for the concepts lodged on this site.
We have a service which lists the vocabularies being managed through this site and being managed by it:
http://vocabularies.gbif.org/services/gbif/vocabularies/
You may notice this is a short list - we are working on moving a number of other taxonomically focussed vocabularies into the site to really make it useful - for the full list see http://gnapartnership.org/gbif-scratchpads/ticket/82
For each of the vocabularies you can now:
The best way to illustrate the services is to break the request url up so take the following stylised URL:
http://vocabularies.gbif.org/services/gbif/[vocabularyName]/{name=ABC}{identifier (all)}{?}{&alternatives=1(0)}{&lang=XX[,YY,ZZZ](all)}{&filters[filterName]=filterValue}{&limit=numberOfRecords(500)}{&page=pageNumber(0)
| Component | Definition |
|---|---|
| http://vocabularies.gbif.org | Site URL |
| services/gbif/ | Get to the web services |
| vocabularyName | The desired vocabulary you want to query - (eg 'country') |
| identifier | The standard identifier you want to retrieve from the vocabulary (eg 'BO'). If no identifier is given then all concepts for that vocabulary are returned. (Cannot be used in combination with 'name'.) |
| name | A word of 2 or more characters that you want to match terms with (eg 'arab'). Returns all concepts matching a name. (Cannot be used in combination with 'identifier'.) |
| alternatives | If set to 'true' or any non zero value (eg 'alternatives=1') then the request will return alternative terms for the concept as well as preferred terms. Defaults to 0 (false). Does not work with the 'name' argument. |
| lang | Standard ISO identifier for the language as defined by IETF RFC 4646 (http://www.ietf.org/rfc/rfc4646.txt) or successor. This is normally the ISO 639-1 two letter code for the language, or if your language is not covered by that standard the ISO 639-2/639-3 code for that language. (eg 'fr') |
| filters[filtername] | You can specify an array of filters with which to limit your query. Not all datatypes have these filters built in, but the language one does, with the most notable filter being the '639_level' filter which filters languages by the level at which they enter the ISO 639 standard for encoding languages. In this case the level can take the integer values 1, 2 or 3. |
| limit | limit the number of records returned in your query (defaults to 500) |
| page | specify the page number to return for your query (defaults to 0) |
| [] | required argument |
| {} | optional argument |
| () | the default value for optional arguments if the optional argument is not given |
The workflow for both Vocabularies and Extensions within this site is made up of 5 states.
The item has just been created - it never stays in this state, so it immediately moves into the next state, draft.
This is a very fluid time within a Vocabulary / Extension - lots can change without notice.
Concepts can still be added to vocabulaires. Current concepts definitions and associated data should be able to change but the identifiers should remain stable.
Terms can still be added to concepts, but concept definitions and identifiers remain constant. Concepts can still be added to vocabularies.
The vocabulary or extension still exists but has potentially been replaced by a more up to date one.
| From | To | |
|---|---|---|
| (creation) | → | draft |
| draft | → | review |
| draft | → | deprecated |
| review | → | draft |
| review | → | published |
| review | → | deprecated |
| published | → | deprecated |
| None |
| None |
| From | To | |
|---|---|---|
| draft | → | review |
| From | To | |
|---|---|---|
| (creation) | → | draft |
| draft | → | review |
| draft | → | published |
| draft | → | deprecated |
| review | → | draft |
| review | → | published |
| review | → | deprecated |
| published | → | deprecated |
| From | To | |
|---|---|---|
| (creation) |