DiGIR Messages

DRAFT: 2001-09-10

Note: Throughout this document, text inserted in boxes like this refers to comments that are unlikely to form part of the final document and are inserted for informational purposes only.

This document contains a first draft of the messages between "Portal" and "Provider" as described in the meeting at the Presidio over the period 2001-09-08 : 2001-09-09.

The term "Origin" is used here in place of "Portal" to more specifically identify that entity from which the request originates. The term "Provider" is used as it was during the meeting, meaning a service that receives requests from an Origin, processes the content of the request, and returns an appropriate response.

DTD sections are used to describe message constructs. Will probably replace with schema at a later time.

Introduction

Preface

This document describes the message constructs to be used for communication between a Provider and its clients for the DiGIR protocol. In the context of this document, a "Provider" is a service that accepts messages described in this document, generates responses outlined in this document and exhibits behaviour described in this and related documents. A client is the originator of the message sent to the Provider.

The interaction between a client and provider is stateless, meaning that a client can not presume any state information is persisted between messages.

The primary purpose of the provider is to identify subsets of information identified by a client provided filter and return some portion of that content in a format requested by the client.

Document Conventions

In the sections labeled as normative, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [15].

Revision History

Date Version Description

2001-09-09 0.0.0 Document started

Date	Version	Description
2001-09-09	0.0.0	Document started

Search Structure

Search Response Structure

Status Structure

Status Response Structure

Request Structure

A Request Structure contains a single Operation which indicates the action requested of the provider and the parameters required to perform the operation. In response to a Request Structure a provider MUST return a valid Response structure except where prevented by a catastrophic failure.

For this version only a single operation may be sent with each request. This may be extended in future version to allow multiple operations to be defined within a single request.

Version added to the request and response elements to provide support for backward compatibility as software evolves. Should it be a requirement that providers that support newer (higher) versions MUST support operations from older versions?

Request Structure Definition

<!ENTITY request (header, operation)>
<!ATTLIST response version #REQUIRED>
   <!ENTITY header (sendTime,sourceID, destinationID)>
       <!ENTITY sendTime #PCDATA>
       <!ENTITY sourceID #PCDATA>
       <!ENTITY destinationID #PCDATA>
       <!ENTITY operation ANY>

Request Structure Element Descriptions

Element Description

request The top most element of any Request message

header Contains information generic to all types of Request and Response messages.

version The version of the service that the message is being directed to. The first valid version identifier will be "1.0.0".

sendTime The time (GMT) formatted according to ISO-8601 that the request message was generated. The actual value of sendTime should indicate as close as practicable when the message is sent.

sourceID An identifier for the source of the message. Where the message is machine generated, this should be the IP address of the machine that generated the message.

destinationID The IP address of the target of the message.

operation The operation element identifies the operation that the provider is being requested to perform and the parameters required to perform that operation.

The type attribute of the operation element indicates the requested operation. There are currently two types of operations defined: "search" and "status".

Element	Description
request	The top most element of any Request message
header	Contains information generic to all types of Request and Response messages.
version	The version of the service that the message is being directed to. The first valid version identifier will be "1.0.0".
sendTime	The time (GMT) formatted according to ISO-8601 that the request message was generated. The actual value of sendTime should indicate as close as practicable when the message is sent.
sourceID	An identifier for the source of the message. Where the message is machine generated, this should be the IP address of the machine that generated the message.
destinationID	The IP address of the target of the message.
operation	The operation element identifies the operation that the provider is being requested to perform and the parameters required to perform that operation. The type attribute of the operation element indicates the requested operation. There are currently two types of operations defined: "search" and "status".

Request Structure Example

<request>
    <header>
        <sendTime>1988-04-07T18:39:09Z</sendTime>
        <sourceID>129.237.201.230</sourceID>
        <destinationID>129.237.201.228</destinationID>
    </header>
    <operation type="operationName">
    ... operation definition ...
    </operation>
</request>

Response Structure

A Response Structure is always returned by a Provider in response to a Request Structure.

Response Structure Definition

<!ENTITY response (header, content, diagnostics)>
<!ATTLIST response version #REQUIRED>
<!ENTITY header (sendTime, sourceID, destinationID)>
    <!ENTITY sendTime #PCDATA>
    <!ENTITY sourceID #PCDATA>
    <!ENTITY destinationID #PCDATA>
<!ENTITY content ANY>
    <!ATTLIST content type #REQUIRED>
<!ENTITY diagnostics (diagnostic*)>
    <!ENTITY diagnostic #PCDATA>
    <!ATTLIST diagnostic code #REQUIRED>
    <!ATTLIST diagnosic severity #REQUIRED>

Response Structure Element Descriptions

Element Description

response The top most element of any Request message

header Contains information generic to all types of Request and Response messages.

version The version of the service that the message is being directed to. The first valid version identifier will be "1.0.0".

sendTime The time (GMT) formatted according to ISO-8601 that the request message was generated. The actual value of sendTime should indicate as close as practicable when the message is sent.

sourceID An identifier for the source of the message. Where the message is machine generated, this should be the IP address of the machine that generated the message.

destinationID The IP address of the target of the message.

content The content element identifies the output from the requested operation.

The type attribute of the content element should be identical to the "type" attribute of the "operation" element in the request. There are currently two types of content defined: "search" and "status".

diagnostics The diagnostics element contains zero or more diagnostic elements which provide information about the processing of the operation.

diagnostic A diagnostic element has two attributes indicating the id of the diagnostic and the level of severity attached to the diagnostic. The content on the diagnostic element contains text intended for human reading that provides more information about the condition which caused the diagnostic.

code Each type of diagnostic is given a unique identifier (integer value)

severity Each diagnostic is assigned a level of severity.

Element	Description
response	The top most element of any Request message
header	Contains information generic to all types of Request and Response messages.
version	The version of the service that the message is being directed to. The first valid version identifier will be "1.0.0".
sendTime	The time (GMT) formatted according to ISO-8601 that the request message was generated. The actual value of sendTime should indicate as close as practicable when the message is sent.
sourceID	An identifier for the source of the message. Where the message is machine generated, this should be the IP address of the machine that generated the message.
destinationID	The IP address of the target of the message.
content	The content element identifies the output from the requested operation. The type attribute of the content element should be identical to the "type" attribute of the "operation" element in the request. There are currently two types of content defined: "search" and "status".
diagnostics	The diagnostics element contains zero or more diagnostic elements which provide information about the processing of the operation.
diagnostic	A diagnostic element has two attributes indicating the id of the diagnostic and the level of severity attached to the diagnostic. The content on the diagnostic element contains text intended for human reading that provides more information about the condition which caused the diagnostic.
code	Each type of diagnostic is given a unique identifier (integer value)
severity	Each diagnostic is assigned a level of severity.

Response Structure Example

<response version="1.0.0">
    <header>
        <sendTime>1988-04-07T18:39:09Z</sendTime>
        <sourceID>129.237.201.230</sourceID>
        <destinationID>129.237.201.228</destinationID>
    </header>
    <content type="contentType">
    ... contents of response ...
    </content>
    <diagnostics>
        <diagnostic code="1" severity="1">A diagnostic message</diagnostic>
    </diagnostics>
</response>

Operations

Search Structure

The search operation is used to identify a subset of information in a single database exposed by the provider, indicate how the matching subset should formatted, and return the requested content.

Search Structure Definition

<!ENTITY operation (dbName,filter, recordStruct)>
    <!ATTLIST operation type (search | scan) #REQUIRED>
    <!ENTITY dbName #PCDATA>
    <!ENTITY filter (LOP | COP)>
        <!ENTITY LOP (COP, COP)>
        <!ATTLIST LOP type (and | or | andNot | orNot) #REQUIRED>
            <!ENTITY COP (term, concept)>
            <!ATTLIST COP type #REQUIRED>
            <!ENTITY term #PCDATA>
            <!ATTLIST term type #IMPLIED>
            <!ENTITY concept>
    <!ENTITY records #PCDATA>
    <!ATTLIST records start #IMPLIED>
    <!ATTLIST records count #IMPLIED>

Search Structure Element Descriptions

Element Description

dbName The name of the database exposed by the provider against which the filter will be applied and (optionally) records retrieved.

filter Contains the filter that is used to identify a subset of records

LOP Logical operator. A LOP can contain exactly two COP entities, each of which evaluate to boolean TRUE or FALSE

LOP type Indicates the type of logical operator. Possible values are "and", "or", "and not" and "or not"

COP Comparison operator. A COP indicates how a query term should be compared with a concept exposed by the database.

COP type Indicates the type of comparison being performed. Possible values include

term The term is the value being matched to a concept

term type The term type indicates how the contents of the term should be interpreted. e.g. "string" or "integer" or "bounding box" or "sound" etc.

concept Identifies the concept that the term should be comapred with. For simplifying international support, concepts should be identified by an integer value.

format The format element indicates how records in the response should be formatted. The following values are reserved:
count, min, max, countGroup
The format should either contain a reference to, or a complete XML schema appropriate for the database content that indicates how the records should be constructed for the response.

start The start attribute of the records element indicates the starting in the result set to be returned. Records in a result set are indexed from 1 to n, where n is the number of records that match the filter. The first record of the result set is identified as record number 1.

Where start is not indicated the response should start at record number 1.

Where the value of start evaluates to zero or less than zero, the response should start at record number 1 and a diagnostic should be returned indicating an invalid start value.

Where start evaluates to a value greater than the number of records in the result set, no records should be returned and a diagnostic indicating an invalid start values should be returned.

count The count attribute of the records element indicates how many records should be returned.

Where count is not specified, all records from start to the end of the result set should be returned.

Where count evaluates to zero, no records should be returned.

Where count evaluates to a number less than zero, all records should be returned and a diagnostic indicating an invalid count value should be returned.

Where count indicates more records than are available, all records should be returned and a diagnostic indicating an attempt to retrieve more records than are available should be returned.

Element	Description
dbName	The name of the database exposed by the provider against which the filter will be applied and (optionally) records retrieved.
filter	Contains the filter that is used to identify a subset of records
LOP	Logical operator. A LOP can contain exactly two COP entities, each of which evaluate to boolean TRUE or FALSE
LOP type	Indicates the type of logical operator. Possible values are "and", "or", "and not" and "or not"
COP	Comparison operator. A COP indicates how a query term should be compared with a concept exposed by the database.
COP type	Indicates the type of comparison being performed. Possible values include
term	The term is the value being matched to a concept
term type	The term type indicates how the contents of the term should be interpreted. e.g. "string" or "integer" or "bounding box" or "sound" etc.
concept	Identifies the concept that the term should be comapred with. For simplifying international support, concepts should be identified by an integer value.
format	The format element indicates how records in the response should be formatted. The following values are reserved: count, min, max, countGroup The format should either contain a reference to, or a complete XML schema appropriate for the database content that indicates how the records should be constructed for the response.
start	The start attribute of the records element indicates the starting in the result set to be returned. Records in a result set are indexed from 1 to n, where n is the number of records that match the filter. The first record of the result set is identified as record number 1. Where start is not indicated the response should start at record number 1. Where the value of start evaluates to zero or less than zero, the response should start at record number 1 and a diagnostic should be returned indicating an invalid start value. Where start evaluates to a value greater than the number of records in the result set, no records should be returned and a diagnostic indicating an invalid start values should be returned.
count	The count attribute of the records element indicates how many records should be returned. Where count is not specified, all records from start to the end of the result set should be returned. Where count evaluates to zero, no records should be returned. Where count evaluates to a number less than zero, all records should be returned and a diagnostic indicating an invalid count value should be returned. Where count indicates more records than are available, all records should be returned and a diagnostic indicating an attempt to retrieve more records than are available should be returned.

Search Structure Examples

Search the database called "birdCollection" (dbName) for records in which the concept of year (concept = 14) exactly equals (comparison type 3) the numeric value (term type 2) "1970" and return all the records that match in full format.

<operation type="search">
    <dbName>birdCollection</dbName>
    <filter>
        <comparison type="3">
            <concept>14</concept>
            <term type="2">1970</term>
        </comparison>
    </filter>
    <records>
        <format>
        http://speciesanalyst.net/DarwinCore/1.0/recordStruct/full.xsd
        </format>
    </records>
</operation>

Search the database called "birdCollection" for records in which the concept of genus contains the string "Otus" AND the concept of country matches the string "Canada", returning only the number of records found.

<operation type="search">
    <dbName>birdCollection</dbName>
    <filter>
        <LOP type="AND">
            <comparison type="8">
                <concept>7</concept>
                <term type="1">Otus</term>
            </comparison>
            <comparison type="3">
                <concept>17</concept>
                <term type="1">Canada</term>
            </comparison>
        </LOP>
    </filter>
    <records>
        <format>count</format>
    <records>
</operation>

Apply the same filter as above, but return 10 records starting at record number 5 from the set of matching records using the brief format.

<operation type="search">
    <dbName>birdCollection</dbName>
        <filter>
            <LOP type="AND">
                <comparison type="8">
                    <concept>7</concept>
                    <term type="1">Otus</term>
                </comparison>
                <comparison type="3">
                    <concept>17</concept>
                    <term type="1">Canada</term>
                </comparison>
            </LOP>
        </filter>
        <records start="5" count="10">
            <format>
            http://speciesanalyst.net/darwincore/1/0/recordStruct/brief.xsd
            </format>
        </records>
</operation>

Search Response Structure

A Search Response Structure is generated in response to a Search Structure in a Request message received by a Provider.

Search Response Structure Definition

<!ELEMENT content (structure, record*, moreRecords)>
<!ATTLIST content type (search | status) #REQUIRED>
<!ELEMENT structure ANY>
<!ELEMENT record ANY>
<!ELEMENT moreRecords #PCDATA>

Search Response Structure Element Descriptions

Element Description

content The content element provides a wrapper for the various types of response content. For the purposes of a Search Response Structure, content contains a structure definition, zero or more record elements, and an element indicating if there are more records in the result set.

content type Identical to the type attribute of the operation element of the request. In this case it would be "search".

structure The structure of the contents of each record element expressed as XML-Schema

record Each record element contains the subset of information identified by the search request filter, and formatted according to the search request format specification.

moreRecords indicates if there are more records beyond the last record element in this message.

Element	Description
content	The content element provides a wrapper for the various types of response content. For the purposes of a Search Response Structure, content contains a structure definition, zero or more record elements, and an element indicating if there are more records in the result set.
content type	Identical to the type attribute of the operation element of the request. In this case it would be "search".
structure	The structure of the contents of each record element expressed as XML-Schema
record	Each record element contains the subset of information identified by the search request filter, and formatted according to the search request format specification.
moreRecords	indicates if there are more records beyond the last record element in this message.

Search Response Structure Examples

The moreRecords element seems totally out of place here. There *must* be a better way of expressing this.

A search response to a search request with the format "count" specified where 865 records were found to match the filter criteria.

<content type="search">
    <format>
    count
    </format>
    <record>865</record>
    <moreRecords>false</moreRecords>
</content>

A search response that contains three records. The response also indicates that there are more records available in the result set. The contents of the records are not specified here.

<content type="search">
    <format>
    http://speciesanalyst.net/darwincore/1.0/recordStruct/full.xsd
    </format>
    <record>...</record>
    <record>...</record>
    <record>...</record>
    <moreRecords>true</moreRecords>
</content>

Status Structure

Note: Status is inserted here as a place holder.

TO DO

Status Response Structure

TO DO

DiGIR Messages

Introduction

Preface

Document Conventions

Revision History

Contents

Request Structure

Request Structure Definition

Request Structure Element Descriptions

Request Structure Example

Response Structure

Response Structure Definition

Response Structure Element Descriptions

Response Structure Example

Operations

Search Structure

Search Structure Definition

Search Structure Element Descriptions

Search Structure Examples

Search Response Structure

Search Response Structure Definition

Search Response Structure Element Descriptions

Search Response Structure Examples

Status Structure

Status Response Structure