<?xml version="1.0" encoding="utf-8" ?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0">
    <header>
      <!-- header specific elements -->
    </header>
    <operation_name>
      <!-- operation specific parameters -->
    </operation_name>
  </request>

  <?xml version="1.0" encoding="utf-8" ?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0">
    <header>
      <!-- header specific elements -->
    </header>
    <capabilities/>
  </request>

  <?xml version="1.0" encoding="utf-8" ?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0">
    <header>
      <!-- header specific elements -->
    </header>
    <operation_name>
      <!-- operation specific results -->
    </operation_name>
    <diagnostics>
      <!-- diagnostics information -->
    </diagnostics>
  </response>

  <?xml version="1.0" encoding="UTF-8"?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
             targetNamespace="http://example.net/cs/1.0/"
             elementFormDefault="qualified">
    <xs:element name="Person">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="Name" type="xs:string"/>
          <xs:element name="Email" type="xs:string"/>
          <xs:element name="Birth" type="xs:date" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="Id" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
  </xs:schema>

  Root element ::= ( <request> | <response> | <outputModel> | <inventoryTemplate> | <searchTemplate> )

  <?xml version="1.0" encoding="UTF-8" ?> 
  <request xmlns="http://rs.tdwg.org/tapir/1.0" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0 
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
     <!--   header and operation specific content -->
  </request>

  Request type ::= <header> 
                   ( <metadata> | <capabilities> | <inventory> | <search> | <ping> )

  Response type ::= <header>
                    ( <metadata> | <capabilities> | <inventory> | <search> | <pong> | <error> | <logged> ) 
                    <diagnostics>?

  Header type ::= <source>+ <destination>? <custom>?

  Source type ::= @accesspoint @sendtime <software>?

  Software type ::= @name @version <dependencies>*

  <request xmlns=http://rs.tdwg.org/tapir/1.0
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
                 xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                     http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
        <software name="TapirClient" version="3.0"/>
      </source>
    </header>
    <capabilities/>
  </request>

  <response>
    <!-- omitting header -->
    <error code="DBS_CONNECTION_ERROR" 
           level="fatal" 
           time="2005-11-11T12:23:57.023+01:00">Could not connect to database</error>
  </response>

  diagnostic type ::= @code? @level @time? message

  @level ::= ( "debug"|"info"|"warn"|"error"|"fatal" )

  <response>
    <!-- omitting header -->
    <!-- omitting operation -->
    <diagnostics>
      <diagnostic level="error" code="REQ_READ_MODEL_FAILED">The requested model could not be read.</diagnostic>
      <diagnostic level="warning" code="REQ_STRUCTURE_UNKNOWN_SCHEMA_TAG">
        Unknown xml schema element "test" encountered in line 3. Ignored.
      </diagnostic>
      <diagnostic level="info" code="RSP_ELEM_DROP">
        XML element "myel" dropped because it misses required attribute "myattr"
      </diagnostic>
      <diagnostic level="debug">Start reading the datasource configurations</diagnostic>
    </diagnostics>
  </response>

  <node path="/FeatureCollection/featureMember/LocationGML/Point/coordinates">
    <concept id="http://example.net/schema/Longitude" required="true"/>
    <literal value=","/>
    <concept id="http://example.net/schema/Latitude" required="true"/>
  </node>

  <node path="/r:records/r:record/dc:modified">
    <concept id="http://example.net/schema/DateLastModified" required="true"/>
  </node>

  <?xml version="1.0" encoding="UTF-8"?>
  <outputModel xmlns="http://rs.tdwg.org/tapir/1.0"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                   http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd
                                   http://www.w3.org/2001/XMLSchema
                                   http://www.w3.org/2001/XMLSchema.xsd">
    <label>Specimen Records</label>
    <documentation>Simple output model for specimen data.</documentation>
    <structure>
      <xs:schema targetNamespace="http://example.net/simple_specimen">
        <xs:element name="dataset">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="specimen" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="identification" minOccurs="0" maxOccurs="unbounded">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="name" type="xs:string"/>
                          <xs:element name="identifier" type="xs:string" minOccurs="0"/>
                        </xs:sequence>
                        <xs:attribute name="date" type="xs:string" use="optional"/>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                  <xs:attribute name="catnum" type="xs:int" use="required"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:schema>
    </structure>
    <rootElement name="dataset"/>
    <indexingElement path="/dataset/specimen"/>
    <mapping>
      <node path="/dataset/specimen/@catnum">
        <concept id="http://example.net/schema1/CatalogNumber" required="true"/>
      </node>
      <node path="/dataset/specimen/identification/name">
        <concept id="http://example.net/schema1/ScientificName" required="true"/>
      </node>
      <node path="/dataset/specimen/identification/identifier">
        <concept id="http://example.net/schema2/PersonName"/>
      </node>
      <node path="/dataset/specimen/identification/@date">
        <concept id="http://example.net/schema2/DateText"/>
      </node>
    </mapping>
  </outputModel>

  <?xml version="1.0" encoding="UTF-8"?>
  <inventoryTemplate xmlns="http://rs.tdwg.org/tapir/1.0"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                         http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <label>Specimen Scientific Names</label>
    <documentation>Search and list unique scientific names of specimen 
    identifications ordered alphabetically. The parameter 
    "name" can be used as a filter condition indicating the 
    first characters of interest.</documentation>
    <concepts>
      <concept id="http://example.net/schema/ScientificName"/>
    </concepts>
    <filter>
      <like>
        <concept id="http://example.net/schema/ScientificName"/>
        <parameter name="name"/>
      </like>
    </filter>
  </inventoryTemplate>

  <?xml version="1.0" encoding="UTF-8"?>
  <searchTemplate xmlns="http://rs.tdwg.org/tapir/1.0"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                      http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <label>Specimen by Name</label>
    <documentation>Search specimens by their scientific name. Result is 
    ordered by name (ascending) and catalog number (descending). 
    A parameter "name" can be used to build the filter.</documentation>
    <externalOutputModel location="http://example.net/models/names.xml"/>
    <filter>
      <like>
        <concept id="http://example.net/schema/ScientificName"/>
        <parameter name="name"/>
      </like>
    </filter>
    <orderBy>
      <concept id="http://example.net/schema/ScientificName"/>
      <concept id="http://example.net/schema/CatalogNumber" descend="true"/>
    </orderBy>
  </searchTemplate>

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <metadata/>
  </request>

5.1.2.2. Contacts

Related entities must indicate at least one contact and its role.

<role>

Used to specify one or more roles of a contact with respect to the service. The suggested vocabulary includes two values, "data administrator" or "system administrator", but accepts other values. String. Required.

<vcard:VCARD>

Complex element from the VCARD namespace for personal details. Includes an @xml:lang attribute to record language.

<vcard:FN>

Free text non-atomised, full name of contact. Includes optional @xml:lang attribute. String. Required.

<vcard:TITLE>

Free text for contact's job title (e.g., "Director"). Includes optional @xml:lang attribute. String. Optional.

<vcard:TEL>

Free text for contact's telephone number. Includes optional @xml:lang attribute and optional enumerated @TYPE attribute with any of the values home, msg, work, pref, voice, fax, cell, pager, bbs, modem, car, isdn, or pics. String. Optional.

<vcard:EMAIL>

Text for contact's email. String. Optional.

<custom>

Optional element that allows the inclusion of any additional structured information related to the contact.

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
            xmlns:dct="http://purl.org/dc/terms/"
            xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
            xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0 
                                http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source accesspoint="http://example.net/tapir.cgi" 
              sendtime="2005-11-11T12:23:56.023+01:00">
        <software name="TapirProvider" version="1.0"/>
      </source>
    </header>
    <metadata>
      <dc:title>Global Dragonflies Database</dc:title>
      <dc:type>http://purl.org/dc/dcmitype/Service</dc:type>
      <accesspoint>http://example.net/tapir.cgi</accesspoint>
      <dc:description>Global database about Dragonflies observation and specimen records</dc:description>
      <dc:language>en</dc:language>
      <dc:subject>dragonflies dragonfly observation specimen arthropoda insecta odonata</dc:subject>
      <dct:bibliographicCitation>Global Dragonflies Database</dct:bibliographicCitation>
      <dc:rights>Creative Commons License</dc:rights>
      <dct:modified>2006-07-01T09:35:14+01:00</dct:modified>
      <dct:created>2006-01-01T00:00:00+01:00</dct:created>
      <indexingPreferences startTime="01:30:00Z" maxDuration="PT1H" frequency="P1M" />
      <relatedEntity>
        <role>data supplier</role>
        <entity type="organization">
          <identifier>http://purl.org/biodiv/myorg</identifier>
          <name>My Organization</name>
          <acronym>MYORG</acronym>
          <logoURL>http://example.net/myorg.png</logoURL>
          <description>My Organization hosts and maintains biodiversity databases</description>
          <relatedInformation>http://example.net/myorg</relatedInformation>
          <hasContact>
            <role>data administrator</role>
            <vcard:VCARD>
              <vcard:FN>My Name</vcard:FN>
              <vcard:TITLE>Director</vcard:TITLE>
              <vcard:TEL>11 11 11111111</vcard:TEL>
              <vcard:EMAIL>myname@example.net</vcard:EMAIL>
            </vcard:VCARD>
          </hasContact>
          <geo:Point>
            <geo:lat>45.256</geo:lat>
            <geo:long>-71.92</geo:long>
          </geo:Point>
        </entity>
      </relatedEntity>
    </metadata>
  </response>

Example: Example of a metadata response document

5.2. Capabilities

The Capabilities operation is used to retrieve the essential settings and technical information about a TAPIR service.

5.2.1. Capabilities Request

In XML, the Capabilities operation is invoked by inserting the <capabilities/> element after the header section in a request document. Capabilities requests take no arguments or parameters.

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <capabilities/>
  </request>

Example: Example of an XML capabilities request document

In KVP request encoding, the Capabilities operation can be invoked with a single parameter, as follows:

http://example.net/tapir.cgi?op=capabilities

5.2.2. Capabilities Response

Capabilities responses contain five mandatory top level sections to indicate available operations, supported request encodings and parameters, mapped concepts, available variables and global settings. An optional section <archives> can be used to indicate possible dump files available. Another optional <custom> section can be used to include any extra information not covered by the other sections.

5.2.2.1. Operations

The <operations> element is intended to return the list of operations supported by the service, including optional capabilities that are specific to each operation. When an operation is supported, an element with the same name must be present inside the <operations> element. Ping, metadata and capabilities are mandatory operations that are simply declared with no further arguments.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
  </operations>

Example: A provider supporting only the mandatory operations

A provider that supports the inventory operation must indicate one or more supported inventory templates, or the <anyConcepts/> capability. Providers that only support inventory templates should not accept inventory requests that do not reference them. Each inventory template must be indicated with a <template> element with an attribute @location pointing to an external document defining the template. An optional @alias attribute can be specified, in which case the alias can also be used as the value of the template parameter in KVP inventory requests. A WSDL (Web Service Description Language) document describing the inventory template and its interface can optionally be included with an attribute @wsdl.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
    <inventory>
      <templates>
        <template location="http://example.net/tmpl/collector_inventory.xml"/>
        <template location="http://example.net/tmpl/genus_inventory.xml"
                  alias="genus_inventory"
                  wsdl="http://example.net/tmpl/genus_inventory.wsdl" />
      </templates>
    </inventory>
  </operations>

Example: A provider supporting inventory with templates

Providers declaring the <anyConcepts/> capability should accept inventory requests involving one or more concepts that were advertised as being mapped by the provider. They must also support inventory requests involving any external inventory template that references any known concepts. Therefore, providers in this situation must additionally support arbitrary filters. The <anyConcepts/> capability is declared without any further arguments.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
    <inventory>
      <anyConcepts/>
    </inventory>
  </operations>

Example: A provider supporting inventory in any concept

Providers are also allowed to support both <anyConcepts/> and templates, in case they wish to point to specific inventory templates for any particular reason. However providers are not allowed to advertise support of the inventory operation just with an empty <inventory/> element.

If a provider supports the search operation, it must indicate either one or more supported search templates, or the <outputModels/> capability. Providers that only support search templates should not accept search requests that do not reference them. Each search template must be indicated with a <template> element having an attribute @location pointing to an external document defining the template. An optional @alias attribute can be specified, in which case the alias can also be used as the value of the template parameter in KVP search requests. A WSDL (Web Service Description Language) document describing the search template and its interface can optionally be included with an attribute @wsdl.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
    <inventory>
      <anyConcepts/>
    </inventory>
    <search>
      <templates>
        <template location="http://example.net/tmpl/search_by_taxonomy.xml"/>
        <template location="http://example.net/tmpl/search_by_geography.xml"
                  alias="geo"
                  wsdl="http://example.net/tmpl/search_by_geography.wsdl" />
      </templates>
    </search>
  </operations>

Example: A provider supporting search with templates

Providers declaring the <outputModels/> capability should indicate either one or more <knownOutputModels> or the <anyOutputModels> capability. Both can be declared, but an empty <outputModels/> element will be considered invalid.

Providers that only support a specific list of output models must understand filters and "order by" parameters. But they can optionally support the <anyOutputModels> capability. When a provider declares support for a specific output model, it must be able to process any search request that references that same output model, either directly or through a search template. Known output models are declared with the <outputModel> element with a @location attribute pointing to the document defining it. An optional @alias attribute can be specified, in which case the alias can be used as the value of the output model parameter in KVP search requests.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
    <inventory>
      <anyConcepts/>
    </inventory>
    <search>
      <outputModels>
        <knownOutputModels>
          <outputModel location="http://example.net/models/taxonomy_rss.xml"/>
          <outputModel location="http://example.net/models/geography_kml.xml" alias="kml"/>
        </knownOutputModels>
      </outputModels>
    </search>
  </operations>

Example: A provider supporting search with known output models

Providers may also declare the <anyOutputModels> capability, in which case they need to indicate which subset of the XML Schema language they understand. <anyOutputModels> refers to the ability to respond to search requests involving arbitrary output model definitions, assuming they make use of concepts that are mapped by the provider. Output models include a response structure defined with XML Schema. XML Schema is a large and very complex specification and TAPIR does not expect providers to be able to understand or parse the whole language. The minimum set of the XML Schema language that needs to be understood by providers in this case is represented by the <basicSchemaLanguage/> capability, and it includes the following constructs of XML Schema: targetNamespace definition, element definition (including minOccurs and maxOccurs), attribute definitions (including attribute "use"), local definitions of complexType and simpleType, sequences, and the "all" definition. Therefore, when a provider declares the <anyOutputModel> capability, it must declare inside it at least the element <basicSchemaLanguage/>.

  <operations>
    <ping/>
    <metadata/>
    <capabilities/>
    <inventory>
      <anyConcepts/>
    </inventory>
    <search>
      <anyOutputModels>
        <responseStructure>
          <basicSchemaLanguage/>
          <import/>
        </responseStructure>
      </anyOutputModels>
    </search>
  </operations>

Example: A provider supporting search with any output models

The following constructs of XML Schema can be optionally supported and declared as part of the <anyOutputModels> element:

• choice
• group (local group definitions without global referencing)
• import
• include
• references
  • element
  • attribute
  • group
  • attributeGroup
  • complexType
  • simpleType
    • list
    • union
• simpleTypes
  • stringTypes
    • string
      • normalizedString
      • token
      • language
      • Name
      • NCName
      • NMToken
      • NMTokens
      • ID
      • IDREF
      • IDREFS
      • ENTITY
      • ENTITIES
  • numericTypes
    • float
    • double
    • decimal
    • integerTypes
      • integer
      • long
      • int
      • short
      • byte
      • positiveInteger
      • nonPositiveInteger
      • negativeInteger
      • nonNegativeInteger
      • unsignedLong
      • unsignedInt
      • unsignedShort
      • unsignedByte
  • dateTimeTypes
    • duration
    • dateTime
    • time
    • date
    • gYearMonth
    • gYear
    • gMonthDay
    • gDay
    • gMonth
  • miscTypes
    • Boolean
    • base64Binary
    • hexBinary
    • anyURI
    • QName
• extension
• restriction
  • minInclusive
  • maxInclusive
  • minExclusive
  • maxExclusive
  • fractionDigits
  • totalDigits
  • enumeration
  • whiteSpace
  • pattern
  • length
  • minLength
  • maxLength
• substitutionGroup
• constraints
  • field
  • selector
  • unique
  • key
  • keyref

Providers are allowed to support both search templates and output models. However, they are not allowed to advertise support of the search operation with an empty <search/> element.

When providers support search with output models they are also allowed to support both <knownOutputModels> and <anyOutputModels>, but they are not allowed to declare an empty <outputModels/> element.

Besides standard operations, providers can also declare they support custom operations inside an optional <custom> element.

5.2.2.2. Requests

The <requests> element is intended to provide information on what request encodings the service can respond to, whether it handles log-only requests and what filter capabilities are supported.

This section includes three sub-sections:

<encoding>

Indicates what request encodings are supported. The options are <kvp/> (Key-Value Pairs) and <xml/>. Support of key-value pairs is mandatory, while the XML encoding is optional.

<globalParameters>

Indicates if the provider "accepts", "requires" or "denies" log-only requests.

<filter>

Lists the expressions and Boolean operators understood by the provider service and which may be used in constructing filters.

  <requests>
    <encoding>
      <kvp/>
    </encoding>
    <globalParameters>	
      <logOnly>denied</logOnly>
    </globalParameters>
    <filter/>
  </requests>

Example: Fragment of a <requests> declaration in a capabilities response document showing the minimum functionality that a TAPIR service must be able to provide. Note that in this case no filter capabilities are declared.

Filters are used in search and inventory operations. The <filter> element in capabilities responses lists all the filter operations and terms that are supported by the provider. When a provider declares the filter <encoding> element, a minimum set of filtering capabilities must be supported and indicated for the sake of clarity. The only optional filtering capability in this case is related to the arithmetic operators.

  <requests>
    <encoding>
      <kvp/>
      <xml/>
    </encoding>
    <globalParameters>	
      <logOnly>accepted</logOnly>
    </globalParameters>
    <filter>
        <encoding>
          <expression>
            <concept/>
            <literal/>
            <parameter/>
            <variable/>
            <arithmetic>
              <add/>
              <sub/>
              <div/>
              <mul/>
            </arithmetic>
          </expression>
          <booleanOperators>
            <logical>
              <not/>
              <and/>
              <or/>
            </logical>
            <comparative>
              <equals caseSensitive="false"/>
              <greaterThan/>
              <greaterThanOrEquals/>
              <lessThan/>
              <lessThanOrEquals/>
              <in/>
              <isNull/>
              <like caseSensitive="false"/>
            </comparative>
          </booleanOperators>
        </encoding>
    </filter>
  </requests>

Example: A TAPIR provider declaring support to both xml and kvp encoding, accepting log-only requests, and declaring the complete filter functionality.

When a provider supports filters, it can indicate if they are case sensitive or not. When not indicated, it defaults to "true" (case sensitive).

5.2.2.3. Concepts

The <concepts> element is intended to provide details of recognised conceptual schemas and individually mapped concepts from those schemas. At least one conceptual schema must be mapped with at least one concept. The underlying database structure remains opaque to TAPIR clients, which interact with the underlying database by reference to the mapped concepts. Recognised conceptual schemas are declared using the @namespace and @location attributes of the <schema> element, both of which are required and must be valid URIs. An optional @alias can be assigned to the schema.

Within each schema declaration the provider must list the recognised concepts of that schema using the <mappedConcept> element. Each concept is declared through an instance of the <mappedConcept> element, which contains four attributes:

@id

The fully qualified concept identifier. Required. String.

@searchable

Denotes whether the concept can be used in filters. Optional (defaults to "true"). Boolean.

@required

Denotes that this is a mandatory concept that needs to be present in output models of all search requests. Optional (defaults to "false"). Boolean.

@alias

A local alias associated with the concept. Optional. String.

@datatype

Indicates the corresponding datatype of the mapped concept. This will determine the ordering behaviour in results and the I/O data formats supported by the provider for the concept. Must be one of the fully qualified XML Schema primitive datatypes. The datatype declared should always try to match the datatype defined by the conceptual schema. If the conceptual schema uses a non primitive datatype for the concept, this match should happen with the corresponding primitive datatype (going back in the type hierarchy). Optional (defaults to http://www.w3.org/2001/XMLSchema#string). String.

  <concepts>
    <schema namespace="http://example.net/s/1"
            location="http://example.net/s/1/schema.xsd">
      <mappedConcept id="http://example.net/s/1/CollectionCode"/>
      <mappedConcept id="http://example.net/s/1/CollectionName" searchable="false"/>
    </schema>
    <schema namespace="http://example.net/s/2"
            location="http://example.net/s/2/schema.xsd">
      <mappedConcept id="http://example.net/s/2/CatalogNumber" datatype="http://www.w3.org/2001/XMLSchema#decimal"/>
      <mappedConcept id="http://example.net/s/2/Rights" required="true"/>
    </schema>
  </concepts>

Example: Example of a concepts declaration that might appear in a capabilities response document

When a <mappedConcept> and its <schema> are declared with an @alias attribute, providers must be able to understand requests that reference the concept by the short notation: concept_alias@schema_alias. When a <mappedConcept> is declared with an @alias attribute but its <schema> is not, providers must be able to understand requests that reference only the concept by its alias. These two situations do not exempt providers from understanding requests referencing concepts by fully qualified identifiers.

5.2.2.4. Variables

The <variables> element indicates system environment variables that can be used as filter expressions (see section about filter expressions). Each supported variable must be indicated with an element of the same variable name inside the element <environment>. When the <variables> element is empty it means that no variables are supported.

  <variables>
    <environment>
      <accessPoint/>
      <date/>
      <timestamp/>
      <metadataLanguage/>
      <dataSourceName/>
      <dataSourceDescription/>
      <subject/>
      <rights/>
      <bibliographicCitation/>
      <dataSourceLanguage/>
      <lastUpdate/>
      <dateCreated/>
      <technicalContactName/>
      <technicalContactEmail/>
      <contentContactName/>
      <contentContactEmail/>
    </environment>
   </variables>

Example: Fragment of a capabilities response declaring all environmental variables defined by the TAPIR XML Schema and an extra one.

5.2.2.5. Settings

The <settings> element indicates specific service settings related to server overload caused by requests for excessive amounts of data. There are five settings of interest to client software, all of them optional, and further ones can be declared using the <custom> element. The five settings all take positive integer values:

minQueryTermLength

The minimum length of a wildcard string used in "like" expressions.

maxElementRepetitions

The maximum number of repetitions allowed for any repeatable XML elements in search and inventory responses. It can also be used as a reference for paging.

maxElementLevels

The maximum number of nested XML levels allowed for search responses (not including the TAPIR envelope).

maxResponseTags

The maximum number of XML tags that can be returned in responses.

maxResponseSize

The maximum size in kilobytes allowed to be returned in responses.

  <settings>
    <minQueryTermLength>2</minQueryTermLength>
    <maxElementRepetitions>100</maxElementRepetitions>
    <maxElementLevels>20</maxElementLevels>
  </settings>

Example: Fragment of a capabilities response showing service settings.

5.2.2.6. Archives

An <archives> element can be used to advertise one or more dump files available. A dump file contains all records from the provider at a particular time and can be useful for clients that need to harvest entire datasets. When a dump file is available, clients can make use of it when interacting with the provider for the first time, and then use incremental harvesting through the search operation in subsequent interactions. Note that incremental harvesting will only be possible if the provider has mapped some concept that indicates when a record was last edited, and ideally another concept that indicates when a record was deleted. Such concepts should be part of a data abstraction layer and are therefore outside the scope of this specification.

Each dump file is represented by an <archive> element that can contain the following attributes:

@format

Format of the archive. It can be "xml" or any custom value. Mandatory. String.

@location

URL from where the archive can be downloaded. Mandatory. Any URI.

@creation

Timestamp when the archive was created. Mandatory. DateTime.

@compression

When the archive is compressed, this attribute must be present to indicate the type of compression. When present, it can be "gzip" or any custom value. When absent, no compression was used. Optional. String.

@numberOfRecords

Number of records in the archive. Mandatory. Integer.

@outputModel

Output model used to generate the archive. This attribute should only be present if the archive format is "xml". Optional. Any URI.

  <archives>
    <archive format="xml" 
             location="http://example.net/file.gz" 
             creation="2005-10-31T12:23:56.023+01:00" 
             compression="gzip" 
             numberOfRecords="351056" 
             outputModel="http://example.net/model.xml"/>
  </archives>

Example: A provider advertising a dump file with all records at a specific time

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0 
                                http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source accesspoint="http://example.net/tapir.cgi" 
              sendtime="2005-11-11T12:23:56.023+01:00">
        <software name="TapirProvider" version="1.0"/>
      </source>
    </header>
    <capabilities>
      <operations>
        <ping/>
        <metadata/>
        <capabilities/>
        <inventory>
          <anyConcepts/>
        </inventory>
        <search>
          <outputModels>
            <anyOutputModels>
              <responseStructure>
                </basicSchemaLanguage>
              </responseStructure>
            </anyOutputModels>
          </outputModels>
        </search>
      </operations>
      <requests>
        <encoding>
          <kvp/>
          <xml/>
        </encoding>
        <globalParameters>	
          <logOnly>accepted</logOnly>
        </globalParameters>
        <filter>
            <encoding>
              <expression>
                <concept/>
                <literal/>
                <parameter/>
                <variable/>
                <arithmetic/>
              </expression>
              <booleanOperators>
                <logical>
                  <not/>
                  <and/>
                  <or/>
                </logical>
                <comparative>
                  <equals caseSensitive="false"/>
                  <greaterThan/>
                  <greaterThanOrEquals/>
                  <lessThan/>
                  <lessThanOrEquals/>
                  <in/>
                  <isNull/>
                  <like caseSensitive="false"/>
                </comparative>
              </booleanOperators>
            </encoding>
        </filter>
      </requests>
      <concepts>
        <schema namespace="http://example.net/s"
                location="http://example.net/s/schema.xsd">
          <mappedConcept id="http://example.net/s/CatalogNumber"/>
          <mappedConcept id="http://example.net/s/ScientificName"/>
        </schema>
      </concepts>
      <variables/>
      <settings>
        <minQueryTermLength>2</minQueryTermLength>
        <maxElementRepetitions>100</maxElementRepetitions>
        <maxElementLevels>20</maxElementLevels>
      </settings>
    </capabilities>
  </response>

Example: Example of a full capabilities response document containing only the mandatory sections

5.3. Inventory

The Inventory operation is used to retrieve distinct values for one or more concepts specified as parameters. It returns aggregated data in the mode of a DISTINCT select in SQL, as opposed to individual records returned by the Search operation. When more than one concept is specified, inventory responses must return distinct combinations of values.

Concepts used as parameters may come from different conceptual schemas and must be specified either with their fully qualified identifiers or with aliases. If aliases are used, the TAPIR implementation must be configured to use the relevant concept name server.

If a provider supports the inventory operation, it must advertise either one or more inventory templates or support the <anyConcepts> capability. Providers may support both options and choose how they wish to process requests.

5.3.1. Inventory Request

Inventory requests can make use of inventory templates or may specify the concept(s) and an optional filter directly in the message. Paging parameters can also be used.

In XML, the inventory operation can be invoked by inserting the <inventory> element after the header section in a request document, and then specifying an inventory template or the specific parameters.

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <inventory>
      <template location="http://example.net/tmpl/genus_inventory.xml"/>
    </inventory>
  </request>

Example: Example of an XML inventory request document using a template.

In KVP request encoding, the same example could be invoked with:

http://example.net/tapir.cgi?op=inventory&template= http://example.net/tmpl/genus_inventory.xml

If the template included a filter with a parameter "type" restricting results according to the basis of record, it could be invoked with

http://example.net/tapir.cgi?op=inventory&template= http://example.net/tmpl/genus_inventory.xml&type=specimen

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <inventory>
      <concepts>
        <concept id="http://example.net/schema1/Country"/>
        <concept id="http://example.net/schema1/Genus"/>
      </concepts>
    </inventory>
  </request>

Example: Example of an XML inventory request document (looking for unique combinations of genus and country) specifying concepts but no filter.

In KVP request encoding, the same example could be invoked with

http://example.net/tapir.cgi?op=inventory&concept=http://example.net/schema1/Country& concept=http://example.net/schema1/Genus

or, using concept aliases

http://example.net/tapir.cgi?op=inventory&count=false&start=0&limit=100& concept=Country@schema1&concept=Genus@schema1

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <inventory count="true" limit="100" start="0">
      <concepts>
        <concept id="http://example.net/schema1/Country" tagName="country"/>
        <concept id="http://example.net/schema1/Genus" tagName="genus"/>
      </concepts>
      <filter>
        <like>
          <concept id="http://example.net/schema1/Genus"/>
          <literal value="Luzu*"/>
        </like>
      </filter>
    </inventory>
  </request>

Example: Example of an XML inventory request document (looking for unique combinations of genus and country) specifying concepts, custom tag names for the resulting values, paging parameters and a filter.

In KVP request encoding, the same example could be invoked with

http://example.net/tapir.cgi?op=inventory&count=true&start=0&limit=100& concept=Country@schema1&concept=Genus@schema1&tagname=country&tagname=genus& filter=Genus@schema1 like "Luzu*"

5.3.2. Inventory Response

The structure of inventory responses must conform to the "inventoryResultType" defined in the TAPIR XML Schema. The body of the inventory message must list the concepts used to create the inventory using the <concepts> element. Individual inventory records, which represent unique combinations of multiple concepts, are returned as one or more <record> elements.

Each <record> element lists the value or values found in the order that concepts are listed under <concepts>. If count was requested, then each <record> must include an attribute @count, giving the number of occurrences of this combination in the underlying data source. If paging was requested, then a <summary> element must also be returned. The order of <record> elements should be ascending according to the concept's datatype declared in the capabilities response.

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0 
                                http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source accesspoint="http://example.net/tapir.cgi" 
              sendtime="2005-11-11T12:23:56.023+01:00">
        <software name="TapirService" version="1.0"/>
      </source>
    </header>
    <inventory>
      <concepts>
        <concept id="http://example.net/schema1/Country"/>
        <concept id="http://example.net/schema1/Genus"/>
      </concepts>
      <record>
        <value>AUSTRALIA</value>
        <value>Calicium</value>
      </record>
      <record>
        <value>AUSTRALIA</value>
        <value>Fellhanera</value>
      </record>
      <summary start="0" next="2" totalReturned="2" totalMatched="35"/>
    </inventory>
  </response>

Example: An inventory response showing country and genus combinations

If the request references an unmapped concept an <error> should be returned.

When the request specifies a custom "tagName" for the concept, then this name should be used instead of the default <value> tag.

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0 
                                http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source accesspoint="http://example.net/tapir.cgi" 
              sendtime="2005-11-11T12:23:56.023+01:00">
        <software name="TapirService" version="1.0"/>
      </source>
    </header>
    <inventory>
      <concepts>
        <concept id="http://example.net/schema1/Country"/>
        <concept id="http://example.net/schema1/Genus"/>
      </concepts>
      <record>
        <country>AUSTRALIA</country>
        <genus>Calicium</genus>
      </record>
      <record>
        <country>AUSTRALIA</country>
        <genus>Fellhanera</genus>
      </record>
      <summary start="0" next="2" totalReturned="2" totalMatched="35"/>
    </inventory>
  </response>

Example: An inventory response showing country and genus combinations with values enclosed by custom tag names

5.4. Search

The Search operation is used to return non-aggregate records from data sources. Search requests make use of output models and filters to select the requested data. The returned records may also be counted and paged.

If a provider supports the search operation, it must advertise either one or more search templates or it must support the <outputModels> capability. Providers may support both options and choose how they wish to process requests. If a provider supports the <outputModels> capability, it must advertise either one or more known output models or it must support the <anyOutputModels> capability.

5.4.1. Search Request

Search requests can make use of search templates or specify all parameters directly in the message. Paging parameters can also be used.

In XML, the search operation can be invoked by inserting the <search> element after the header section in a request document, and then specifying a search template or the specific parameters.

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00">
      </source>
    </header>
    <search>
      <template location="http://example.net/tmpl/search_by_taxon.xml"/>
    </search>
  </request>

Example: Example of an XML search request document using a template.

In KVP request encoding, the same example could be invoked with

http://example.net/tapir.cgi?op=search&template= http://example.net/tmpl/search_by_taxon.xml

If the template included a filter with a parameter "genus" restricting results according to a specified genus name, it could be invoked with

http://example.net/tapir.cgi?op=search&template= http://example.net/tmpl/search_by_taxon.xml&genus=Physalis

In addition to referring to external output models (both those known to the provider and user defined ones) by their URI, it is possible to declare an output structure directly within a request document through the <outputModel> element, whose structure is exactly as that used in external models.

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                               http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source sendtime="2005-11-11T12:23:56.023+01:00"/>
    </header>
    <search count="true" start="0" limit="1000">
      <outputModel>
        <structure>... concepts and relationships ... </structure>
        <rootElement name="... name of global element ..."/>
        <indexingElement path="... node path(s) for paging and counting ..."/>
        <mapping>... concept mapping elements ...</mapping>
      </outputModel>
      <filter>
        <like>
          <concept id="http://example.net/schema/ScientificName"/>
          <literal value="Luzu*"/>
        </like>
      </filter>
      <orderBy>
        <concept id="http://example.net/schema/Family"/>
        <concept id="http://example.net/schema/ScientificName"/>
      </orderBy>
    </search>
  </request>

Example: Simplified example of an XML search document with in-line outputModel definition

When used in KVP encoding, output models must always be externally defined, and referenced by the parameter "model". Output model definitions cannot be encoded in KVP.

http://example.net/tapir.cgi?op=search&start=0&limit=10& model=http://example.net/models/specimens.xml&filter= http://example.net/schema/ScientificName like "Luzu*"&orderby= http://example.net/schema/ScientificName

The same example with concept aliases would be

http://example.net/tapir.cgi?op=search&start=0&limit=10& model=http://example.net/models/specimens.xml&filter= ScientificName@schema like "Luzu*"&orderby= ScientificName@schema

Search operations also include the possibility to remove the TAPIR envelope, i.e., only the content that goes inside the "search" element is returned. This can be specified by the parameter "envelope". In XML it is an optional attribute (defaults to false) of the element search, and in KVP it is an independent parameter with the same name.

If an error occurs when the envelope in turned off, the response should be an "error" element containg the error message. It should usually be possible to get more information about the error by sending another request with envelope turned on and then inspecting the diagnostics.

5.4.2. Search Response

All methods of formulating search queries are processed by the provider software to select data from its underlying data source and to return to the client in the form of an XML response message. The way in which the provider chooses to do this is not defined by the protocol. Search responses with the TAPIR envelope must validate against the "searchResultType" defined by the TAPIR XML Schema.

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
    <header>
      <source accesspoint="http://example.net/tapir.cgi" 
              sendtime="2005-11-11T12:23:56.023+01:00"/>
    </header>
    <search>
      <dataset xmlns="http://example.net/simple_specimen">
        <specimen catnum="234">
           <identification>
             <name>Luzula luzuloides</name>
           </identification>
        </specimen>
        <specimen catnum="290">
          <identification>
            <name>Luzula alpestris</name>
          </identification>
        </specimen>
      </dataset>
      <summary start="0" totalReturned="2"/>
    </search>
  </response>

Example: Example of a search response document.

5.5. Ping

The Ping operation provides a means of establishing whether services are currently on-line and whether appropriate wrapper software is installed. This operation can also provide basic data about response times. It does not require a query to be run against a connected database, as is sometimes required of metadata and capabilities requests. Data providers are free to include as part of diagnostics any extra information that may be of value to monitor networks.

5.5.1. Ping Request

In XML, the ping operation is invoked by inserting the <ping/> element after the header section in a request document. Ping takes no arguments or parameters.

  <?xml version="1.0" encoding="UTF-8"?>
  <request xmlns="http://rs.tdwg.org/tapir/1.0"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
                                      http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
  <header>
    <source sendtime="2005-11-11T12:23:56.023+01:00">
         <software name="TapirClient" version="1.0"/>
    </source>
  </header>
    <ping/>
  </request> 

Example: TAPIR Ping Request. The simplest operation in TAPIR.

In KVP request encoding, the ping operation can be invoked with a single parameter

http://example.net/tapir.cgi?op=ping

5.5.2. Ping Response

  <?xml version="1.0" encoding="UTF-8"?>
  <response xmlns="http://rs.tdwg.org/tapir/1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
            http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd">
  <header>
    <source accesspoint="http://example.net/tapir.cgi" 
            sendtime="2005-11-11T12:23:57.023+01:00">
         <software name="TapirProvider" version="1.0"/>
    </source>
  </header>
    <pong/>
  </response> 

6. Global Parameters

All operations can make use of global common parameters. In XML, global parameters are passed as specific attribute values of the operation element, and are defined in the "globalParametersGroup". In KVP, they are passed as individual parameters. The list of global parameters include:

log-only

The log-only parameter can be used to instruct the service to log the request but not process it as it would normally do. It can be used to forward requests to the original providers, when users are querying third-party cached databases. This way, original providers can track usage of their data. Although it is possible to send log-only requests, clients must check the provider capabilities response before sending them. The <globalParameters> element of capabilities responses declares if log requests are required, accepted or denied. Providers that are unable to log requests on their system or do not want to receive them, should reply to a log-only request with an error message using the <error> element. If log-only requests are accepted or required, then the response must include the element <logged/> instead. Boolean. Optional (defaults to "false").

xslt

The xslt parameter points to an XML style sheet that can be used by XSLT processors to transform TAPIR responses. When xslt is specified, providers are instructed to include the corresponding "xml-stylesheet" processing instruction after the XML header, as shown below. However, providers are also free to place restrictions on the allowable domains related to the stylesheet location. In this case, if a stylesheet comes from an unknown location, it can be ignored - but an associated warning should be raised inside the diagnostics section. String representing a URL. Optional.

  <?xml version="1.0" encoding="utf-8" ?>
  <?xml-stylesheet type="text/xsl" href="http://example.net/trans.xsl"?>
  <!-- TAPIR response -->

Example: Fragment of a TAPIR response showing the XML headers when the xslt parameter is passed.

7. Counting and Paging

Inventory and search operations include counting and paging functionality. Both are done with reference to an indexing element (search operation) or to a record element (inventory operation). In XML, counting and paging parameters are defined in the "pagingParametersGroup" and passed as attribute values of the operation element. In KVP, counting and paging is done through specific individual parameters.

count

For Inventory operations the count parameter instructs the service to return the total number of distinct records and number of occurrences of each record matching the selection criteria. For search operations, the count parameter instructs the service to return the number of records returned and the number of records that matched the query in the @returned and @totalMatched attributes of the <summary> element respectively. Boolean. Optional (default = "false")

start

Index of the first record to be returned when paging results. Non-negative integer. Optional (default = "0", which corresponds to the index of the first record).

limit

Indicates the maximum number of records to be returned when paging results. If a request asks for count but specifies limit = "0" then no records are returned but the total number of records found is recorded in @totalMatched. Non-negative integer. Optional (when not specified it means "unlimited").

In XML, a typical use of paging parameters attributes would be

    <search count="true" start="0" limit="50">
     ....... 
    </search>

The same parameters in KVP would be

http://example.net/tapir.cgi?op=search&count=1&start=0&limit=50&...

When paging is requested, response documents must include a <summary> element of the "resultSummaryType", which returns information in the following set of attributes:

@start

Index of the first element that was returned.

@next

Index of the next record that could be retrieved using a subsequent request.

@totalReturned

The number of records actually being returned.

@totalMatched

If count was requested the totalMatched attribute gives the "estimated" number of total matching records - not necessarily the number of valid records that can possibly be returned by paging through the entire record set. This happens because records can be "dropped" or ignored if they fail to produce a valid XML representation according to the response structure.

  ...
  <record count="10">
    <value>AUSTRALIA</value>
    <value>Calicium</value>
  </record>
  <record count="20" >
    <value>AUSTRALIA</value>
    <value>Fellhanera</value>
  </record>
  <summary start="0" next="2" totalReturned="2" totalMatched="35"/>
  ...

Example: Fragment of an inventory response showing count and paging values.

8. Filters, Expressions and Operators

8.1. Filters

Inventory and search operations may contain a filter specifying conditions to restrict returned data to a specific subset. TAPIR filters encode expressions and operators in an atomised form that can be translated to other query languages (e.g., SQL).

The ability to dynamically parse filters is optional in TAPIR and can be expressed as part of the capabilities response. Providers that do not support filters may still support query templates advertised in their capabilities. In this case, when the query template includes a filter in its definition, the meaning and the functionality of the filter must be understood by the provider. The provider may hard code a local query that translates the entire filter and then, when processing a request, substitute parameters that are usually present in query template's filters with their respective values.

8.2. Expressions

The atomised values in a TAPIR filter are represented by expressions. There are three types of expressions in TAPIR: simple expressions, complex expressions and variables. Expressions evaluate to a single value and are used by filter operators.

8.2.1. Simple Expressions

Simple expressions include elements that are directly associated with a single value. There are three possible types of simple expressions:

• Literal: Any string. In XML, literals are represented by a <literal> element that must include the respective value in the attribute @value:

     <literal value="42" />
  

• Concept: An element representing a concept from a conceptual schema. When used in filters, concepts must be related to a property or attribute that can be associated with a specific content in a local data source. In XML, a concept expression is represented by a <concept> element that must contain the concept identifier in the attribute @id:

    <concept id="http://example.net/concept/scientificName" />
  

• Parameter: An element that can be used to point to external values provided by the calling message. In XML, parameters are represented by the element <parameter> that must include the parameter name in the attribute @name:

    <parameter name="sname" />
  

  The expression above instructs a program to get the value from the respective HTTP GET or HTTP POST parameter. Considering the GET request below, the previous example would evaluate to the literal value "Helix":
  http://example.net/wrapper.cgi?op=search&template=http://example.net/tmpl&sname=Helix
  Attention is required to choose parameter names that do not conflict with the reserved TAPIR parameters. Any name from the list of reserved parameters is not allowed to be present in filters.

8.2.2. Complex Expressions

Complex expressions are represented by four arithmetic operators. The list below shows the arithmetic operators followed by their respective XML element.

• add: <add>
• divide: <div>
• multiply: <mul>
• subtract: <sub>

Arithmetic operators are binary, so they always combine exactly two expressions as their arguments. The first argument must always be associated with the leftmost expression in the operation. This means that in subtractions the first expression corresponds to the minuend and the second corresponds to the subtrahend. In divisions the first expression corresponds to the divident while the second corresponds to the divisor.

  <add>
    <literal value="20" />
    <literal value="22" />
  </add>

Example: Use of a binary arithmetic operator.

8.2.3. Variables

Variables are elements that represent environment variables from the data provider system. TAPIR defines the following system variables that may be supported by provider implementations:

• date: Represents the current date according to the XML Schema date type (ISO 8601). Example: 2006-07-21

• timestamp: Represents the current timestamp according to the XML Schema dateTime type (ISO 8601). Example: 2006-07-20T17:01:38+02:00

• accessPoint: Represents the service access point.

• dataSourceName: Represents the name of the data source (the service "title" as advertised in metadata responses).

• dataSourceDescription: Represents the description of the data source (the service "description" as advertised in metadata responses).

• subject: Keywords, key phrases or classification codes that describe content provided by the data source (the service "subject" as advertised in metadata responses).

• rights: Information about who can access the resource or about its security status, access regulations, etc. (the service "rights" as advertised in metadata responses).

• bibliographicCitation: Information about how to cite the data source (the service "bibliographicCitation" as advertised in metadata responses).

• metadataLanguage: The language in which the content of the following variables are expressed: dataSourceName, dataSourceDescription, rights, subject and bibliographicCitation..

• dataSourceLanguage: The primary language of the data provided by the service (the first "dc:language" element advertised in metadata responses).

• technicalContactName: The name of the first system administrator of the first technical host entity in metadata responses.

• technicalContactEmail: The e-mail of the first system administrator of the first technical host entity in metadata responses.

• contentContactName: The name of the first data administrator of the first data supplier entity in metadata responses.

• contentContactEmail: The e-mail of the first data administrator of the first data supplier entity in metadata responses.

• lastUpdate: Represents the timestamp when the underlying data was last updated. Format must follow the XML Schema dateTime type (ISO 8601).

• dateCreated: Represents the timestamp when the data source was created. Format must follow the XML Schema dateTime type (ISO 8601).

In XML, variables are represented by a <variable> element with a "name" attribute, such as

  <variable name="date" />

Variables that are supported by a data provider must be advertised in capabilities responses. Data providers are also free to define and make use of additional system variables.

8.3. Logical and Comparative Operators

TAPIR supports a range of Boolean (logical and comparative) operators for building filters.

8.3.1. Comparative Operators

There are three types of comparative operators - unary, binary, and multiple.

8.3.1.1. Unary Comparative Operators

Unary comparative operators always take a single concept as argument. The only operator of this type is the isNull operator.

• isNull: Evaluates to true if the value associated with the concept is NULL. In XML, this operator is represented by the element <isNull>.

    <isNull>
      <concept id="http://example.net/concept/country" />
    </isNull>
  

8.3.1.2. Binary Comparative Operators

Binary comparative operators always compare a concept with an expression. The first argument must always be the concept and is associated with the leftmost expression in the operation. The following operators are binary:

• equals: The "equals" (=) comparison operator. When used in string comparisons, case sensitivity is indicated as part of the capabilities response. In XML, this operator is represented by the element <equals>.

    <equals>
      <concept id="http://example.net/concept/genus" />
      <literal value="Rubus" />
    </equals>
  

• like: The "like" operator used in character string comparisons. It checks if a string value matches a given pattern. The wildcard is represented by the character "*". Case sensitiveness is indicated as part of the capabilities response. In XML, this operator is represented by the element <like>. Not specifying any wildcard in the corresponding literal is equivalent to specifying two wildcards: one in the beginning and the other in the end of the literal value. When the character "*" is not meant to be a wildcard, it should be escaped by including "_" before the "*" character.

    <like>
      <concept id="http://example.net/concept/commonName" />
      <literal value="*thrush" />
    </like>
  

• greaterThan: The greater than (>) comparison operator. In XML, this operator is represented by the element <greaterThan>.

    <greaterThan>
      <concept id="http://example.net/concept/yearCollected" />
      <literal value="1990" />
    </greaterThan>
  

• greaterThanOrEquals: The greater than or equals (>=) comparison operator. In XML, this operator is represented by the element <greaterThanOrEquals>.

    <greaterThanOrEquals>
      <concept id="http://example.net/concept/individualCount" />
      <literal value="3" />
    </greaterThanOrEquals>
  

• lessThan: The less than (<) comparison operator. In XML, this operator is represented by the element <lessThan>.

    <lessThan>
      <concept id="http://example.net/concept/yearCollected" />
      <literal value="1870" />
    </lessThan>
  

• lessThanOrEquals: The less than or equals (<=) comparison operator. In XML, this operator is represented by the element <lessThanOrEquals>.

    <lessThanOrEquals>
      <concept id="http://example.net/concept/altitude" />
      <literal value="500" />
    </lessThanOrEquals>
  

8.3.1.3. Multiple Comparative Operators

Multiple comparative operators always compare a concept with one or more simple expressions. This operator is equivalent to a sequence of "or" operators comprising equals comparisons between the concept and each simple expression. The only operator of this type is the "in" operator.

• in: The "in" operator checks if a concept is equals to one of the values in a list. When used in string comparisons, case sensitivity is indicated as part of the capabilities response of the equals operator. In XML, this operator is represented by the element <in>.

    <in>
      <concept id="http://example.net/concept/basisOfRecord" />
      <values>
        <literal value="specimen" />
        <literal value="observation" />
      </values>
    </in>
  

8.3.2. Logical operators

There are two types of logical operators – unary and multiple.

8.3.2.1. Unary Logical Operators

Unary logical operators take as argument a single Boolean operator, which can be any comparison operator or any logical operator.

• not: This operator specifies that matching records must not meet the specified condition. In XML, this operator is represented by the element <not>.

    <not>
      <like>
        <concept id="http://example.net/concepts/speciesName"/>
        <literal value = "Helix*"/>
      </like>
    </not>
  

8.3.2.2. Multiple Logical Operators

Multiple logical operators combine two or more Boolean operators, which can be any comparison operator or any logical operator.

• and: The "and" operator is used to connect two or more Boolean conditions, which must all evaluate to true in order for the composite to be true. In XML, this operator is represented by the element <and>.

    <and>
      <equals>
        <concept id="http://example.net/concept/genus" />
        <parameter name="genus" />
      </equals>
      <equals>
        <concept id="http://example.net/concept/species" />
        <parameter name="species" />
      </equals>
      <equals>
        <concept id="http://example.net/concept/subspecies" />
        <parameter name="subspecies" />
      </equals>
    </and>
  

• or: The "or" operator is used to connect two or more Boolean conditions. The compound condition evaluates to true if at least one of the conditions evaluates to true. In XML, this operator is represented by the element <or>.

    <or>
      <lessThan>
        <concept id="http://example.net/concept/latitude" />
        <literal value="-90.00" />
      </lessThan>
      <greaterThan>
        <concept id="http://example.net/concept/latitude" />
        <literal name="90.00" />
      </greaterThan>
    </or>
  

8.4. Additional Interpretation Rules

When a TAPIR provider receives a request, there are additional rules that need to be followed when interpreting filters:

• A comparative operator that references an unspecified parameter must be ignored (as if it was not part of the filter).
• A comparative operator must always evaluate to false when it references a concept that is not understood by the provider (i.e., the concept is not listed as a mapped concept in the capabilities response), unless the comparative operator also references an unspecified parameter - in which case the operator must be ignored instead.
• When ignoring a comparative operator, if it was part of a logical operator then the logical operator should also be ignored if there are no boolean (logical or comparative) operators left inside.
• When ignoring a logical operator, if it was part of another logical operator, then the outer logical operator should also be ignored if there are no boolean (logical or comparative) operators left inside.

9. KVP (Key-Value Pair) Requests

TAPIR requests can be encoded as KVP, as opposed to the XML encoding, and can be sent through HTTP GET or HTTP POST. Therefore, interaction with a TAPIR service can be done by means of URLs using CGI-style parameters. For instance, to ping a TAPIR service one can use the simple KVP GET encoded message

http://example.net/tapir.cgi?op=ping

All TAPIR operations can be invoked with KVP, though output model definitions cannot be expressed with KVP.

9.1. Parameter Rules

Parameter names are always case insensitive. Parameter values are case insensitive by default, except when used with "equals" or "like" comparisons and the provider explicitly declared these operators to be case sensitive (see capabilities response for more details).

Parameters may be specified in any order. Any unknown parameters can be ignored. Parameters without values can also be ignored.

When creating custom parameters in filters, it is necessary to make sure that their names do not conflict with TAPIR specific parameters (see Appendix for the full list of reserved parameter names).

9.2. Global Parameters

The following parameters can be used in all TAPIR operations:

op = [ p | ping | m | metadata | c | capabilities | i | inventory | s | search ]

Specifies the requested TAPIR operation.

• default = metadata : if op is not specified the service must send back a metadata response
• cardinality = 1..1 : only one operation is allowed per request

xslt = [ URI ]

Gives the address of an XML style sheet to be included after the XML header.

• default = null
• cardinality = 0..1

log-only = [ true | false | 1 | 0 ]

Used to indicate if the request should only be logged, not processed. Returns a log message instead of data.

• default = false
• cardinality = 0..1

source-ip = [ URI | NONE ]

Used to indicate the IP address of the original client when the message was processed by intermediate agents.

• default = null
• cardinality = 0..1

9.3. Ping Parameters

op = [ ping | p ]

The ping request has no other parameters.

9.4. Metadata Parameters

op = [ metadata | m ]

The metadata request has no other parameters.

9.5. Capabilities Parameters

op = [ capabilities | c ]

The capabilities request has no other parameters

9.6. Inventory Parameters

op = [ inventory | i ]

cnt, count ::= [ true | false | 1 | 0 | NONE ]

Indicates if the total number of distinct records and the number of occurrences for each record must be returned.

• default = false
• cardinality = 0..1

s, start = [ non-negative integer | NONE ]

Index of the first record to be returned.

• default = 0 (defaults to the first record in the matching data)
• cardinality = 0..1

l, limit = [ non-negative integer | NONE ]

The number of records to be returned.

• default = NONE (all matching records are returned by default)
• cardinality = 0..1

A choice must be made to use either a template, or one or more direct references to concepts with an optional filter.

t, template = [ URI | string ]

The URL of an Inventory Template document or an alias of a template declared in the capabilities response. When a template is present the concept and filter parameters are ignored.

• default = null
• cardinality = 0..1 (optional and only one template is allowed)

OR

c, concept = [ fully qualified identifiers or aliases ]

One or more concepts.

• default = UNDEFINED (which must be interpreted by any provider implementation to mean no concept, which will result in an empty response)
• cardinality = 0..n (at least one concept must be included if no template is specified)

n, tagname = [ string ]

One or more custom tag names (one for each concept).

• default = "value"
• cardinality = 0..n (optional, but when specified there must be one tagname for each concept)

f, filter = [ expression ]

A KVP filter.

• default = null (no filter used)
• cardinality = 0..1 (optional and only one filter statement is allowed)

9.7. Search Parameters

op = [ search | s ]

cnt, count = [ true | false | 1 | 0 | NONE ]

Indicates if the count of the records returned in the response and the number of matching records should be returned.

• default = false
• cardinality = 0..1

s, start = [ non-negative integer | NONE ]

Index of the first record to be returned.

• default = 0 (defaults to the first record in the matching data)
• cardinality = 0..1

l, limit = [ non-negative integer | NONE ]

The number of records to return.

• default = NONE (all matching records are returned by default)
• cardinality=0..1

e, envelope = [ true | false | 1 | 0 | NONE ]

Indicates if the TAPIR envelope (response, header, search, summary and diagnostics tags) should be suppressed or not.

• default = true
• cardinality = 0..1

A choice must be made to use either a template, or an output model parameter with optional "filter" and "orderby" parameters. The "template" parameter takes precedence over the "model" so if both are present the "model" and the optional "filter" and "orderby" parameters should be ignored.

t, template = [ URI | string ]

The URL of a Search Template document or an alias of a template declared in the capabilities response. When a template is present, the model, filter, orderby and descend parameters should be ignored.

• default = null
• cardinality = 0..1

OR

m, model = [ URI | string ]

The URL of an output model document or an alias of an output model declared in the capabilities response.

• default = null
• cardinality=0..1 (when both template and model are present, the model parameter must be ignored)

f, filter = [ expression ]

A KVP filter.

• default = null
• cardinality = 0..1

o, orderby = [ fully qualified concept identifiers or aliases ]

One or more concept identifiers to order results.

• default = null (no particular order)
• cardinality = 0..n

d, descend = [ true | false | 1 | 0 ]

Indicates if the order should be ascending or descending for each concept specified in "orderby". When present, it must have the same number of instances of "orderby".

• default = false (ascending order)
• cardinality = 0..n

9.8. Filters

Filter expressions in KVP requests will be infix equivalents to their XML counterparts.

9.8.1. Backus-Naur Form (BNF) Grammar for Filter Expressions

  <expression>                    ::= <logical_operator> | <comparative_operator>
  
  <comparative_operator>          ::= <unary_comparison_expression> |
                                      <binary_comparison_expression> | 
                                      <unbound_comparison_expression>
  
  <logical_operator>              ::= <unary_logical_expression> | <binary_logical_expression>
  
  <literal>                       ::= '"' <string> '"'
  
  <concept>                       ::= <concept_alias> | <qualified_concept>
  
  <concept_alias>                 ::= <local_concept_alias> "@" <namespace_alias>
  
  <local_concept_alias>           ::= <string>
  
  <namespace_alias>               ::= <string>
  
  <qualified_concept>             ::= <string>
  
  <value>                         ::= <literal> | <concept> | <arithmetic_expression>
  
  <arithmetic_expression>         ::= <value> <arithmetic_operator> <value>
  
  <unary_comparison_expression>   ::= <unary_comparison_operator> <concept>
  
  <binary_comparison_expression>  ::= <value> <binary_comparison_operator> <value>
  
  <unbound_comparison_expression> ::= <unbound_comparison_operator> <expression> {<expression>}
  
  <unary_logical_expression>      ::= <unary_logical_operator> <expression>
  
  <binary_logical_expression>     ::= <expression> <binary_logical_operator> <expression>
  
  <unary_comparison_operator>     ::= "isNull"
  
  <binary_comparison_operator>    ::= "equals" | "like" | "greaterThan" | "lessThan" | 
                                      "greaterThanOrEquals" | "lessThanOrEquals"
  
  <unbound_comparison_operator>   ::= "in"
  
  <unary_logical_operator>        ::= "not"
  
  <binary_logical_operator>       ::= "and" | "or"
  
  <arithmetic_operator>           ::= <add> | <div> | <mul> | <sub>
  
  <add>                           ::= "+"
  <sub>                           ::= "-"
  <mul>                           ::= "*"
  <div>                           ::= "/"
  
  <string>                        ::= <any_char> { <any_char> }

9.8.2. Operators Precedence

Following are lists showing the precedence of filter operators:

expressions

arithmetic_operator, comparative_operator, logical_operator

arithmetic_operators

mul, div, add, sub

comparative_operators

isNull, equals, like, greaterThan, lessThan, greaterThanOrEquals, lessThanOrEquals

logical_operators

not, and, or

Blocks can be formed by using simple parentheses ( ).

9.8.3. Examples

  isnull country@cs1 or FullScientificName@cs2 like "Abies*" and country@cs1 equals "Spain"

The same example can be more explicit using parentheses, as follows:

  ((isnull country@cs1) or ((FullScientificName@cs2 like "Abies*") and (country@cs1 equals "Spain")))

10. The TAPIR XML Schema

The official version of the TAPIR XML Schema (tdwg_tapir.xsd) is located at:

http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd

11. Appendix

11.1. Reserved Parameter Names

Parameter names defined in filters can be any string valid according to the HTTP Common Gateway Interface (CGI) standard. But as TAPIR operations can be called through pure KVP requests, some parameter names are reserved as TAPIR parameters and cannot be used as parameter names in filters.

The following parameter names are reserved for TAPIR:

  c
  cnt
  concept
  count
  descend
  d
  e
  envelope
  f
  filter
  l
  limit
  log-only
  m
  model
  n
  o
  op
  orderby
  s
  start
  t
  tagname
  template
  xslt

11.2. Simple XML Encoding for Conceptual Schemas

The following XML Schema defines a standard encoding that can be used to describe conceptual schemas:

  <?xml version="1.0"?>
  <xsd:schema targetNamespace="http://rs.tdwg.org/tapir/cns/1.0" 
              xmlns="http://rs.tdwg.org/tapir/cns/1.0" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema"
              elementFormDefault="qualified" 
              attributeFormDefault="unqualified" xml:lang="en" >
    <xsd:annotation>
      <xsd:documentation>
        Simple XML Encoding to describe Conceptual Schemas used by TAPIR networks.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:element name="cns">
      <xsd:annotation>
        <xsd:documentation>
          Root element consisting of one schema element.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="schema" type="conceptualSchemaType"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
    <xsd:complexType name="conceptualSchemaType">
      <xsd:annotation>
        <xsd:documentation>
          Type representing a conceptual schema. It must contain the namespace attribute,
          one or more label elements (for different languages), one or more location 
          elements (when the conceptual schema can be downloaded from multiple places) 
          and one concepts element with at least one concept. An optional alias can be 
          assigned to the schema.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:sequence>
        <xsd:element name="label" type="langType" maxOccurs="unbounded"/>
        <xsd:element name="alias" type="xsd:string" minOccurs="0"/>
        <xsd:element name="location" type="xsd:anyURI" maxOccurs="unbounded"/>
        <xsd:element name="concepts">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="concept" type="conceptType" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
      <xsd:attribute name="namespace" type="xsd:anyURI" use="required"/>
    </xsd:complexType>
    <xsd:complexType name="conceptType">
      <xsd:annotation>
        <xsd:documentation>
          Type representing a concept. It must contain the id attribute and the
          datatype element. An optional alias and documentation (doc) element can be 
          present. The documentation be a textual description or a link. The required 
          attribute can be used to indicate if this concept is mandatory or not.
          Although not enforced by this schema, the datatype must be a fully qualified 
          XML Schema primitive datatype.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:sequence>
        <xsd:element name="alias" type="xsd:string" minOccurs="0"/>
        <xsd:element name="datatype" type="xsd:string"/>
        <xsd:element name="doc" type="langType" minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="id" type="xsd:string" use="required"/>
      <xsd:attribute name="required" type="xsd:boolean"/>
    </xsd:complexType>
    <xsd:complexType name="langType">
      <xsd:simpleContent>
        <xsd:extension base="xsd:string">
          <xsd:attribute ref="xml:lang" use="optional"/>
        </xsd:extension>
      </xsd:simpleContent>
    </xsd:complexType>
  </xsd:schema>

The example below is an excerpt of an instance document describing DarwinCore as a conceptual schema:

  <cns xmlns="http://rs.tdwg.org/tapir/cns/1.0">
    <schema namespace="http://rs.tdwg.org/dwc/dwcore/">
    <label>DarwinCore v1.4</label>
    <alias>dwc_1_4</alias>
    <location>http://rs.tdwg.org/dwc/tdwg_dw_core.xsd</location>
    <concepts>
      <concept id="http://rs.tdwg.org/dwc/dwcore/GlobalUniqueIdentifier" required="true">
        <alias>GlobalUniqueIdentifier</alias>
        <datatype>http://www.w3.org/2001/XMLSchema#string</datatype>
        <doc>http://wiki.tdwg.org/twiki/bin/view/DarwinCore/GlobalUniqueIdentifier</doc>
      </concept>
      <concept id="http://rs.tdwg.org/dwc/dwcore/DateLastModified" required="true">
        <alias>DateLastModified</alias>
        <datatype>http://www.w3.org/2001/XMLSchema#dateTime</datatype>
        <doc>http://wiki.tdwg.org/twiki/bin/view/DarwinCore/DateLastModified</doc>
      </concept>
    </schema>
  </cns>

11.3. Term Definitions

11.4. History of Changes

The following changes were made to this document since its first public release.

Date: September, 8th, 2009

• Added paragraph about the target audience of this document.
• Added links to other TAPIR documents (executive summary and TAPIR networks guide).

Date: July, 21st, 2009

• Added recommendation to use default port numbers in access points.
• Added indentation when defining entity and VCARD sub-nodes.
• Specified XML encoding precedence.

Date: February, 5th, 2009

• Revised all text before submitting to the TDWG standards track.
• Removed references to DarwinCore and ABCD.
• Changed documentation about <address> and added <regionCode>, <countryCode> and <zipCode> as part of entity metadata.
• Removed xslt-apply parameter and xslt on server side capability.
• Added "type" attribute (organization or person) to related entities.
• Added new <rootElement> in the output model definition to indicate the name of a global element that should be the root element in search responses.
• Changed response specification forcing HTTP 204 when the envelope is turned off and a search returns no results. Services are now free to perform content negotiation when the envelope is turned off in the search operation.
• Removed parameters "partial" and "omit-ns".
• Included paragraph about the possibility to declare custom operations.
• Included content about new section "archives" in capabilities.
• Updated XML Schema location from http://rs.tdwg.org/tapir/1.0/schema/tapir.xsd to http://rs.tdwg.org/tapir/1.0/schema/tdwg_tapir.xsd.
• Made several adjustments for compatibility with the TDWG Standards Documentation Specification.

Date: September, 18th, 2008

• Changed section about message transport to indicate that TAPIR requires HTTP/1.0 or greater.
• Removed references to Concept Name Servers.
• Added appendix with a simple XML encoding to represent conceptual schemas.
• Minor changes in text to improve clarity.

Date: February, 7th, 2008

• Added recommendation for not omitting the charset in the HTTP header of responses.
• Changed section about response structures to be clearer about its meaning and to define there the "basic schema language".
• Added section with additional interpretation rules for filters.
• Added paragraph in the Capabilities Response/Concepts section to reinforce that providers should understand the short notation when a mapped concept and its schema are declared with an alias.
• Added new "datatype" attribute to <mappedConcept> elements in capabilities responses.
• Added statement in the Inventory Respose section saying that the order of <record> elements should be ascending according to the concept's datatype declared in the capabilities response.
• Added statement that conceptual schemas should minimally indicate the datatypes for each concept.

Date: July, 18th, 2007

• Replaced outputModel by externalOutputModel in search template example.
• Environment variable "lastUpdated" was renamed to "lastUpdate" to be consistent with the XML Schema.
• Included environment variables: dateCreated, metadataLanguage, dataSourceLanguage, dataSourceDescription, rights, subject, bibliographicCitation, technicalContactName, technicalContactEmail, contentContactName, contentContactEmail.
• Included optional attribute "alias" in output models and templates declared in capabilities responses. Aliases can be used in KVP requests replacing the document location.
• Restricted the HTTP Content-Type header in POST/GET requests to be "application/x-www-form-urlencoded".
• Fixed wrong reference to attribute @frequency that was starting with a capital letter.
• Fixed typo in "globalParameters" element name.
• "template" elements in capabilities response examples were not inside a "templates" grouping element.
• "anyOutputModels" element in capabilities response example was lacking a "responseStructure" subelement.
• Fixed many capabilities response examples where the tag slash in supported operations was in the wrong position (e.g. </ping> instead of <ping/>).
• Mentioned the possibility of having multiple dc:language elements in metadata responses.
• Content of dc:language must follow RFC4646 and use the codes specified by the IANA Language Subtag Registry.
• Included custom slot as part of hasContact in metadata responses.

Date: February, 24th, 2007

• Correction: "envelope" parameter on search operations should be turned on by default.
• Included note about the possibility of restricting the allowable domains related to the location of stylesheets that are specified through the "xslt" parameter. When the stylesheet comes from an unknown location it can be ignored with a corresponding warning being raised in the diagnostics section.
• Added specific XML Schema capability for xsd:include.
• Included note about the fact that a provider is not forced to guarantee the entire validity of search responses according to the XML Schema defined in the response structure, except to the extent of its own declared XML Schema capabilities.
• Included recommendation for providers to raise warnings instead of errors when an unsupported XML Schema construct is found in the response structure.
• Included new search parameter called "omit-ns" instructing providers to omit or not namespace delarations and the corresponding prefixes in search responses when the envelope is turned off.
• Included a new attribute "required" for both concepts and variables in the output model mapping (defaults to false). When required, providers should raise an error when the concept is unmapped, or the variable is not available or the corresponding value is null.
• Node paths in output model mapping were not considering namespaces. When the response structure needs to make use of different namespaces, all namespaces need to be declared in the output model element and the nodes referenced in the xpaths must include the associated namespace prefix.
• Removed requirement that providers must automatically turn on envelopes in search responses when an error occurs.

Date: February, 7th, 2007

• Attribute nodes in output model mapping should include a slash before the attribute prefix "@" to be consistent with XPath and with the original integration document. Changed all mapping examples from node@attr to node/@attr.

Date: January, 22nd, 2007

• Updated XML Schema location from http://rs.tdwg.org/tapir/1.0/tapir.xsd to http://rs.tdwg.org/tapir/1.0/schema/tapir.xsd.
• Changed the definition of "model" parameter in the "KVP Requests" section. The previous definition "a pointer to a formatted (usually in XML schema) response structure" was wrong and was changed to "a pointer to an output model document".
• Changed the definition of "basicSchemaLanguage" by removing "simpleContent" and "complexContent" from the list of XML Schema constructs that need to be supported. Also replaced attribute "minOccurs" by attribute "use".
• Included explanation and example about the new optional attribute "tagName" for inventory concepts. Included the corresponding KVP parameter "tagname" or "n".
• Included optional "alias" attribute for mapped schemas in capabilities responses.
• Changed default value of "start" parameter to "0" (index of the first record).
• Included additional specification for the "like" operator saying that "not specifying any wildcard in the corresponding literal is equivalent to specifying two wildcards: one in the beginning and the other in the end of the literal value".
• Included additional specification for the "like" operator saying that when the character "*" is not meant to be a wildcard, it should be escaped by including "_" before the "*" character.
• Changed XML representation of variables to <variable name="var_name"/> and removed <custom> section in capabilities responses that could be used to advertise custom variables (not needed anymore because now xsd:any is used there).
• Changed explanation about source@accesspoint. In requests it must contain the IP address of each source, except the last one. In responses it must contain the service URL. Removed all accesspoint attributes from requests examples.
• Included KVP parameter "source-ip".
• Included new KVP parameter "descend" or "d" for search operations.
• Included additional explanation that maxElementRepetitions apply only to inventory and search responses.
• Included additional explanation that maxElementLevels apply only to search responses and do not consider the TAPIR envelope.
• Included new section about "response structures".