OData ATOM Format Version 4.0
Working Draft 01
192 March 2013
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Barbara Hartel (), SAP AG
Ram Jeyaraman (), Microsoft
Editor:
Martin Zurmuehl (), SAP AG
Michael Pizzo (), Microsoft
Ralf Handl (), SAP AG
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 is related to:
· OData Core Part 1: Protocol
· OData Core Part 2: URL Conventions
· OData Core Part 3: Common Schema Definition Language
· OData ABNF Construction Rules
· OData JSON Format
This specification replaces or supersedes:
· None
Declared XML namespaces:
· http://docs.oasis-open.org/odata/ns/data
· http://docs.oasis-open.org/odata/ns/metadata
Abstract:
The OData protocol is comprised of a set of specifications for representing and interacting with structured content. A server offering an OData Service communicates with clients using that protocol and may offer responses to requests in several formats. This document describes the OData Atom Format, which is one of these possible formats. If the mime type application/atom+xml has been requested by the client, the response of any conforming server must follow the normative rules declared in this document.
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.
Copyright © OASIS Open 2012. All Rights Reserved.
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
1 Introduction 6
1.1 Terminology 6
1.2 Normative References 6
1.3 Non-Normative References 7
2 The xml:base Attribute 8
3 Primitive Types in Atom 8
4 Use of Atom 12
4.1 Namespaces 12
4.1.1 Atom Namespace 12
4.1.2 Atom Publishing Protocol Namespace 12
4.1.3 Atom Tombstone Namespace 12
4.1.4 OData Data Namespace 12
4.1.5 OData Metadata Namespace 12
5 Atom Element Definition 14
5.1 Entity Instances 14
5.1.1 The atom:entry Element 14
5.1.1.1 The metadata:etag Attribute 14
5.1.2 The atom:id Element 15
5.1.2.1 The metadata:set Attribute 15
5.1.3 Self and Edit Links as atom:link Elements 15
5.1.4 Stream Properties as atom:link Elements 15
5.1.4.1 The rel Attribute of a Link Representing a Stream Property 15
5.1.4.2 The href Attribute of a Link Representing a Stream Property 16
5.1.4.3 The title Attribute of a Link Representing a Stream Property 16
5.1.5 Relationships as atom:link Elements 16
5.1.5.1 The rel Attribute of an atom:link Element Representing a Relationship 16
5.1.5.2 The href Attribute of an atom:link Element Representing a Relationship 16
5.1.5.3 The type Attribute of an atom:link Element Representing a Relationship 16
5.1.5.4 The title Attribute of an atom:link Element Representing a Relationship 16
5.1.6 Inline Content within a metadata:inline Element 17
5.1.7 Relationship Links as atom:link Elements 17
5.1.7.1 The rel Attribute of an atom:link Element Representing Relationship Links 17
5.1.7.2 The href Attribute of an atom:link Element Representing Relationship Links 17
5.1.7.3 The type Attribute of an atom:link Element Representing Relationship Links 18
5.1.7.4 The title Attribute of an atom:link Element Representing Relationship Links 18
5.1.8 Entity Type as an atom:category Element 18
5.1.9 Entity Content within an atom:content Element 18
5.1.9.1 Media Entities as Media Link Entries using the src Attribute 18
5.1.10 atom:link element for Updating Media Link Entries 18
5.1.10.1 The rel attribute for writing to Media Link Entries 18
5.1.10.2 The href attribute for writing to Media Link Entries 18
5.1.11 Entity Properties within a metadata:properties Element 19
5.1.11.1 Entity Property as a data:[propertyName] Element 19
5.1.12 Nulls represented using the metadata:null Attribute 20
5.1.13 Data Type represented using the metadata:type Attribute 20
5.2 Resource References 21
5.2.1 Resource References as a metadata:ref element 21
5.2.1.1 Entity Id as a ref Attribute 21
5.3 Collections of Entities 21
5.3.1 Collection of Entities as an atom:feed Element 21
5.3.2 The atom:id Element within an atom:feed 21
5.3.3 Count as a metadata:count Element 21
5.3.4 Self-Links as atom:link Elements 21
5.3.5 Additional Results as an atom:link element 22
5.3.6 Delta Link as an atom:link element 22
5.4 Delta Response 22
5.4.1 Changed/Added Entities as atom:entry Elements 24
5.4.2 Deleted entities as atom-tombstone:deleted-entry Elements 24
5.4.2.1 Entity Id as a ref attribute 24
5.4.2.2 Deleted Time as a when Attribute 24
5.4.2.3 Deleted Reason as a metadata:reason Attribute 24
5.4.3 Links as metadata:link-entry Elements 24
5.4.3.1 Entity Id as a source Attribute 25
5.4.3.2 Navigation Property as a relationship Attribute 25
5.4.3.3 Related Entity as a target Attribute 25
5.4.3.4 Creation Time as a when Attribute 25
5.4.4 Deleted Links as metadata:deleted-link-entry Elements 25
5.4.4.1 Entity Id as a source Attribute 25
5.4.4.2 Navigation Property as a relationship Attribute 25
5.4.4.3 Related Entity as a target Attribute 26
5.4.4.4 Deleted Time as a when Attribute 26
6 Actions 27
6.1 Actions as a metadata:action Element 27
6.1.1 The metadata Attribute for an Action 27
6.1.2 The target Attribute for an Action 27
6.1.3 The title Attribute for an Action 27
7 Functions 28
7.1 Functions as a metadata:function Element 28
7.1.1 The metadata Attribute for a Function 28
7.1.2 The target Attribute for a Function 28
7.1.3 The title Attribute for a Function 28
8 Annotations 29
8.1 The metadata:annotation Element 29
8.1.1 The target Attribute 29
8.1.2 The term Attribute 29
8.1.3 The metadata:type Attribute 29
8.1.4 The metadata:null Attribute 29
8.2 Annotation Value 29
8.2.1 Primitive Values 29
8.2.2 Collection Values 30
8.2.3 Structure Annotations 30
8.3 Instance Annotation Targets 31
8.3.1 Annotating a Feed 31
8.3.2 Annotating an Entry 31
8.3.3 Annotating a Property 31
8.3.4 Annotating a Navigation Property 31
8.3.5 Annotating a Function or Action 31
8.3.6 Annotating an Error 31
9 Primitive or Complex Scalar Values 32
9.1 The metadata:value Element 32
9.1.1 The metadata:type Attribute 32
9.1.2 The metadata:null Attribute 32
10 Collections of Primitive or Complex Scalar Values 33
10.1 The metadata:value Element 33
10.1.1 The metadata:type Attribute 33
11 Entity Container as a Workspace within a Service Document 34
11.1 Service Document as an app:service Element 34
11.1.1 Entity Container as an app:workspace Element 34
11.1.2 Entity Sets as app:collection Elements 34
11.1.3 Entity Set Name as an atom:title Element 34
11.1.4 Function Imports as metadata:function-import Elements 34
11.1.5 Function Import Name as an atom:title Element 34
11.1.6 Named Entities as metadata:entity Elements 35
11.1.7 Entity Name as an atom:title Element 35
12 Action Parameters 36
13 Errors as XML 37
13.1 The metadata:error Element 37
13.2 The metadata:code Element 37
13.3 The metadata:message Element 37
13.4 The metadata:innererror Element 37
14 Extensibility 38
15 Conformance 39
Appendix A. Acknowledgments 40
Appendix B. Non-Normative Text 41
B.1 Subsidiary section 41
B.1.1 Sub-subsidiary section 41
Appendix C. Revision History 42
odata-atom-format-v4.0-wd01 Working Draft 01 192 March 2013
Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 1 of 1
1 Introduction
The OData protocol is comprised of a set of specifications for representing and interacting with structured content. This document describes the OData Atom Format of the payload returned from an OData Service when requesting the application/atom+xml mime type.
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 or entity resource reference
· a sequence of entities
· a sequence of changes
· 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 document
· 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-Protocol].
1.1 Terminology
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.2 Normative References
This document references the following related documents:
[OData-ABNF] OData ABNF Construction Rules Version 4.0. DD Month 2013. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-core/v4.0/csd01/odata-abnf-construction-rules-v4.0-csd01.doc.
[OData-CSDL] OData Version 4.0 Part 3: CSDL. DD Month 2013. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-core/v4.0/csd01/odata-core-v4.0-csd01-part3-csdl.doc.
[OData-JSON] OData Extension for JSON Data Version 4.0. DD Month 2012. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-json-ext/v4.0/csd01/odata-json-ext-v4.0-csd01.doc
[OData-Protocol] OData Version 4.0 Part 1: Protocol. DD Month 2013. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-core/v1.0/csd01/odata-core-v4.0-csd01-part1-protocol.doc.
[OData-URL] OData Version 4.0 Part2: URL Conventions DD Month 2013. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-core/v4.0/csd01/odata-core-v4.0-csd01-part2-url-conventions.doc
[RFC2119] S. Bradner, “Key words for use in RFCs to Indicate Requirement Levels”, IETF RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.
[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. http://www.ietf.org/rfc/rfc2616.txt.
[RFC3629] F. Yergeau, “UTF-8, a transformation format of ISO 10646”, IETF RFC 3629, November 2003. http://tools.ietf.org/html/rfc3629.
[RFC3987] M. Duerst, M. Suignard, “Internationalized Resource Identifiers (IRIs)”, IETF RFC3987, Januar 2005. http://www.ietf.org/rfc/rfc3987.txt
[RFC4287] M. Nottingham, Ed., R. Sayre, Ed. “The Atom Syndication Format”, IETF RFC4287, December 2005. http://www.ietf.org/rfc/rfc4287.txt
[RFC5023] J. Gregorio, Ed., B. de hOra, Ed., “The Atom Publishing Protocol”, IETF RFC5023, October 2007. http://www.ietf.org/rfc/rfc5023.txt
[RFC5646] Phillips, A., “Tags for Identifying Languages”, BCP 47, IETF RFC 5646, September 2009. http://tools.ietf.org/html/rfc5646.
[RFC6721] Snell, J., "The Atom 'deleted-entry' Element", IETF RFC 6721, September 2012, http://tools.ietf.org/html/rfc6721
[XML-Schema-2] Peterson, D. et al., “W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes”, W3C Recommendation, 5 April 2012. http://www.w3.org/TR/xmlschema11-2/.
1.3 Non-Normative References
None
2 The 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.
3 Primitive 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 / [0-9]+ / 42
Edm.Date
Represents a date with values ranging from January 1, 1753 A.D. through December 31, 9999 A.D. / yyyy "-" mm "-" dd / 2000-12-12
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.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.TimeOfDay
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:time in [XML-Schema-2] / 23:59:59.999999999999
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.Duration
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)))
4 Use 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.