Odata ATOM Format Version 1.0

OData ATOM Format Version 1.0

Working Draft 01

1527JanuaryNovember 20132

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Barbara Hartel (), SAP AG

Ram Jeyaraman (), Microsoft

Editor:

Martin Zurmuehl (), SAP AG

Colleen Evans (), Microsoft

Additional artifacts:

This prose specification is one component of a Work Product which also includes:

XML schemas:(list file names or directory name)
Other parts (list titles and/or file names)

Related work:

This specification replaces or supersedes:

Specifications replaced by this specification (hyperlink, if available)

This specification is related to:

Related specifications (hyperlink, if available)

Declared XML namespaces:

list namespaces declared within this specification

Abstract:

The OData protocol is comprised of a set of specifications for representing and interacting with structured content. This document describes the OData Atom Format returned from an OData Service when requesting the application/atom+xml mime type.

Status:

This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1Introduction

1.1 Terminology

1.2 Normative References

1.3 Non-Normative References

2The xml:base Attribute

3Primitive Types in Atom

4Use of Atom

4.1 Namespaces

4.1.1 Atom Namespace

4.1.2 Atom Publishing Protocol Namespace

4.1.3 OData Data Namespace

4.1.4 OData Metadata Namespace

5Atom Element Definition

5.1 Entity Instances

5.1.1 The atom:entry Element

5.1.1.1 The metadata:etag Attribute

5.1.2 The atom:id Element

5.1.3 Self and Edit Links as atom:link Elements

5.1.4 Stream Properties as atom:link Elements

5.1.4.1 The rel Attribute of a Link Representing a Stream Property

5.1.4.2 The href Attribute of a Link Representing a Stream Property

5.1.4.3 The title Attribute of a Link Representing a Stream Property

5.1.5 Relationships as atom:link Elements

5.1.5.1 The rel Attribute of an atom:link Element Representing a Relationship

5.1.5.2 The href Attribute of an atom:link Element Representing a Relationship

5.1.5.3 The type Attribute of an atom:link Element Representing a Relationship

5.1.5.4 The title Attribute of an atom:link Element Representing a Relationship

5.1.6 Inline Content within a metadata:inline Element

5.1.7 Relationship Links as atom:link Elements

5.1.7.1 The rel Attribute of an atom:link Element Representing Relationship Links

5.1.7.2 The href Attribute of an atom:link Element Representing Relationship Links

5.1.7.3 The type Attribute of an atom:link Element Representing Relationship Links

5.1.7.4 The title Attribute of an atom:link Element Representing Relationship Links

5.1.8 Entity Type as an atom:category Element

5.1.9 Entity Content within an atom:content Element

5.1.9.1 Media Entities as Media Link Entries using the srcAttribute

5.1.10 atom:link element for Updating Media Link Entries

5.1.10.1 The rel attribute for writing to Media Link Entries

5.1.10.2 The href attribute for writing to Media Link Entries

5.1.11 Entity Properties within a metadata:properties Element

5.1.11.1 Entity Property as a data:[propertyName] Element

5.1.12 Nulls represented using the metadata:null Attribute

5.1.13 Data Type represented using the metadata:type Attribute

5.2 Collections of Entities

5.2.1 Collection of Entities as an atom:feed Element

5.2.2 The atom:id Element within an atom:feed

5.2.3 Count as a metadata:count Element

5.2.4 Self-Links as atom:link Elements

5.2.5 Additional Results as an atom:link element

6Actions

6.1 Actions as a metadata:action Element

6.1.1 The metadata Attribute for an Action

6.1.2 The target Attribute for an Action

6.1.3 The title Attribute for an Action

7Functions

7.1 Functions as a metadata:function Element

7.1.1 The metadata Attribute for a Function

7.1.2 The target Attribute for a Function

7.1.3 The title Attribute for a Function

8Annotations

8.1 The metadata:Annotation Element

8.1.1 The Term Attribute

8.1.2 The Type Attribute

8.1.3 The Target Attribute

8.2 Annotation Value

8.2.1 Attribute Value Notation

8.2.2 Primitive Values

8.2.3 Collection Values

8.2.4 Structure Annotations

8.3 Instance Annotation Targets

8.3.1 Annotating a Feed

8.3.2 Annotating an Entry

8.3.3 Annotating a Property

8.3.4 Annotating a Navigation Property

8.3.5 Annotating a Function or Action

8.3.6 Annotating an Error

9Custom Mapping to Atom Elements

10Individual Primitive or Complex Scalar Values

11Collections of Primitive or Complex Scalar Values

12Entity Container as a Workspace within a Service Document

12.1 The app:service element

12.1.1 Entity Container as an app:workspace element

12.1.2 Entity Sets as an app:collection element

12.1.3 Entity Set Name as an atom:title element

13Links

13.1 Collection of Links as a data:links Element

13.2 Link as a data:uri Element

14Errors as XML

14.1 The metadata:error Element

14.2 The metadata:code Element

14.3 The metadata:message Element

14.3.1 The xml:lang Attribute

14.4 The metadata:innererror Element

15Extensibility

16Conformance

Appendix A.Acknowledgments

Appendix B.Non-Normative Text

B.1 Subsidiary section

B.1.1 Sub-subsidiary section

Appendix C.Revision History

odata-atom-format-v1.0-wd01Working Draft 011527JanuaryNovember20132

1Introduction

An OData payload may represent:

a single primitive value
a sequence of primitive values
a single structured (“complex”) value
a sequence of structured (“complex”) values
an entity (a structured type with an identity)
a sequence of entities
a media resource
a single instance of a mime type
a single link to a related entity
a collection of links to related entities
a service document describing the collections (entity sets) exposed by the service
an xml document describing the entity model exposed by the service
an error
a batch of requests to be executed in a single request
a set of responses returned from a batch request

For a description of the xml format for describing an entity model, see[OData-CSDL]. For a description of batch requests and responses, see [OData-Core].

1.1Terminology

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 [RFC2119].

1.2Normative References

This document references the following related documents:

[OData-ABNF]OData ABNF Construction Rules Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01.

[OData-Core]OData Protocol Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01.

[OData-CSDL]OData Common Schema Definition Language (CSDL) Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01.

[OData-JSON]OData Extension for JSON Data Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01.

[OData-URL]OData URL Conventions Version 1.0DD Month 2012. OASIS Committee Specification Draft 01.

[RFC2119]S. Bradner, “Key words for use in RFCs to Indicate Requirement Levels”,IETF RFC 2119, March 1997.

[RFC2616]R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, IETF RFC2616, June 1999.

[RFC3987]M. Duerst,M. Suignard,“Internationalized Resource Identifiers (IRIs)”, IETFRFC3987, Januar 2005.

[RFC4287]M. Nottingham, Ed., R. Sayre, Ed. “The Atom Syndication Format”,IETFRFC4287, December 2005.

[RFC5023]J. Gregorio, Ed., B. de hOra, Ed., “The Atom Publishing Protocol”,IETF RFC5023, October 2007.

[XML-Schema-2]Peterson, D. et al., “W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes”, W3C Recommendation, 5 April 2012.

1.3Non-Normative References

None

2The xml:base Attribute

OData payloads may use the xml:base attribute to define a base URI for relative references defined within the scope of the element containing the xml:base attribute.

3Primitive Types in Atom

OData Atom and XML payloads serialize primitive types as shown in the table below.

For full syntax rules, see [OData-ABNF].

Primitive Type / Literal Form / Example
Null
Represents the absence of a value / "null" / null
Edm.Binary
Represent fixed- or variable- length binary data / ((A-F | a-f | 0-9)(A-F | a-f | 0-9))* / 23ABFF
Edm.Boolean
Represents the mathematical concept of binary-valued logic / "true" | "1"
"false" | "0" / true
false
Edm.Byte
Unsigned 8-bit integer value / (A-F | a-f | 0-9)(A-F | a-f | 0-9) / FF
Edm.DateTime[RH1]
Represents a date and time with values ranging from 12:00:00 midnight, January 1, 1753 A.D. through 11:59:59 P.M, December 31, 9999 A.D. / yyyy "-" mm "-" dd "T" hh ":" mm
[":" ss["." fffffff]] / 2000-12-12T12:00
Edm.Decimal
Represents numeric values with fixed precision and scale. This type can describe a numeric value ranging from negative 10^255 + 1 to positive 10^255 -1 / ["-"][0-9]+[.][0-9]* / 2.345
Edm.Double
Represents a floating point number with 15 digits precision that can represent values with approximate range of ± 2.23e -308 through ± 1.79e +308 / ["-"][0-9]+ ((.[0-9]+) | [E[+ | -][0-9]+]) / 2.345
Edm.Single
Represents a floating point number with 7 digits precision that can represent values with approximate range of ± 1.18e -38 through ± 3.40e +38 / ["-"][0-9]+.[0-9] / 2.5
Edm.Float[RH2]
Represents a floating point number with 7 digits precision that can represent values with approximate range of ± 1.18e -38 through ± 3.40e +38 / ["-"][0-9]+.[0-9] / 2.5
Edm.Guid
Represents a 16-byte (128-bit) unique identifier value / dddddddd "-" dddd "-" dddd "-" dddd "-" dddddddddddd
d= A-F |a-f | 0-9 / 12345678-aaaa-bbbb-cccc-ddddeeeeffff
Edm.Int16
Represents a signed 16-bit integer value / [-][0-9]+ / 16
Edm.Int32
Represents a signed 32-bit integer value / [-] [0-9]+ / 32
Edm.Int64
Represents a signed 64-bit integer value / [-] [0-9]+ / 64
Edm.SByte
Represents a signed 8-bit integer value / [-] [0-9]+ / 8
Edm.String
Represents fixed- or variable-length character data / any UTF-8 character
Note: See definition of UTF8-char in [RFC3629] / OData
Edm.Time
Represents the time of day with values ranging from 0:00:00.x to 23:59:59.y, where x and y depend upon the precision / Defined by the lexical representation for xs:durationin [XML-Schema-2] / PT23H59M59.9999999S
Edm.DateTimeOffset
Represents date and time as an Offset in minutes from GMT, with values ranging from 12:00:00 midnight, January 1, 1753 A.D. through 11:59:59 P.M, December 9999 A.D / Defined by the lexical representation for xs:datetime (including timezone offset) in [XML-Schema-2] / 2002-10-10T17:00:00Z
Edm.DayTimeDuration[RH3]
Represents a duration in days, hours, minutes, seconds and fractions of seconds / Defined by the lexical representation for xs:dayTimeDuration in [XML-Schema-2] / P12DT23H59M59.99999S
Edm.Geography
Abstract base type for all Geography types. / N/A / N/A
Edm.GeographyPoint
Represents a point in a round-earth coordinate system. / srid "Point(" point ")"
srid= "SRID=" 1*5DIGIT ";"
point= LONG LAT
Where LONG and LAT are EDM.Doubles representing Longitude and Latitude. / SRID=123435;
Point(33.84 -117.91)
Edm.GeographyLineString
Represents a linestring in a round-earth coordinate system. / srid "LineString(" linestring ")"
linestring= point ["," point]+ / SRID=123435;
Linestring(33.84 -117.91,
48.87 2.78)
Edm.GeographyPolygon
Represents a polygon in a round-earth coordinate system. / srid "Polygon(" polygon ")"
polygon= ring "," [ring ","]*
ring= "(" firstpoint "," [point ","]* firstpoint ")" ]* ")"
firstpoint = point / SRID=123435;
Polygon((33.84 -117.91,
48.87 2.78,
33.84 -117.91))
Edm.GeographyCollection
Represents a collection of Geography Values. / srid "GeographyCollection(" geographycollection ")"
geographycollection= geographyvalue ["," geographyvalue]*
geographyvalue="Point("point")" |
"LineString(" linestring ")" |
"Polygon(" polygon ")" |
"GeographyCollection(" geographycollection ")" |
"MultiPoint("multipoint ")" |
"MultiLineString("multilinestring ")" |
"MultiPolygon("multipolygon ")" / SRID=123435;
GeographyCollection(
Point(33.84 -117.91),
Point(48.87 2.78))
Edm.GeographyMultiPoint
Represents a collection of points in a round-earth coordinate system / srid "MultiPoint(" multipoint ")"
multipoint= point ["," point]* / SRID=123435;
MultiPoint(
33.84 -117.91,
(48.87 2.78))
Edm.GeographyMultiLineString
Represents a collection of linestrings in a round-earth coordinate system. / srid "MultiLineString(" multilinestring ")"
multilinestring= "(" linestring ")" [",(" linestring ")" ]* / SRID=123435;
MultiLineString(
(33.84 -117.91,48.87 2.78),
(33.84 -117.91, 28.36 -81.56))
Edm.GeographyMultiPolygon
Represents a collection of polygons in a round-earth coordinate system. / srid "MultiPolygon(" multipolygon ")"
multipolygon= "(" polygon ")" [",(" polygon ")"]* / SRID=123435;
MultiPolygon(
(
(33.84 -117.91,(33.84 -117.91,28.36 -81.56,33.84 -117.91)))
Edm.Geometry
Abstract base type for all Geometry types / N/A / N/A
Edm.GeometryPoint
Represents a point in a flat-earth coordinate system. / srid "Point(" point ")" / SRID=123435;
Point(33.84 -117.91)
Edm.GeometryLineString
Represents a linestring in a flat-earth coordinate system. / srid "LineString(" linestring ")" / SRID=123435;
Linestring(33.84 -117.91,
48.87 2.78)
Edm.GeometryPolygon
Represents a polygon in a flat-earth coordinate system. / srid "Polygon(" polygon ")" / SRID=123435;
Polygon((33.84 -117.91,
48.87 2.78,33.84 -117.91))
Edm.GeometryCollection
Represents a collection of Geometry Values. / srid "GeometryCollection(" geometrycollection ")"
geometrycollection= geometryvalue ["," geometryvalue]*
geometryvalue= "Point("point")" |
"LineString(" linestring ")" |
"Polygon(" polygon ")" |
"GeometryCollection(" geometrycollection ")" |
"MultiPoint("multipoint ")" |
"MultiLineString("multilinestring ")" |
"MultiPolygon("multipolygon ")" / SRID=123435;
GeometryCollection(
Point(33.84 -117.91),
Point(48.87 2.78))
Edm.GeometryMultiPoint
Represents a collection of points in a flat-earth coordinate system. / srid "MultiPoint(" multipoint ")" / SRID=123435;
MultiPoint((33.84 -117.91),
(48.87 2.78))
Edm.GeographyMultiLineString
Represents a collection of linestrings in a flat-earth coordinate system. / srid "MultiLineString(" multilinestring ")" / SRID=123435;
MultiLineString(
(33.84 -117.91,48.87 2.78),
(33.84 -117.91,28.36 -81.56))
Edm.GeographyMultiPolygon
Represents a collection of polygons in a flat-earth coordinate system. / srid "MultiPolygon(" multipolygon ")" / SRID=123435;
MultiPolygon(
(
(33.84 -117.91,(33.84 -117.91,28.36 -81.56,33.84 -117.91)))

4Use of Atom

The Atom Syndication Format [RFC4287] defines an XML-based format for describing collections (“feeds”) made up of individual “entries”. The Atom Publishing Protocol [RFC5023] defines an application-level protocol based on HTTP transfer of Atom-formatted representations.

OData builds on [RFC4287] and [RFC5023] by defining additional conventions and extensions for representing and querying entity data.

4.1Namespaces

OData defines meaning for elements and attributes defined in the following namespaces.

4.1.1Atom Namespace

Atom elements and attributes are defined within the Atom namespace:

In this specification the namespace prefix atom is used to represent the Atom Namespace, however the prefix name is not prescriptive.

4.1.2Atom Publishing Protocol Namespace

Atom Publishing Protocol (AtomPub) elements and attributes are defined within the AtomPub namespace:

In this specification the namespace prefix app is used to represent the AtomPub Namespace, however the prefix name is not prescriptive.

4.1.3OData Data Namespace

Elements that describe the actual data values for an entity are qualified with the OData Data Namespace:

In this specification the namespace prefix data is used to represent the OData Data Namespace, however the prefix name is not prescriptive.

4.1.4OData Metadata Namespace

Attributes and elements that represent metadata (such as type, null usage, and entry-level etags) are defined within the OData Metadata Namespace: elements or attributes MUST NOT use this namespace.

In this specification the namespace prefix metadata is used to represent the OData Metadata Namespace, however the prefix name is not prescriptive.

5Atom Element Definition

OData’s Atom format defines extensions and conventions on top of [RFC4287]and [RFC5023]for representing structured data as follows:

5.1Entity Instances

Entity Instances, whether individual or within an ATOM feed, are represented as atom:entry elements.

For example, the following atom:entry element describes a Product:

<entry>

<id>

</author>

title="Category" href="Products(0)/Category" />

<linkrel="
type="application/atom+xml;type=entry"

title="Supplier" href="Products(0)/Supplier" />

<metadata:properties>

<data:ID m:type="Edm.Int32">0</data:ID>

<data:Name>Bread</data:Name>

<data:Description>Whole grain bread</data:Description>

<data:ReleaseDate metadata:type="Edm.DateTime">

1992-01-01T00:00:00

</data:ReleaseDate>

<data:DiscontinuedDate metadata:type="Edm.DateTime" metadata:null="true" />

<data:Rating metadata:type="Edm.Int32">4</data:Rating>

<data:Price metadata:type="Edm.Decimal">2.5</data:Price>

</metadata:properties>

</content>

</entry>

This section defines the elements and attributes within an atom:entry element that are assigned meaning in OData.

5.1.1The atom:entryElement

An atom:entry element is used to represent a single entity, which is an instance of a structured type with an identity.

5.1.1.1The metadata:etag Attribute

The atom:entry element MAY contain a metadata:etag attribute, representing an opaque string value that can be used in a subsequent request to determine if the value of the entity has changed. For details on how ETags are used, see to [OData-Core].

5.1.2The atom:id Element

The atom:id element defines a durable, opaque, globally unique identifier for the entry. Its content must be an IRI as defined in [RFC3987]. The consumer of the feed must not assume this IRI can be de-referenced, nor assume any semantics from its structure.

5.1.3Self and Edit Links as atom:link Elements

Atom defines two types of links within an entry that represent retrieve or update/delete operations on the entry.

atom:link elements with a rel attribute of "self" can be used to retrieve the entity (via the URL specified in the href attribute).

atom:link elements with a rel attribute of "edit" can be used to retrieve, update, or delete the entity (via the URL specified in the href attribute).

An atom:entry element representing an OData entity SHOULD contain a self link, an edit link, or both for a particular entry, but MUST NOT contain more than one edit link for a given entry. Absence of an edit link implies that the entry is read-only.

5.1.4Stream Properties as atom:linkElements

An entity may have one or more stream properties (for example, a photo property of an employee entity). Properties that represent streams have a type of“Edm.Stream”.

OData uses atom:link elements to represent named stream properties of an entity.

For example, a stream property named “Photo” could be represented through an atom:link element as a child of the atom:entry element as follows:

<atom:link
rel="

type="img/jpg" title="Photo" href="Categories(0)/Photo"

A stream property named “Photo” could be edited through an atom:link element as a child of the atom:entry element as follows:

<atom:link
rel="

type="img/jpg" title="Photo" href="Categories(0)/Photo"

5.1.4.1The relAattribute of a Link Representing a Stream Property

The rel attribute for an atom:link element that can be used to retrieve a stream property is made up of the name of the OData Data Namespace, followed by the string “/mediaresource/”, followed by the name of the stream property on the entity.