NatureServe Species Schemas

The NatureServe Species Schemas are documents written in the XML Schema language that describe species-level attributes reflected in NatureServe's Biodiversity Data Model. They define all of the possible XML elements and attributes that make up NatureServe's 'Biodiversity Data Flow', i.e. the biodiversity data which may be obtained from NatureServe's web services.

Current Version: 1.1

Schemas are version numbered in the format major_version_number.minor_version_number. For the current version, the major version number is 1 and the minor version number is 1.

Schemas with a particular major version number can be used to validate all minor versions up to and including that version. In other words, minor version number changes are backwardly compatible and, for instance, the current version 1.1 can validate outputs conforming to either versions 1.1 or 1.0.

Changes in major version number indicate changes so significant that backwards compatibility is no longer possible. If a schema moved to version 2.0, for instance, it could no longer validate outputs conforming to versions 1.*.

URL

NatureServe maintains an 'index schema' per major version number, which always points to the latest version of the schemas. For versions 1.*, this can be found at the following url. Users are encouraged to make this their starting point for exploring the schemas or validating outputs, as the minor version details will be hidden from view.

http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1/

Reading the schemas

The set of schemas is arranged in a hierarchy, starting with the index schema. The index schema 'includes' the latest version of the Biodiversity Data Flow root schema, which in turn includes the schemas which define the outputs from the various web services, which in turn include the basic elements from the Biodiversity Data Model, etc.

Each service description contains an entry in its Output section for the 'Root element' of its response data. Once found, this root element can be traced to elucidate the contents of its sub-elements and their sub-elements, etc, and thereby form a picture of the complete response. This process is made much easier by the usage of a tool - XML Schema is not in any sense 'intuitive'. Some suggestions for tools can be found at the Technical Library.

Although the schemas themselves are extensively documented, separate human friendly documentation, specific to the output of each service, can be found by following the 'Detailed documentation' link in the Output section of each service description.

Validating web services output

Web services outputs can be automatically validated by tools which compare the XML generated to the definition contained in an XML schema. All NatureServe's web services include an attribute on their root elements called schemaLocation. For instance, the root element for the output of the Global Comprehensive Species Service is as follows (this has been reformatted slightly to fit the page).

<globalSpeciesList
   xsi:schemaLocation=
      "http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1
       http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1/"
   xmlns="http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   schemaVersion="1.1">
						

The schemaLocation attribute here is saying:

"elements in the namespace

http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1

(which covers the Biodiversity Data Flow) conform to the schema at

http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1/".

The use of schemaLocation makes it possible not only for a user to find the required schema, but also a validation tool. The user can simply tell the tool to validate the XML and let it fetch and parse the required schemas.

See also

The Technical Library has a list of useful schema related resources.