OData ATOM Format Version 1.0 - OASIS



OData ATOM Format Version 1.0

Working Draft 01

1527 JanuaryNovember 20132

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Barbara Hartel (barbara.hartel@), SAP AG

Ram Jeyaraman (Ram.Jeyaraman@), Microsoft

Editor:

Martin Zurmuehl (martin.zurmuehl@), SAP AG

Colleen Evans (coevans@), 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.

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 OData Data Namespace 12

4.1.4 OData Metadata Namespace 12

5 Atom Element Definition 13

5.1 Entity Instances 13

5.1.1 The atom:entry Element 13

5.1.1.1 The metadata:etag Attribute 14

5.1.2 The atom:id Element 14

5.1.3 Self and Edit Links as atom:link Elements 14

5.1.4 Stream Properties as atom:link Elements 14

5.1.4.1 The rel Attribute of a Link Representing a Stream Property 14

5.1.4.2 The href Attribute of a Link Representing a Stream Property 15

5.1.4.3 The title Attribute of a Link Representing a Stream Property 15

5.1.5 Relationships as atom:link Elements 15

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

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

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

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

5.1.6 Inline Content within a metadata:inline Element 16

5.1.7 Relationship Links as atom:link Elements 16

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

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

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

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

5.1.8 Entity Type as an atom:category Element 17

5.1.9 Entity Content within an atom:content Element 17

5.1.9.1 Media Entities as Media Link Entries using the src Attribute 17

5.1.10 atom:link element for Updating Media Link Entries 17

5.1.10.1 The rel attribute for writing to Media Link Entries 17

5.1.10.2 The href attribute for writing to Media Link Entries 17

5.1.11 Entity Properties within a metadata:properties Element 17

5.1.11.1 Entity Property as a data:[propertyName] Element 18

5.1.12 Nulls represented using the metadata:null Attribute 19

5.1.13 Data Type represented using the metadata:type Attribute 19

5.2 Collections of Entities 19

5.2.1 Collection of Entities as an atom:feed Element 19

5.2.2 The atom:id Element within an atom:feed 19

5.2.3 Count as a metadata:count Element 20

5.2.4 Self-Links as atom:link Elements 20

5.2.5 Additional Results as an atom:link element 20

6 Actions 21

6.1 Actions as a metadata:action Element 21

6.1.1 The metadata Attribute for an Action 21

6.1.2 The target Attribute for an Action 21

6.1.3 The title Attribute for an Action 21

7 Functions 22

7.1 Functions as a metadata:function Element 22

7.1.1 The metadata Attribute for a Function 22

7.1.2 The target Attribute for a Function 22

7.1.3 The title Attribute for a Function 22

8 Annotations 23

8.1 The metadata:Annotation Element 23

8.1.1 The Term Attribute 23

8.1.2 The Type Attribute 23

8.1.3 The Target Attribute 23

8.2 Annotation Value 23

8.2.1 Attribute Value Notation 23

8.2.2 Primitive Values 24

8.2.3 Collection Values 24

8.2.4 Structure Annotations 24

8.3 Instance Annotation Targets 25

8.3.1 Annotating a Feed 25

8.3.2 Annotating an Entry 25

8.3.3 Annotating a Property 25

8.3.4 Annotating a Navigation Property 25

8.3.5 Annotating a Function or Action 25

8.3.6 Annotating an Error 25

9 Custom Mapping to Atom Elements 26

10 Individual Primitive or Complex Scalar Values 27

11 Collections of Primitive or Complex Scalar Values 28

12 Entity Container as a Workspace within a Service Document 29

12.1 The app:service element 29

12.1.1 Entity Container as an app:workspace element 29

12.1.2 Entity Sets as an app:collection element 29

12.1.3 Entity Set Name as an atom:title element 29

13 Links 30

13.1 Collection of Links as a data:links Element 30

13.2 Link as a data:uri Element 30

14 Errors as XML 31

14.1 The metadata:error Element 31

14.2 The metadata:code Element 31

14.3 The metadata:message Element 31

14.3.1 The xml:lang Attribute 31

14.4 The metadata:innererror Element 31

15 Extensibility 32

16 Conformance 33

Appendix A. Acknowledgments 34

Appendix B. Non-Normative Text 35

B.1 Subsidiary section 35

B.1.1 Sub-subsidiary section 35

Appendix C. Revision History 36

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

2 Normative 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.0 DD 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)”, IETF RFC3987, Januar 2005.

[RFC4287] M. Nottingham, Ed., R. Sayre, Ed. “The Atom Syndication Format”, IETF RFC4287, 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. .

3 Non-Normative References

None

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.

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 |"null" |null |

|Represents the absence of a value | | |

|Edm.Binary |((A-F | a-f | 0-9)(A-F | a-f | 0-9))* |23ABFF |

|Represent fixed- or variable- length binary | | |

|data | | |

|Edm.Boolean |"true" | "1" |true |

|Represents the mathematical concept of |"false" | "0" |false |

|binary-valued logic | | |

|Edm.Byte |(A-F | a-f | 0-9)(A-F | a-f | 0-9) |FF |

|Unsigned 8-bit integer value | | |

|Edm.DateTime |yyyy "-" mm "-" dd "T" hh ":" mm |2000-12-12T12:00 |

|Represents a date and time with values ranging|[":" ss["." fffffff]] | |

|from 12:00:00 midnight, January 1, 1753 A.D. | | |

|through 11:59:59 P.M, December 31, 9999 A.D. | | |

|Edm.Decimal |["-"][0-9]+[.][0-9]* |2.345 |

|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 | | |

|Edm.Double |["-"][0-9]+ ((.[0-9]+) | [E[+ | -][0-9]+]) |2.345 |

|Represents a floating point number with 15 | | |

|digits precision that can represent values | | |

|with approximate range of ± 2.23e -308 through| | |

|± 1.79e +308 | | |

|Edm.Single |["-"][0-9]+.[0-9] |2.5 |

|Represents a floating point number with 7 | | |

|digits precision that can represent values | | |

|with approximate range of ± 1.18e -38 through | | |

|± 3.40e +38 | | |

|Edm.Float |["-"][0-9]+.[0-9] |2.5 |

|Represents a floating point number with 7 | | |

|digits precision that can represent values | | |

|with approximate range of ± 1.18e -38 through | | |

|± 3.40e +38 | | |

|Edm.Guid |dddddddd "-" dddd "-" dddd "-" dddd "-" dddddddddddd |12345678-aaaa-bbbb-cccc-ddddeeeeffff |

|Represents a 16-byte (128-bit) unique | | |

|identifier value |d= A-F |a-f | 0-9 | |

|Edm.Int16 |[-][0-9]+ |16 |

|Represents a signed 16-bit integer value | | |

|Edm.Int32 |[-] [0-9]+ |32 |

|Represents a signed 32-bit integer value | | |

|Edm.Int64 |[-] [0-9]+ |64 |

|Represents a signed 64-bit integer value | | |

|Edm.SByte |[-] [0-9]+ |8 |

|Represents a signed 8-bit integer value | | |

|Edm.String |any UTF-8 character |OData |

|Represents fixed- or variable-length character|Note: See definition of UTF8-char in [RFC3629] | |

|data | | |

|Edm.Time |Defined by the lexical representation for xs:duration |PT23H59M59.9999999S |

|Represents the time of day with values ranging|in [XML-Schema-2] | |

|from 0:00:00.x to 23:59:59.y, where x and y | | |

|depend upon the precision | | |

|Edm.DateTimeOffset |Defined by the lexical representation for xs:datetime |2002-10-10T17:00:00Z |

|Represents date and time as an Offset in |(including timezone offset) in [XML-Schema-2] | |

|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 | | |

|Edm.DayTimeDuration |Defined by the lexical representation for |P12DT23H59M59.99999S |

|Represents a duration in days, hours, minutes,|xs:dayTimeDuration in [XML-Schema-2] | |

|seconds and fractions of seconds | | |

|Edm.Geography |N/A |N/A |

|Abstract base type for all Geography types. | | |

|Edm.GeographyPoint |srid "Point(" point ")" |SRID=123435; |

|Represents a point in a round-earth coordinate|srid= "SRID=" 1*5DIGIT ";" |Point(33.84 -117.91) |

|system. |point= LONG LAT | |

| | | |

| |Where LONG and LAT are EDM.Doubles representing | |

| |Longitude and Latitude. | |

|Edm.GeographyLineString |srid "LineString(" linestring ")" |SRID=123435; |

|Represents a linestring in a round-earth |linestring= point ["," point]+ |Linestring(33.84 -117.91, |

|coordinate system. | |48.87 2.78) |

|Edm.GeographyPolygon |srid "Polygon(" polygon ")" |SRID=123435; |

|Represents a polygon in a round-earth |polygon= ring "," [ring ","]* |Polygon((33.84 -117.91, |

|coordinate system. |ring= "(" firstpoint "," [point ","]* firstpoint ")" |48.87 2.78, |

| |]* ")" |33.84 -117.91)) |

| |firstpoint = point | |

|Edm.GeographyCollection |srid "GeographyCollection(" geographycollection ")" |SRID=123435; |

|Represents a collection of Geography Values. |geographycollection= geographyvalue ["," |GeographyCollection( |

| |geographyvalue]* |Point(33.84 -117.91), |

| |geographyvalue="Point("point")" | |Point(48.87 2.78)) |

| |"LineString(" linestring ")" | | |

| |"Polygon(" polygon ")" | | |

| |"GeographyCollection(" geographycollection ")" | | |

| |"MultiPoint("multipoint ")" | | |

| |"MultiLineString("multilinestring ")" | | |

| |"MultiPolygon("multipolygon ")" | |

|Edm.GeographyMultiPoint |srid "MultiPoint(" multipoint ")" |SRID=123435; |

|Represents a collection of points in a |multipoint= point ["," point]* |MultiPoint( |

|round-earth coordinate system | |33.84 -117.91, |

| | |(48.87 2.78)) |

|Edm.GeographyMultiLineString |srid "MultiLineString(" multilinestring ")" |SRID=123435; |

|Represents a collection of linestrings in a |multilinestring= "(" linestring ")" [",(" linestring |MultiLineString( |

|round-earth coordinate system. |")" ]* |(33.84 -117.91,48.87 2.78), |

| | |(33.84 -117.91, 28.36 -81.56)) |

|Edm.GeographyMultiPolygon |srid "MultiPolygon(" multipolygon ")" |SRID=123435; |

|Represents a collection of polygons in a |multipolygon= "(" polygon ")" [",(" polygon ")"]* |MultiPolygon( |

|round-earth coordinate system. | |( |

| | |(33.84 -117.91,(33.84 -117.91,28.36 |

| | |-81.56,33.84 -117.91))) |

|Edm.Geometry |N/A |N/A |

|Abstract base type for all Geometry types | | |

|Edm.GeometryPoint |srid "Point(" point ")" |SRID=123435; |

|Represents a point in a flat-earth coordinate | |Point(33.84 -117.91) |

|system. | | |

|Edm.GeometryLineString |srid "LineString(" linestring ")" |SRID=123435; |

|Represents a linestring in a flat-earth | |Linestring(33.84 -117.91, |

|coordinate system. | |48.87 2.78) |

|Edm.GeometryPolygon |srid "Polygon(" polygon ")" |SRID=123435; |

|Represents a polygon in a flat-earth | |Polygon((33.84 -117.91, |

|coordinate system. | |48.87 2.78,33.84 -117.91)) |

|Edm.GeometryCollection |srid "GeometryCollection(" geometrycollection ")" |SRID=123435; |

|Represents a collection of Geometry Values. |geometrycollection= geometryvalue ["," geometryvalue]*|GeometryCollection( |

| |geometryvalue= "Point("point")" | |Point(33.84 -117.91), |

| |"LineString(" linestring ")" | |Point(48.87 2.78)) |

| |"Polygon(" polygon ")" | | |

| |"GeometryCollection(" geometrycollection ")" | | |

| |"MultiPoint("multipoint ")" | | |

| |"MultiLineString("multilinestring ")" | | |

| |"MultiPolygon("multipolygon ")" | |

|Edm.GeometryMultiPoint |srid "MultiPoint(" multipoint ")" |SRID=123435; |

|Represents a collection of points in a | |MultiPoint((33.84 -117.91), |

|flat-earth coordinate system. | |(48.87 2.78)) |

|Edm.GeographyMultiLineString |srid "MultiLineString(" multilinestring ")" |SRID=123435; |

|Represents a collection of linestrings in a | |MultiLineString( |

|flat-earth coordinate system. | |(33.84 -117.91,48.87 2.78), |

| | |(33.84 -117.91,28.36 -81.56)) |

|Edm.GeographyMultiPolygon |srid "MultiPolygon(" multipolygon ")" |SRID=123435; |

|Represents a collection of polygons in a | |MultiPolygon( |

|flat-earth coordinate system. | |( |

| | |(33.84 -117.91,(33.84 -117.91,28.36 |

| | |-81.56,33.84 -117.91))) |

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.

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

1 Namespaces

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

1 Atom 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.

2 Atom 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.

3 OData 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 OData Metadata Namespace

Attributes and elements that represent metadata (such as type, null usage, and entry-level etags) are defined within the OData Metadata Namespace: . Custom 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.

Atom Element Definition

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

1 Entity 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:

(0)

2012-03-30T07:11:05Z

0

Bread

Whole grain bread

1992-01-01T00:00:00

4

2.5

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

1 The atom:entry Element

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

1 The 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].

2 The 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.

3 Self 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.

4 Stream Properties as atom:link Elements

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:

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

1 The rel Aattribute 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.

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

In both cases the full name must be used; the use of relative URLs in the rel attribute is not allowed.

2 The href Aattribute of a Link Representing a Stream Property

The href attribute of an atom:link element describing an OData stream property contains the URL that can be used to read, or write, the stream, according to the rel attribute. This URL may be relative or absolute.

3 The title aAttribute of a Link Representing a Stream Property

The title attribute on an atom:link element describing an OData relationship provides human-readable, possibly language-dependent, and not necessarily unique information about the link. It has no implied semantics in OData.

5 Relationships as atom:link Elements

OData uses atom:link elements to represent relationships between entities.

For example, the set of related products for a particular category may be represented through an atom:link element as a child of a category entry element as follows:

The related data for the relationship MAY be included in the Entity using a single child metadata:inline element.

1 The rel Aattribute of an atom:link Element Representing a Relationship

The rel attribute for an atom:link element that represents a relationship MUST be present and is made up of the name of the OData Data Namespace, followed by the string “/related/” followed by the name of the navigation property on the entity.

Note that the full name must be used; the use of relative URLs in the rel attribute is not allowed.

2 The href Aattribute of an atom:link Element Representing a Relationship

The href attribute of an atom:link element describing an OData relationship MUST be present and specifies the URL that can be used to retrieve the related entities. This URL may be relative or absolute.

3 The type Aattribute of an atom:link Element Representing a Relationship

The type attribute on an atom:link element describing an OData relationship MUST be present and determines whether the cardinality of the related end is:

a single entity, in which case the type=“application/atom+xml;type=entry”, or

a collection of entities, in which case the type=“application/atom+xml;type=feed”

4 The title Aattribute of an atom:link Element Representing a Relationship

The title attribute on an atom:link element describing an OData relationship SHOULD be present and equal to the name of the navigation property, and provides human-readable, possibly language-dependent, and not necessarily unique information about the link.

6 Inline Content within a metadata:inline Element

An atom:link element describing an OData relationship MAY contain a single metadata:inline element, in which case the element contains the feed (in the case of a collection) or entry (in the case of a single entity), where the feed or entry is a child of the metadata:inline element formatted as per this document.

An empty metadata:inline element means that there is no content associated with the relationship (i.e., the navigation property is null). Note that this case is distinct from the absence of a metadata:inline element which simply means that the contents of the relationship is deferred (not included in the payload).

It is valid to include the metadata:inline element in only a subset of the entries within a feed.

7 Relationship Links as atom:link Elements

OData uses atom:link elements to represent the collection of relationship link(s) between entities.

For example, the set of links between a category and related products may be represented through an atom:link element as a child of a category entry element as follows:

1 The rel Aattribute of an atom:link Element Representing Relationship Links

The rel attribute for an atom:link element that represents a collection of relationship links MUST be present and is made up of the name of the OData Data Namespace, followed by the string "/relatedlinks/" followed by the name of the navigation property on the entity.

Note that the full name must be used; the use of relative URLs in the rel attribute is not allowed.

2 The href Aattribute of an atom:link Element Representing Relationship Links

The href attribute of an atom:link element describing a relationship link MUST be present and specifies the URL that represents the collection of relationship links. This URL may be relative or absolute.

3 The type Aattribute of an atom:link Element Representing Relationship Links

The type attribute on an atom:link element describing a relationship link MUST be present and equal to the content type “application/xml”.

4 The title Aattribute of an atom:link Element Representing Relationship Links

The title attribute on an atom:link element describing a relationship link SHOULD be present and SHOULD be set to the name of the navigation property. The title attribute provides human-readable, possibly language-dependent, and not necessarily unique information about the link.

8 Entity Type as an atom:category Element

An OData entry MAY contain a single atom:category element with a scheme attribute equal to "" to identify the entity type of the entry. This element MUST be present if the entry represents an entity whose type is part of a type hierarchy.

An atom:category element describing an OData entity type MUST have a term attribute whose value is the namespace qualified name of the entity type of the entry.

The entry MAY contain additional atom:category elements with different scheme values; such atom:category elements have no semantic meaning in OData.

9 Entity Content within an atom:content Element

The atom:content element defines the content of the entry.

1 Media Entities as Media Link Entries using the src Attribute

The atom:content element MAY contain a src attribute, in which case the entry is a Media Link Entry, used to represent a Media Resource (for example, a photo). The value of the src attribute MUST be a URI that can be used to retrieve the content of the Media Resource.

For Media Entities, the atom:content element MUST be empty. In this case, properties of the Media Resource (other than the stream) are represented by the metadata:properties element as a sibling to, rather than a child of, the atom:content element.

10 atom:link element for Updating Media Link Entries

A Media Link Entry MAY contain an atom:link element with a rel attribute of "edit-media" to specify a URL that can be used to write to the BLOB associated with the entity.

1 The rel attribute for writing to Media Link Entries

Within an atom:entry representing a Media Link Entry, an atom:link element with a rel attribute of “edit-media” is used to identify a link that can be used to write to the BLOB associated with the entry.

2 The href attribute for writing to Media Link Entries

An atom:link element representing the link used to write to the BLOB associated with the entity MUST include an href attribute to specify the URI that can be used to write the stream. This URI may be relative or absolute.

11 Entity Properties within a metadata:properties Element

The metadata:properties element represents a subset of the property values for an entity that are not exclusively mapped to defined or custom elements, as described in Custom Mapping to Atom Elements.

The metadata:properties element MUST be a direct child of the atom:content element EXCEPT for the case where the entry represents a media entity, in which case the metadata:properties element MUST be a sibling of the atom:content element. In the case that all properties of the entity are exclusively mapped to defined or custom elements, an empty metadata:properties element MAY be present.

1 Entity Property as a data:[propertyName] Element

Within the metadata:properties element, individual data values of the entity are represented as elements where the name of the element is the name of the entity property within the OData Data Namespace.

The data:[PropertyName] element MAY include a metadata:type attribute to specify the type of the simple- or complex-typed instance.

For example, the following element within an metadata:properties element represents the “Rating” field with an integer value of 4:

4

1 Simple Typed Properties

For simple typed properties, the content of the data:[propertyName] element represents the value of the property. For example, the following would represent the value “CEO” for the Title property of an entity:

CEO

2 Complex Typed Properties

For complex typed properties, the content of the data:[propertyName] element consists of nested data:[propertyName] elements describing the properties of the complex type. It MAY include a metadata:type attribute to specify the type.

For example, the complex typed property “Name”, with properties “FirstName” and “LastName” would be respresented as:

Julie

Swansworth

3 Collection of Simple Typed Properties

For properties that represent a collection of simple types, the data:[propertyName] element may include a metadata:type attribute with a value of "Collection([SimpleTypeName])". The content of the element consists of nested child elements named “element”, in the OData Data Namespace, for each value in the collection.

The value of each simple-typed in the collection follows the syntax for simple typed properties.

elements MUST NOT contain the metadata:null="true" attribute value.

For example, the collection typed property “Emails” would be respresented as:

Julie@

Julie.Swansworth@

4 Collection of Complex Typed Properties

For properties that represent a collection of complex types, the data:[propertyName] element may include a metadata:type attribute with a value of "Collection([ComplexTypeName])“ attribute. The content of the element consists of nested child elements named “element", in the OData Data Namespace, for each complex typed value in the collection.

The element representing the instance may include a metadata:type attribute to specify the type of the individual element. The value of each complex-typed follows the syntax for complex-typed properties.

elements MUST NOT be empty and MUST NOT contain the metadata:null="true" attribute.

For example, the collection typed property “PhoneNumbers” would be represented as:

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download