class OctetStream

A series of 8-bit bytes which combined together form a digital object. OctetStream is used to transfer object bytes such as the response to MNRead.get().

class Integer

A simple integer. The range of expected values should be described with the accompanying API call.

The Integer type is serialized over XML using the predefined XMLSchema integer type, the value space of which is the infinite series {...,-2,-1,0,1,2,...}.

class Boolean

A boolean response is commonly used in the DataONE service APIs to indicate success or otherwise of an operation. For operations that are called through the service interfaces, a positive boolean response (i.e. True) is indicated by returning a HTTP response with a status code of “200”. The body of the message may contain additional content, but this should be ignored by the receiver.

A False or failure response must return an appropriate Error message and must set the appropriate HTTP status code on the response to indicate a failure.

The Boolean type is serialized over XML using the predefined XMLSchema boolean type, an instance of which can have the following legal literals {true, false, 1, 0}.

class DateTime

A string that completely identifies a specific date and time. When DateTime values are used within fields in request and response messages, and as URL-encoded values for parameters, all DateTime values will be typed using the XML Schema Datatypes definition (see XMLSchema dateTime) for the datetime serialization syntax (xs:dateTime). This syntax represents a subset of the ISO 8601 standard notation, and so standard ISO 8601 parsing libraries can be used to parse the values (see libraries used below). In addition, within DataONE, these values MUST be expressed with a timezone designation in UTC/GMT time only; local times are not permitted.

• Must include date and time
• The time zone must be 0, i.e. GMT

Valid representations include:

• YYYY-MM-DDTHH:MM:SS.mmm
• YYYY-MM-DDTHH:MM:SS.mmm+00:00

The milliseconds may be left off if that precision is not available.

In addition, in any methods that use date time values in HTTP headers, the serialization will follow the HTTP Full Date standard (RFC 1123), e.g:

Sun, 06 Nov 1994 08:49:37 GMT

In Java, code against java.util.Date, though serialization and deserialization will be performed with org.joda.DateTime to ensure millisecond precision is correct.

In Python, we use datetime.datetime to represent datetimes internally and a library called iso8601 to serialize and deserialize to Types.DateTime and Pyxb for the XML representation.

See also the XMLSchema dateTime type which is used for serializing DateTime values in XML transmitted between DataONE components.

class DescribeResponse

The MNRead.describe() method provides a low cost hint about the type, size and state of an object.

The DescribeResponse is returned from the server in a HTTP HEAD response, and hence the values must be represented in the HTTP response headers. There is no XML serialization of a DescribeResponse.

DataONE-formatId

The value of the SystemMetadata.formatId entry available in the SystemMetadata.

Content-Length

Size of the object in bytes, the value of SystemMetadata.size from SystemMetadata.

Last-Modified

A DateTime value that indicates when the system metadata associated with the object was last modified, i.e. the value of SystemMetadata.dateSysMetadataModified for the object.

DataONE-Checksum

The checksumAlgorithm and checksum value of the object being examined. The algorithm and checksum values are separated by a single comma with the algorithm first.

DataONE-SerialVersion

The serialVersion value of the system metadata for the object as reported by the Node responding to the describe request.

Example of a HEAD response on object “ABC123”:

curl -I http://mn1.dataone.org/mn/v1/object/ABC123

HTTP/1.1 200 OK
Last-Modified: Wed, 16 Dec 2009 13:58:34 GMT
Content-Length: 10400
Content-Type: application/octet-stream
DataONE-formatId: eml://ecoinformatics.org/eml-2.0.1
DataONE-Checksum: SHA-1,2e01e17467891f7c933dbaa00e1459d23db3fe4f
DataONE-SerialVersion: 1234