ࡱ > { K bjbjzz vd ͑ }
)
)
)
)
) $ .) .) .) P ~) / .) & 0 p$ U d zU zU zU V :+ T * $ : F ˗
) V V ˗
)
) zU zU 4 T T T 1
) zU
) zU T T T f } zU cB=F 1 6 E D 0 & 2 J
2 } } 2
) e , T ˗ ˗ T & 2 ' :
OData Atom Format Version 4.0
Committee Specification Draft 01
26 April 2013
Specification URIs
This version:
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.doc" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.doc (Authoritative)
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.html" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.html
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.pdf" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.pdf
Previous version:
N/A
Latest version:
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.doc" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.doc (Authoritative)
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.html" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.html
HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.pdf" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.pdf
Technical Committee:
HYPERLINK "http://www.oasis-open.org/committees/odata/" OASIS Open Data Protocol (OData) TC
Chairs:
Barbara Hartel ( HYPERLINK "mailto:barbara.hartel@sap.com" barbara.hartel@sap.com), HYPERLINK "http://www.sap.com/" SAP AG
Ram Jeyaraman ( HYPERLINK "mailto:Ram.Jeyaraman@microsoft.com" Ram.Jeyaraman@microsoft.com), HYPERLINK "http://www.microsoft.com/" Microsoft
Editors:
Martin Zurmuehl ( HYPERLINK "mailto:martin.zurmuehl@sap.com" martin.zurmuehl@sap.com), HYPERLINK "http://www.sap.com/" SAP AG
Michael Pizzo ( HYPERLINK "mailto:mikep@microsoft.com" mikep@microsoft.com), HYPERLINK "http://www.microsoft.com/" Microsoft
Ralf Handl ( HYPERLINK "mailto:ralf.handl@sap.com" ralf.handl@sap.com), HYPERLINK "http://www.sap.com/" SAP AG
Additional artifacts:
This prose specification is one component of a Work Product which also includes:
OData Metadata XML Schema: HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/schemas/metadata.xsd" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/schemas/metadata.xsd
OData Atom Vocabulary: HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/vocabularies/Org.OData.Atom.V1.xml" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/vocabularies/Org.OData.Atom.V1.xml
Related work:
This specification is related to:
OData Version 4.0, a multi-part Work Product which includes:
OData Version 4.0 Part 1: Protocol. Latest version. HYPERLINK "http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html" http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
OData Version 4.0 Part 2: URL Conventions. Latest version. HYPERLINK "http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html"http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html
OData Version 4.0 Part 3: Common Schema Definition Language (CSDL). Latest version. HYPERLINK "http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part3-csdl.html"http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part3-csdl.html
ABNF components: OData ABNF Construction Rules Version 4.0 and OData ABNF Test Cases. HYPERLINK "http://docs.oasis-open.org/odata/odata/v4.0/csprd01/abnf/"http://docs.oasis-open.org/odata/odata/v4.0/csprd01/abnf/
OData JSON Format Version 4.0. Latest version. HYPERLINK "http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html" http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html
Declared XML namespaces:
HYPERLINK "http://docs.oasis-open.org/odata/ns/data" http://docs.oasis-open.org/odata/ns/data
HYPERLINK "http://docs.oasis-open.org/odata/ns/metadata" http://docs.oasis-open.org/odata/ns/metadata
Abstract:
The Open Data Protocol (OData) is a set of specifications for representing and interacting with structured content. This document extends the core OData Protocol specification by defining representations for OData requests and responses using an Atom format.
Status:
This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the Latest version location noted above for possible later revisions of this document.
Technical Committee members should send comments on this specification to the Technical Committees email list. Others should send comments to the Technical Committee by using the HYPERLINK "http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=odata" Send A Comment button on the Technical Committees web page at HYPERLINK "http://www.oasis-open.org/committees/odata/" http://www.oasis-open.org/committees/odata/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ( HYPERLINK "http://www.oasis-open.org/committees/odata/ipr.php" http://www.oasis-open.org/committees/odata/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[OData-Atom-Format-v4.0]
OData Atom Format Version 4.0. 26 April 2013. OASIS Committee Specification Draft 01. HYPERLINK "http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.html" http://docs.oasis-open.org/odata/odata-atom-format/v4.0/csd01/odata-atom-format-v4.0-csd01.html.
Notices
Copyright OASIS Open 2013. 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 HYPERLINK "http://www.oasis-open.org/policies-guidelines/ipr"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.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of HYPERLINK "http://www.oasis-open.org/" OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see HYPERLINK "http://www.oasis-open.org/policies-guidelines/trademark"http://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Table of Contents
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc355097109" 1 Introduction PAGEREF _Toc355097109 \h 7
HYPERLINK \l "_Toc355097110" 1.1 Terminology PAGEREF _Toc355097110 \h 7
HYPERLINK \l "_Toc355097111" 1.2 Normative References PAGEREF _Toc355097111 \h 7
HYPERLINK \l "_Toc355097112" 2 Atom Format Design PAGEREF _Toc355097112 \h 9
HYPERLINK \l "_Toc355097113" 2.1 Namespaces PAGEREF _Toc355097113 \h 9
HYPERLINK \l "_Toc355097114" 2.1.1 Atom Syndication PAGEREF _Toc355097114 \h 9
HYPERLINK \l "_Toc355097115" 2.1.2 Atom Publishing Protocol PAGEREF _Toc355097115 \h 9
HYPERLINK \l "_Toc355097116" 2.1.3 Atom Tombstone PAGEREF _Toc355097116 \h 9
HYPERLINK \l "_Toc355097117" 2.1.4 OData Data PAGEREF _Toc355097117 \h 9
HYPERLINK \l "_Toc355097118" 2.1.5 OData Metadata PAGEREF _Toc355097118 \h 9
HYPERLINK \l "_Toc355097119" 2.1.6 XML Schema Definition for OData Metadata PAGEREF _Toc355097119 \h 10
HYPERLINK \l "_Toc355097120" 3 Requesting the Atom Format PAGEREF _Toc355097120 \h 11
HYPERLINK \l "_Toc355097121" 4 Common Characteristics PAGEREF _Toc355097121 \h 12
HYPERLINK \l "_Toc355097122" 4.1 Header Content-Type PAGEREF _Toc355097122 \h 12
HYPERLINK \l "_Toc355097123" 4.2 Message Body PAGEREF _Toc355097123 \h 12
HYPERLINK \l "_Toc355097124" 5 Service Document PAGEREF _Toc355097124 \h 13
HYPERLINK \l "_Toc355097125" 5.1 Element app:service PAGEREF _Toc355097125 \h 13
HYPERLINK \l "_Toc355097126" 5.1.1 Element app:workspace PAGEREF _Toc355097126 \h 13
HYPERLINK \l "_Toc355097127" 5.1.2 Element app:collection PAGEREF _Toc355097127 \h 14
HYPERLINK \l "_Toc355097128" 5.1.3 Element metadata:function-import PAGEREF _Toc355097128 \h 14
HYPERLINK \l "_Toc355097129" 5.1.4 Element metadata:entity PAGEREF _Toc355097129 \h 15
HYPERLINK \l "_Toc355097130" 5.1.5 Element metadata:service-document PAGEREF _Toc355097130 \h 15
HYPERLINK \l "_Toc355097131" 6 Entity PAGEREF _Toc355097131 \h 16
HYPERLINK \l "_Toc355097132" 6.1 Element atom:entry PAGEREF _Toc355097132 \h 16
HYPERLINK \l "_Toc355097133" 6.1.1 Attribute metadata:etag PAGEREF _Toc355097133 \h 16
HYPERLINK \l "_Toc355097134" 6.1.2 Attribute metadata:metadata PAGEREF _Toc355097134 \h 16
HYPERLINK \l "_Toc355097135" 6.1.3 Attribute metadata:metadata-etag PAGEREF _Toc355097135 \h 17
HYPERLINK \l "_Toc355097136" 6.2 Element atom:id PAGEREF _Toc355097136 \h 17
HYPERLINK \l "_Toc355097137" 6.2.1 Element atom:category PAGEREF _Toc355097137 \h 17
HYPERLINK \l "_Toc355097138" 6.3 Element atom:content PAGEREF _Toc355097138 \h 17
HYPERLINK \l "_Toc355097139" 6.3.1 Self and Edit Links PAGEREF _Toc355097139 \h 17
HYPERLINK \l "_Toc355097140" 7 Property PAGEREF _Toc355097140 \h 19
HYPERLINK \l "_Toc355097141" 7.1 Primitive Value PAGEREF _Toc355097141 \h 19
HYPERLINK \l "_Toc355097142" 7.2 Element metadata:properties PAGEREF _Toc355097142 \h 19
HYPERLINK \l "_Toc355097143" 7.3 Element data:[PropertyName] PAGEREF _Toc355097143 \h 19
HYPERLINK \l "_Toc355097144" 7.3.1 Primitive and Enumeration Property PAGEREF _Toc355097144 \h 20
HYPERLINK \l "_Toc355097145" 7.3.2 Complex Property PAGEREF _Toc355097145 \h 20
HYPERLINK \l "_Toc355097146" 7.3.3 Primitive and Enumeration Collection Property PAGEREF _Toc355097146 \h 20
HYPERLINK \l "_Toc355097147" 7.3.4 Complex Collection Property PAGEREF _Toc355097147 \h 20
HYPERLINK \l "_Toc355097148" 7.3.5 Attribute metadata:null PAGEREF _Toc355097148 \h 21
HYPERLINK \l "_Toc355097149" 7.3.6 Attribute metadata:type PAGEREF _Toc355097149 \h 21
HYPERLINK \l "_Toc355097150" 8 Navigation Property PAGEREF _Toc355097150 \h 22
HYPERLINK \l "_Toc355097151" 8.1.1 Element atom:link PAGEREF _Toc355097151 \h 22
HYPERLINK \l "_Toc355097152" 8.2 Association Link PAGEREF _Toc355097152 \h 23
HYPERLINK \l "_Toc355097153" 8.2.1 Element atom:link PAGEREF _Toc355097153 \h 23
HYPERLINK \l "_Toc355097154" 8.3 Expanded Navigation Property PAGEREF _Toc355097154 \h 23
HYPERLINK \l "_Toc355097155" 8.4 Deep Inserts PAGEREF _Toc355097155 \h 24
HYPERLINK \l "_Toc355097156" 8.5 Bind Operations PAGEREF _Toc355097156 \h 25
HYPERLINK \l "_Toc355097157" 9 Stream Property PAGEREF _Toc355097157 \h 26
HYPERLINK \l "_Toc355097158" 9.1 Element atom:link PAGEREF _Toc355097158 \h 26
HYPERLINK \l "_Toc355097159" 9.1.1 Attribute rel PAGEREF _Toc355097159 \h 26
HYPERLINK \l "_Toc355097160" 9.1.2 Attribute href PAGEREF _Toc355097160 \h 26
HYPERLINK \l "_Toc355097161" 9.1.3 Attribute type PAGEREF _Toc355097161 \h 26
HYPERLINK \l "_Toc355097162" 9.1.4 Attribute metadata:etag PAGEREF _Toc355097162 \h 26
HYPERLINK \l "_Toc355097163" 9.1.5 Attribute title PAGEREF _Toc355097163 \h 26
HYPERLINK \l "_Toc355097164" 10 Media Entity PAGEREF _Toc355097164 \h 27
HYPERLINK \l "_Toc355097165" 10.1 Element atom:link PAGEREF _Toc355097165 \h 27
HYPERLINK \l "_Toc355097166" 10.1.1 Attribute rel PAGEREF _Toc355097166 \h 27
HYPERLINK \l "_Toc355097167" 10.1.2 Attribute href PAGEREF _Toc355097167 \h 27
HYPERLINK \l "_Toc355097168" 10.2 Element atom:content PAGEREF _Toc355097168 \h 27
HYPERLINK \l "_Toc355097169" 10.2.1 Attribute src PAGEREF _Toc355097169 \h 27
HYPERLINK \l "_Toc355097170" 10.2.2 Attribute type PAGEREF _Toc355097170 \h 27
HYPERLINK \l "_Toc355097171" 11 Individual Property PAGEREF _Toc355097171 \h 28
HYPERLINK \l "_Toc355097172" 11.1 Single Scalar Value PAGEREF _Toc355097172 \h 28
HYPERLINK \l "_Toc355097173" 11.1.1 Element metadata:value PAGEREF _Toc355097173 \h 28
HYPERLINK \l "_Toc355097174" 11.2 Collection of Scalar Values PAGEREF _Toc355097174 \h 28
HYPERLINK \l "_Toc355097175" 11.2.1 Element metadata:value PAGEREF _Toc355097175 \h 29
HYPERLINK \l "_Toc355097176" 12 Collection of Entities PAGEREF _Toc355097176 \h 30
HYPERLINK \l "_Toc355097177" 12.1 Element atom:feed PAGEREF _Toc355097177 \h 30
HYPERLINK \l "_Toc355097178" 12.1.1 Attribute metadata:metadata PAGEREF _Toc355097178 \h 30
HYPERLINK \l "_Toc355097179" 12.1.2 Attribute metadata:metadata-etag PAGEREF _Toc355097179 \h 30
HYPERLINK \l "_Toc355097180" 12.1.3 Element atom:id PAGEREF _Toc355097180 \h 30
HYPERLINK \l "_Toc355097181" 12.1.4 Element metadata:count PAGEREF _Toc355097181 \h 30
HYPERLINK \l "_Toc355097182" 12.1.5 Element atom:link PAGEREF _Toc355097182 \h 30
HYPERLINK \l "_Toc355097183" 13 Resource Reference PAGEREF _Toc355097183 \h 32
HYPERLINK \l "_Toc355097184" 13.1 Element metadata:ref PAGEREF _Toc355097184 \h 32
HYPERLINK \l "_Toc355097185" 13.1.1 Attribute ref PAGEREF _Toc355097185 \h 32
HYPERLINK \l "_Toc355097186" 14 Delta Response PAGEREF _Toc355097186 \h 33
HYPERLINK \l "_Toc355097187" 14.1 Added/Changed Entity PAGEREF _Toc355097187 \h 34
HYPERLINK \l "_Toc355097188" 14.2 Deleted Entity PAGEREF _Toc355097188 \h 34
HYPERLINK \l "_Toc355097189" 14.2.1 Element atom-tombstone:deleted-entry PAGEREF _Toc355097189 \h 34
HYPERLINK \l "_Toc355097190" 14.3 Link PAGEREF _Toc355097190 \h 35
HYPERLINK \l "_Toc355097191" 14.3.1 Element metadata:link-entry PAGEREF _Toc355097191 \h 35
HYPERLINK \l "_Toc355097192" 14.4 Deleted Link PAGEREF _Toc355097192 \h 35
HYPERLINK \l "_Toc355097193" 14.4.1 Element metadata:deleted-link-entry PAGEREF _Toc355097193 \h 35
HYPERLINK \l "_Toc355097194" 15 Function PAGEREF _Toc355097194 \h 37
HYPERLINK \l "_Toc355097195" 15.1 Element metadata:function PAGEREF _Toc355097195 \h 37
HYPERLINK \l "_Toc355097196" 15.1.1 Attribute metadata PAGEREF _Toc355097196 \h 37
HYPERLINK \l "_Toc355097197" 15.1.2 Attribute title PAGEREF _Toc355097197 \h 37
HYPERLINK \l "_Toc355097198" 16 Action PAGEREF _Toc355097198 \h 38
HYPERLINK \l "_Toc355097199" 16.1 Element metadata:action PAGEREF _Toc355097199 \h 38
HYPERLINK \l "_Toc355097200" 16.1.1 Attribute metadata PAGEREF _Toc355097200 \h 38
HYPERLINK \l "_Toc355097201" 16.1.2 Attribute target PAGEREF _Toc355097201 \h 38
HYPERLINK \l "_Toc355097202" 16.1.3 Attribute title PAGEREF _Toc355097202 \h 38
HYPERLINK \l "_Toc355097203" 17 Action Parameters PAGEREF _Toc355097203 \h 39
HYPERLINK \l "_Toc355097204" 18 Instance Annotations PAGEREF _Toc355097204 \h 40
HYPERLINK \l "_Toc355097205" 18.1 Element metadata:annotation PAGEREF _Toc355097205 \h 40
HYPERLINK \l "_Toc355097206" 18.1.1 Attribute target PAGEREF _Toc355097206 \h 40
HYPERLINK \l "_Toc355097207" 18.1.2 Attribute term PAGEREF _Toc355097207 \h 40
HYPERLINK \l "_Toc355097208" 18.1.3 Attribute metadata:type PAGEREF _Toc355097208 \h 40
HYPERLINK \l "_Toc355097209" 18.1.4 Attribute metadata:null PAGEREF _Toc355097209 \h 40
HYPERLINK \l "_Toc355097210" 18.2 Annotation Values PAGEREF _Toc355097210 \h 40
HYPERLINK \l "_Toc355097211" 18.2.1 Primitive Values PAGEREF _Toc355097211 \h 40
HYPERLINK \l "_Toc355097212" 18.2.2 Collection Values PAGEREF _Toc355097212 \h 41
HYPERLINK \l "_Toc355097213" 18.2.3 Structure Annotations PAGEREF _Toc355097213 \h 41
HYPERLINK \l "_Toc355097214" 18.3 Instance Annotation Targets PAGEREF _Toc355097214 \h 42
HYPERLINK \l "_Toc355097215" 18.3.1 Feed PAGEREF _Toc355097215 \h 42
HYPERLINK \l "_Toc355097216" 18.3.2 Entry PAGEREF _Toc355097216 \h 42
HYPERLINK \l "_Toc355097217" 18.3.3 Complex Type PAGEREF _Toc355097217 \h 42
HYPERLINK \l "_Toc355097218" 18.3.4 Property PAGEREF _Toc355097218 \h 42
HYPERLINK \l "_Toc355097219" 18.3.5 Navigation Property PAGEREF _Toc355097219 \h 42
HYPERLINK \l "_Toc355097220" 18.3.6 Function or Action PAGEREF _Toc355097220 \h 42
HYPERLINK \l "_Toc355097221" 18.3.7 Error PAGEREF _Toc355097221 \h 42
HYPERLINK \l "_Toc355097222" 19 Error Reponse PAGEREF _Toc355097222 \h 43
HYPERLINK \l "_Toc355097223" 19.1 Element metadata:error PAGEREF _Toc355097223 \h 43
HYPERLINK \l "_Toc355097224" 19.2 Element metadata:code PAGEREF _Toc355097224 \h 43
HYPERLINK \l "_Toc355097225" 19.3 Element metadata:message PAGEREF _Toc355097225 \h 43
HYPERLINK \l "_Toc355097226" 19.4 Element metadata:target PAGEREF _Toc355097226 \h 43
HYPERLINK \l "_Toc355097227" 19.5 Element metadata:details PAGEREF _Toc355097227 \h 43
HYPERLINK \l "_Toc355097228" 19.5.1 Element metadata:detail PAGEREF _Toc355097228 \h 43
HYPERLINK \l "_Toc355097229" 19.5.2 Element metadata:code PAGEREF _Toc355097229 \h 44
HYPERLINK \l "_Toc355097230" 19.5.3 Element metadata:message PAGEREF _Toc355097230 \h 44
HYPERLINK \l "_Toc355097231" 19.5.4 Element metadata:target PAGEREF _Toc355097231 \h 44
HYPERLINK \l "_Toc355097232" 19.6 Element metadata:innererror PAGEREF _Toc355097232 \h 44
HYPERLINK \l "_Toc355097233" 20 Extensibility PAGEREF _Toc355097233 \h 45
HYPERLINK \l "_Toc355097234" 21 Conformance PAGEREF _Toc355097234 \h 46
HYPERLINK \l "_Toc355097235" Appendix A. Acknowledgments PAGEREF _Toc355097235 \h 47
HYPERLINK \l "_Toc355097236" Appendix B. Revision History PAGEREF _Toc355097236 \h 48
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 HYPERLINK \l "_Individual_Primitive_or" single primitive value
a HYPERLINK \l "_Collections_of_Primitive" sequence of primitive values
a HYPERLINK \l "_Individual_Primitive_or" single structured (complex) value
a HYPERLINK \l "_Collections_of_Primitive" sequence of structured (complex) values
an HYPERLINK \l "_Entity_Instances" entity (a structured type with an identity)
a HYPERLINK \l "_Entity_References" resource reference
a HYPERLINK \l "_Collections_of_Entities_1" sequence of entities
a sequence of HYPERLINK \l "_Delta_Response" changes
a HYPERLINK \l "_Entity_Content_within" media resource
a single instance of a mime type
a HYPERLINK \l "_LinkUrl_as_a" single link to a related entity
a HYPERLINK \l "_Collection_of_LinkUrls" collection of links to related entities
a HYPERLINK \l "_Service_Document_as" service document describing the collections (entity sets) exposed by the service
an xml document describing the entity model exposed by the service
an HYPERLINK \l "_Errors_as_XML" 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 REF ODataCSDL \h [OData-CSDL]. For a description of batch requests and responses, see [ REF ODataCore \h Error! Reference source not found.].
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 [ REF rfc2119 \h RFC2119].
Normative References
This document references the following related documents:
[GML] Portele, C., Ed., "OpenGIS Geography Markup Language (GML) Encoding", August 2007. HYPERLINK "http://portal.opengeospatial.org/files/?artifact_id=20509" http://portal.opengeospatial.org/files/?artifact_id=20509.
[OData-ABNF] OData ABNF Construction Rules Version 4.0. See link in Related work section on cover page.
[OData-CSDL] OData Version 4.0 Part 3: Common Schema Definition Language (CSDL). See link in Related work section on cover page.
[OData-MetaXML] OData Metadata XML Schema.See link in Additional artifacts section on cover page.
[OData-Protocol] OData Version 4.0 Part1: Protocol.See link inRelated work section on cover page.
[OData-URL] OData Version 4.0 Part 2: URL Conventions. See link in "Related work" section on cover page.
[OData-VocAtom] OData Atom Vocabulary.See link in Additional artifacts section on cover page.
[RFC2119] Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, March 1997. HYPERLINK "http://www.ietf.org/rfc/rfc2119.txt" http://www.ietf.org/rfc/rfc2119.txt.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, Uniform Resource Identifier (URI): Generic Syntax, IETF RFC3986, January 2005. HYPERLINK "http://www.ietf.org/rfc/rfc3986.txt" http://www.ietf.org/rfc/rfc3986.txt.
[RFC3987] Duerst, M. and M. Suignard, Internationalized Resource Identifiers (IRIs), RFC3987, January 2005. HYPERLINK "http://www.ietf.org/rfc/rfc3987.txt" http://www.ietf.org/rfc/rfc3987.txt.
[RFC4287] Nottingham, M., Ed., and R. Sayre, Ed. The Atom Syndication Format, RFC4287, December 2005. HYPERLINK "http://www.ietf.org/rfc/rfc4287.txt" http://www.ietf.org/rfc/rfc4287.txt.
[RFC5023] Gregorio, J., Ed., and B. de hOra, Ed., The Atom Publishing Protocol, RFC5023, October 2007. HYPERLINK "http://www.ietf.org/rfc/rfc5023.txt" http://www.ietf.org/rfc/rfc5023.txt.
[RFC5646] Phillips, A.., Ed., and M. Davis, Ed., Tags for Identifying Languages, BCP 47, RFC 5646, September 2009. HYPERLINK "http://tools.ietf.org/html/rfc5646" http://tools.ietf.org/html/rfc5646.
[RFC6721] Snell, J., "The Atom 'deleted-entry' Element", RFC 6721, September 2012, HYPERLINK "http://tools.ietf.org/html/rfc6721" http://tools.ietf.org/html/rfc6721.
Atom Format Design
The Atom Syndication Format REF RFC4287 \h [RFC4287] defines an XML-based format for describing collections (feeds) made up of individual entries. The Atom Publishing Protocol REF RFC5023 \h [RFC5023] defines an application-level protocol based on HTTP transfer of Atom-formatted representations.
OData builds on REF RFC4287 \h [RFC4287] and REF RFC5023 \h [RFC5023] by defining additional conventions and extensions for representing and querying entity data.
As specified in REF RFC4287 \h \* MERGEFORMAT [RFC4287] and REF RFC5023 \h \* MERGEFORMAT [RFC5023] processors that encounter foreign markup MUST NOT stop processing and MUST NOT signal an error. This includes additional elements or attributes in any namespace, including elements and attributes in the OData HYPERLINK \l "_OData_Data_Namespace" Data and HYPERLINK \l "_OData_Metadata_Namespace" Metadata namespaces, e.g. values for properties not declared in $metadata, and HYPERLINK \l "_Annotations" annotations that are not defined in the version of the payload being returned.
Namespaces
OData defines meaning for elements and attributes defined in the following namespaces.
Atom Syndication
Atom elements and attributes are defined within the Atom namespace: HYPERLINK "http://www.w3.org/2005/Atom" http://www.w3.org/2005/Atom.
In this specification the namespace prefix atom is used to represent the Atom Namespace, however the prefix name is not prescriptive.
Atom Publishing Protocol
Atom Publishing Protocol (AtomPub) elements and attributes are defined within the AtomPub namespace: HYPERLINK "http://www.w3.org/2007/app" http://www.w3.org/2007/app.
In this specification the namespace prefix app is used to represent the AtomPub Namespace, however the prefix name is not prescriptive.
Atom Tombstone
The deleted-entry element is defined within the Atom Tombstone namespace: http://purl.org/atompub/tombstones/1.0.
In this specification the namespace prefix atom-tombstone is used to represent the Atom Tombstone Namespace, however the prefix name is not prescriptive.
OData Data
Elements that describe the actual data values for an entity are qualified with the OData Data Namespace: http://docs.oasis-open.org/odata/ns/data.
In this specification the namespace prefix data is used to represent the OData Data Namespace, however the prefix name is not prescriptive.
OData Metadata
Attributes and elements that represent metadata (such as type, null usage, and entry-level etags) are defined within the OData Metadata Namespace:
http://docs.oasis-open.org/odata/ns/metadata.
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.
XML Schema Definition for OData Metadata
This specification contains a normative XML schema for the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, see HYPERLINK \l "ODataMetaXML" [OData-MetaXML].
It only define the shape of well-formed OData metadata, but is not descriptive enough to define what correct OData metadata is. This specification document defines additional rules that correct OData metadata MUST fulfill. In case of doubt on what makes OData metadata correct the rules defined in this specification document take precedence.
Requesting the Atom Format
The OData Atom format MAY be requested using the $format query option in the request URL with the MIME type application/atom+xml, or the case-insensitive abbreviation atom.
Alternatively, this format MAY be requested using the Accept header with the MIME type application/atom+xml.
If specified, $format overrides any value specified in the Accept header.
The HYPERLINK \l "_Service_Document" service document MAY additionally be requested with the more specific MIME type application/atomsvc+xml using either $format or Accept.
All resources MAY additionally be requested with the less specific MIME type application/xml using either $format or Accept, or the case-insensitive abbreviation xml using $format.
Common Characteristics
Header Content-Type
The Content-Type header for Atom responses MUST use the most specific MIME type for the requested resource that is indicated as acceptable by the client.
Requests using the $format query option with the abbreviation atom MUST receive the MIME type
application/atomsvc+xml for the HYPERLINK \l "_Service_Document" service document,
application/atom+xml for entities and collections of entities, references, or changes,
application/xml for all other resources.
Requests using $format or an Accept header with value application/atom+xml MUST receive the MIME type
application/xml for the HYPERLINK \l "_Service_Document" service document,
application/atom+xml for entities and collections of entities, refereces, or changes,
application/xml for all other resources.
Requests using $format or an Accept header with value application/xml or $format with the abbreviation xml MUST receive the MIME type application/xml for all resources.
Data modification requests for entities or collections of entities MUST specify a Content-Type header with a value of either application/atom+xml or application/xml. Data modification requests for all other resources MUST specify a Content-Type header with a value of application/xml.
Message Body
Message Body
Each message body MUST be represented as an XML document with a single root element. This element is either the representation of an HYPERLINK \l "_Representing_an_Entity" entity, an HYPERLINK \l "_Representing_an_Entity_2" entity reference or a HYPERLINK \l "_Representing_a_Complex" complex type instance, a HYPERLINK \l "_Representing_a_Primitive" primitive value, a HYPERLINK \l "_Toc345948708" collection of primitive values, HYPERLINK \l "_Toc345948708" a collection of complex values, a HYPERLINK \l "_Toc342598610" collection of entities, or a collection of entries that represent HYPERLINK \l "_Representing_Changes_(Deltas)_1" changes to a previous result.
Relative URLs
OData payloads MAY use relative references as defined in HYPERLINK \l "RFC3986" REF RFC3986 \h [RFC3986] by specifying the xml:base attribute to define a base URI for relative references defined within the scope of the element containing the xml:base attribute.
Service Document
AtomPub defines the concept of a service document to represent the set of available collections. OData uses the service document to describe the entity sets, named entities, and parameterless function imports published by the service.
Example:
DataOrder DetailsContoso Ltd.Best-Selling ProductsEastern Region Sales
Element app:service
The service document contains a single app:service element. The app:service element contains one or more HYPERLINK \l "appWorkspace" app:workspace elements.
Element app:workspace
OData represents the each entity container as an app:workspace element. An app:workspace element contains zero or more HYPERLINK \l "appCollection" app:collection elements, one for each entity set published by the container, zero or more HYPERLINK \l "_Named_Entities_as" metadata:function-import elements, one for each function import published by the continer, and zero or more HYPERLINK \l "_Named_Entities_as" metadata:entity elements, one for each named entity published by the container.
Attribute metadata:name
The metadata:name attribute MUST contain the namespace- or alias-qualified name of the entity container that is represented by the HYPERLINK \l "appWorkspace" app:workspace element. It MAY be omitted if the workspace represents the default entity container.
For more information on namespace- and alias-qualified names, see REF ODataCSDL \h [OData-CSDL].
Attribute metadata:metadata
An app:workspace element MUST have a metadata attribute, defined in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, whose value is the URL that returns the metadata document of the service.
For more information on the format of the metadata document, see HYPERLINK \l "ODataCSDL" [OData-CSDL].
Attribute metadata:metadata-etag
An app:workspace element MAY have a metadata:metadata-etag attribute to specify an ETag that can be used to determine the current version of the service's metadata document.
For details on how ETags are used, see [ REF OData \h Error! Reference source not found.].
Element title
As defined in HYPERLINK \l "RFC5023" [RFC-5023], the app:workspace element MUST contain a title element containing the human-readable description of the workspace. This value may be different from the name of the entity container exposed by the HYPERLINK \l "_Attribute_metadata:name" metadata:name attribute.
Element app:collection
OData represents entity sets that are not marked with IncludeInServiceDocument="false" (see HYPERLINK \l "ODataCSDL" [OData-CSDL]) as app:collection elements contained within the app:workspace element.
Order Details
Attribute href
The app:collection element MUST contain an href attribute which represents a URL that can be used to retrieve the members of the entity set.
Attribute metadata:name
The metadata:name attribute MUST contain the name of the entity set which MAY be unqualified if the enclosing HYPERLINK \l "appWorkspace" app:workspace represents the default entity container.
It MAY be omitted if its value is identical the the value of the href attribute, which is the case if the service uses relative URLs following the OData URL conventions described in REF ODataURL \h \* MERGEFORMAT Error! Reference source not found..
Element atom:title
The atom:title element within the HYPERLINK \l "appCollection" app:collection MUST contain a human-readable description of the entity set which MAY be the name of the entity set.
Element metadata:function-import
OData represents function imports that are marked with IncludeInServiceDocument="true" (see HYPERLINK \l "ODataCSDL" [OData-CSDL]) as metadata:function-import elements.
Attribute href
The metadata:function-import element MUST contain an href attribute which represents a URL that can be used to retrieve the function import result.
Attribute metadata:name
The metadata:name attribute MUST contain the name of the function import which MAY be unqualified if the enclosing HYPERLINK \l "appWorkspace" app:workspace represents the default entity container.
It MAY be omitted if its value is identical the the value of the href attribute, which is the case if the service uses relative URLs following the OData URL conventions described in REF ODataURL \h \* MERGEFORMAT Error! Reference source not found..
Element atom:title
The atom:title element within the HYPERLINK \l "_Function_Imports_as" metadata:function-import element MUST contain a human-readable description of the function import which MAY be the name of the function import.
Element metadata:entity
OData represents named entities as metadata:entity elements.
Attribute href
The metadata:entity element MUST contain an href attribute which represents a URL that can be used to retrieve the entity.
Attribute metadata:name
The metadata:name attribute MUST contain the name of the entity which MAY be unqualified if the enclosing HYPERLINK \l "appWorkspace" app:workspace represents the default entity container.
It MAY be omitted if its value is identical the the value of the href attribute, which is the case if the service uses relative URLs following the OData URL conventions described in REF ODataURL \h \* MERGEFORMAT Error! Reference source not found..
Element atom:title
The atom:title element within the HYPERLINK \l "_Named_Entities_as_1" metadata:entity element MUST contain a human-readable description of the entity which MAY be the name of the entity.
Element metadata:service-document
OData represents related service documents as metadata:service-document elements.
Eastern Region Sales
Attribute href
The metadata:service-document element MUST contain an href attribute which represents a URL that can be used to retrieve the related service document.
Element atom:title
The metadata:service-document element MUST contain an atom:title element containing a human-readable description of the related service document.
Entity
Entities, whether individual or within an Atom feed, are represented as HYPERLINK \l "atomEntry" atom:entry elements.
Example:
http://services.odata.org/OData/OData.svc/Products(0)2012-03-30T07:11:05Z0BreadWhole grain bread
1992-01-01
42.5
This section defines the elements and attributes within an atom:entry element that are assigned meaning in OData.
Element atom:entry
An atom:entry element is used to represent a single entity, which is an instance of a structured type with an identity.
Attribute metadata:etag
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 [ REF ODataCore \h Error! Reference source not found.].
Attribute metadata:metadata
If the root of the response is an atom:entry element, or the entity set cannot be determined from the HYPERLINK \l "_The_odata.metadata_Annotation" metadata URL of the feed, the atom:entry element MUST have a metadata attribute, defined in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, whose value is the metadata URL that describes the entry. This URL MAY be absolute or relative to the metadata URL of the feed.
For more information on the metadata URL, see [ REF ODataCore \h Error! Reference source not found.].
Attribute metadata:metadata-etag
If the root of the response is an atom:entry element, it MAY have a metadata:metadata-etag attribute to specify an ETag that can be used to determine the current version of the service's metadata document.
For details on how ETags are used, see [ REF ODataCore \h Error! Reference source not found.].
Element atom:id
The atom:id element defines a durable, opaque, globally unique identifier for the entry. Its content must be an IRI as defined in REF RFC3987 \h RFC3987. The consumer of the feed must not assume this IRI can be de-referenced, nor assume any semantics from its structure.
Element atom:category
An OData entry MUST contain a single atom:category element with a scheme attribute equal to http://docs.oasis-open.org/odata/ns/scheme to identify the entity type of the entry.
An atom:category element describing an OData entity type MUST have a term attribute whose value is the namespace- or alias-qualified name of the entity type of the entry, in which case the type MUST be defined in the metadata document indicated by the current metadata URL, otherwise it MUST be a full URL to a metadata document with the namespace-qualified name of the instances type appended as a URL fragment.
For example, the following represents an entity whose type is Model.VipCustomer, defined within the current metadata document:
The following represents an entity whose type is Model.VipCustomer, defined within the http://host/alternate/$metadata document:
For more information on namespace- and alias-qualified names, see REF ODataCSDL \h [OData-CSDL].
The entry MAY contain additional atom:category elements with different scheme values; such atom:category elements have no semantic meaning in OData.
Element atom:content
The atom:content element contains the properties of the entity as a HYPERLINK \l "metadataProperties" metadata:properties element unless the entity is a HYPERLINK \l "_Media_Entity" media entity.
Self and Edit Links
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 entity. The absence of a self link implies that the edit link can be used to retrieve the entity. The absence of an edit link implies that the entity is read-only.
Property
Primitive Value
OData Atom and XML payloads represent values of primitive types following the rules of REF ODataABNF \h [GML] Portele, C., Ed., "OpenGIS Geography Markup Language (GML) Encoding", August 2007. http://portal.opengeospatial.org/files/?artifact_id=20509.
[OData-ABNF].
Geography and Geometry values are represented as defined in [ REF GML \h GML].
Values of the other primitive types are represented according to the xxxValue rules, i.e. Edm.Binary as binaryValue etc.
Example:
truefalse-1283.1415926535897931INF34.95Say "Hello", then go!2012-12-032012-12-03T07:16:23ZP12DT23H59M59.999999999999S07:59:59.99901234567-89ab-cdef-0123-456789abcdef0Yellow64.1 142.1
Note that the line break in the body of StringValue is intentional, it represents a line break.
Element metadata:properties
The metadata:properties element represents property values for an entity.
Element data:[PropertyName]
Within the metadata:properties element, individual entity properties are represented as elements where the name of the element is the name of the entity property within the HYPERLINK \l "ODataDataNamespace" OData Data Namespace.
The data:[PropertyName] element MAY include a HYPERLINK \l "metadataType" metadata:type attribute to specify the type of the primitive- 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
The data:[PropertyName] element MAY include a HYPERLINK \l "_Nulls_represented_using" metadata:null attribute to specify that the primitive- or complex-typed instance has the null value.
For example:
Primitive and Enumeration Property
For primitive properties, the content of the data:[PropertyName] element represents the value of the property following the syntax for HYPERLINK \l "_Relationships_as_atom:link" primitive values. For example, the following would represent the string value CEO for the Title property of an entity:
CEO
The following would represent the combined enumeration values Yellow and Solid for the Pattern property of an entity:
Solid,Yellow
Complex Property
For complex 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:
JulieSwansworth
Primitive and Enumeration Collection Property
For properties that represent a collection of primitive or enumeration values, the data:[PropertyName] element may include a metadata:type attribute with a value of "Collection([PrimitiveTypeName])". The content of the element consists of nested child elements named element in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata Namespace for each value in the collection.
The value of each in the collection follows the syntax for HYPERLINK \l "_Relationships_as_atom:link" primitive values.
elements MUST NOT contain the metadata:null="true" attribute value.
Example:
Julie@Swansworth.comJulie.Swansworth@work.com
Complex Collection Property
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 HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata 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 HYPERLINK \l "ComplexTypedProperties" complex-typed properties.
metadata:element elements MUST NOT be empty and MUST NOT contain the metadata:null="true" attribute.
Example:
425-555-1212Home425-555-0178CellSprint
Attribute metadata:null
Null-valued properties are represented as empty elements with the metadata:null="true" attribute.
The metadata:null attribute distinguishes null values from other empty content (such as an empty string).
For example, the following represents an empty apartment number:
The absence of the metadata:null attribute is equivalent to specifying metadata:null="false".
Attribute metadata:type
If the type of the property is anything other than Edm.String, the property representation MUST contain a metadata:type attribute to specify the namespace- or alias-qualified type of the property. If the type is defined in a different metadata document than specified by the current metadata URL, it MUST be a full URL to a metadata document with the namespace- or alias-qualified name of the instances type appended as a URL fragment.
For example, the following specifies that the Age property is a 32-bit integer with the value 25:
25
Navigation Property
A navigation property represents a reference from a source entity to zero or more related entities.
Navigation Link
The navigation link is a URL that allows retrieving the related entity or collection of entities, It is represented as an atom:link element.
Example for products related to a category:
The related data for the relationship MAY be included in the entity using a single child HYPERLINK \l "metadataInline" metadata:inline element.
Element atom:link
In the case where the atom:link element describes a navigation link the attributes rel, href, type, metadata:metadata, and title are to be used as described in the following subsections.
Attribute rel
The rel attribute MUST be present and is made up of the string http://docs.oasis-open.org/odata/ns/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.
Attribute href
The href attribute MUST be present and specifies the URL that can be used to retrieve the related entities. This URL may be relative or absolute.
Attribute type
The type attribute MUST be present and determines whether the cardinality of the related end is a single entity or a collection of entities. The value "application/atom+xml;type=entry" represents a single entity and the value "application/atom+xml;type=feed" an collection of entities.
Attribute metadata:metadata
The metadata:metadata Attribute MUST be present if the navigation property is not defined in metadata. The value of the metadata:metadata attribute, defined in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, specifies the metadata URL that describes the type of the related entity or entities
For details on the metadata URL, see [ REF ODataCore \h Error! Reference source not found.].
Attribute title
The title attribute 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.
Association Link
The association link is a URL that allows retrieving the reference or collection of references to the related entity or entities. It is represented as an atom:link element.
Example for products related to a category:
Example for products related to a category:
Element atom:link
A collection of relationship links is represented by an atom:link element. The attributes rel, href, type, metadata:metadata, and title are to be used as described in the following subsections.
Attribute rel
The rel attribute MUST be present. The value MUST be made up of the string "http://docs.oasis-open.org/odata/ns/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.
Attribute href
The href attribute MUST be present and MUST specify the URL that represents the collection of relationship links. This URL may be relative or absolute.
Attribute type
The type attribute MUST be present with the string "application/xml" as value.
Attribute title
The title attribute SHOULD be present and 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.
Expanded Navigation Property
An expanded navigation property MUST be represented as a single metadata:inline child element of the atom:link element representing the HYPERLINK \l "_Navigation_Link_1" navigation link. The value of the metadata:inline element MUST be the correct representation of the related entity or collection of entities.
It is valid to include the metadata:inline element in only a subset of the entries within a feed.
If at most one entity can be related, the value is the representation of the related entity, or the metadata:inline element is empty if no entity is currently related.
If a collection of entities can be related, it MUST be represented as an HYPERLINK \l "_Collection_of_Entities_1" atom:feed. An empty set of entities (one that contains no entity type instances) MUST be represented as an empty atom:feed.
Each entity MUST be HYPERLINK \l "_Representing_an_Entity_1" represented as an atom:entry element or as HYPERLINK \l "_Resource_Reference" an entity reference.
Example:
...
Deep Inserts
When inserting a new entity with a POST request, related new entities MAY be specified using the same representation as for an HYPERLINK \l "_Expanded_Navigation_Property_1" expanded navigation property.
Deep inserts are not allowed in update operations using PUT or PATCH requests.
Example for inserting a new order with order details and a new customer:
...
...
ANEWONE
...
...
28
...
...
39
...
...
11643
ANEWONE6
...
Bind Operations
When inserting or updating an entity, relationships of navigation properties MAY be inserted or updated via bind operations.
If at most one entity can be related, the bind operation MUST be represented as a navigation link whose href attribute MUST contain the HYPERLINK \l "_Element_atom:id" id of the entity to be related.
For update operations a bind operation on a collection navigation property MUST be represented as a navigation link with an inlined collection of entity references. The referenced entities are added as additional related entities, and existing relationships are not updated or deleted.
For insert operations collection navigation property bind operations and deep insert operations MAY be combined by inlining an atom:feed that contains atom:entry elements and metadata:ref elements.
Example for assigning a product to an existing category with an update request:
Stream Property
Element atom:link
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 the atom:link element to represent a named stream property of an entity.
For example, a stream property named Photo could be represented by 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:
The attributes rel, href, type, metadata:etag, and title are to be used as described in the following subsections.
Attribute rel
The rel attribute MUST be present and MUST be made up of the string http://docs.oasis-open.org/odata/ns/mediaresource/, followed by the name of the stream property on the entity.
The rel attribute for an HYPERLINK \l "atomLink" atom:link element that can be used to change a stream property value is made up of the string http://docs.oasis-open.org/odata/ns/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.
Attribute href
The href attribute MUST be present and MUST contain the URL that can be used to read, or write, the stream, according to the rel attribute. This URL may be relative or absolute.
Attribute type
The type attribute specifies the meda-type of the stream property.
Attribute metadata:etag
The metadata:etag attribute specifies an etag value that can be used in an if-match header to conditionally write to the stream property as described in [ REF ODataCore \h Error! Reference source not found.].
Attribute title
The title attribute provides human-readable, possibly language-dependent, and not necessarily unique information about the link. It has no implied semantics in OData.
Media Entity
Media entities (in AtomPub: media link entries, see REF RFC5023 \h [RFC5023]) are entities that describe and link to a media resource.
http://host/service/Employees(6)
...
6
...
Element atom:link
A media entity 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. The attributes rel and href MUST be used as described in the following subsections.
Attribute rel
The rel attribute MUST be present and MUST have the string edit-media as value.
Attribute href
The href MUST be present and its value MUST specify the URI that can be used to write the stream. This URI may be relative or absolute.
Element atom:content
For media entities the atom:content element MUST be empty. Properties of the media entity are represented by the HYPERLINK \l "metadataProperties" metadata:properties element as a sibling to, rather than a child of, the atom:content element.
Attribute src
The atom:content element MUST contain a src attribute and the value of the src attribute MUST be a URL that can be used to retrieve the content of the media resource.
Attribute type
The atom:content element MUST specify a type attribute that SHOULD contain the MIME type of the media resource.
Individual Property
A valid OData payload may consist of a single HYPERLINK \l "SimpleTypedProperties" primitive or HYPERLINK \l "ComplexTypedProperties" complex value, or of a collection of these.
Single Scalar Value
For example, a request for the first name of a given customer may return the following payloads:
CEO
or
Similarly, the following payload represents a full name:
JulieSwansworth
Element metadata:value
Single scalar values are represented as a metadata:value root element that contains the representation of the scalar value. The attributes metadata:type and metadata:null MUST be used as described in the following subsections.
Attribute metadata:metadata
The metadata:value element MUST have a metadata attribute, defined in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, whose value is the metadata URL that describes the element.
For more information on the metadata URL, see [ REF ODataCore \h Error! Reference source not found.].
Attribute metadata:metadata-etag
The metadata:value element MAY have a metadata:metadata-etag attribute to specify an ETag that can be used to determine the current version of the service's metadata document.
For details on how ETags are used, see [ REF OData \h Error! Reference source not found.].
Attribute metadata:type
If the type of the scalar value being specified is anything other than Edm.String the metadata:type attribute MUST be present and specify the namespace - or alias - qualified type of the value.
Attribute metadata:null
The metadata:null attribute distinguishes null values from other empty content (such as an empty string).
Null-values are represented as an empty metadata:value element with a metadata:null="true" attribute.
Collection of Scalar Values
A valid OData payload MAY consist of a collection of primitive or complex properties.
For example, the following payload represents a collection of phone numbers.
(203)555-1718(203)555-1719
Similarly, the following payload represents a collection of full names.
JulieSwansworthMarkSwansworth
Element metadata:value
A Collection of scalar values is represented as a single metadata:value root element that contains a child element for each member of the collection whose content is an individual HYPERLINK \l "SimpleTypedProperties" primitive or HYPERLINK \l "ComplexTypedProperties" complex value as defined above.
The element MUST NOT contain a metadata:null attribute. The attribute metadata:type MUST be used as described in the following subsection.
Attribute metadata:type
The attribute metadata:type MUST be present and specify the namespace- or alias-qualified collection type.
For collections of complex scalar values this attribute specifies a collection type for the base type of the collection. Individual elements of a derived type MUST specify their derived types with a metadata:type attribute on the element.
Collection of Entities
Collections of entities are represented in Atom as an Atom Feed.
Element atom:feed
Collections of entities are represented using an atom:feed Element, where each entity is represented as an HYPERLINK \l "atomEntry" atom:entry or HYPERLINK \l "_Entity_References_as" metadata:ref.
Attribute metadata:metadata
The atom:feed element, it MUST have a metadata attribute, defined in the HYPERLINK \l "_OData_Metadata_Namespace" OData Metadata namespace, whose value is the metadata URL that describes the feed.
For more information on the metadata URL, see [ REF ODataCore \h Error! Reference source not found.].
Attribute metadata:metadata-etag
The metadata:metadata-etag attribute MAY appear in an atom:feed in order to specify an ETag that can be used to determine the current version of the service's metadata document.
For details on how ETags are used, see [ REF OData \h Error! Reference source not found.].
Element atom:id
OData does not add any conventions or semantics beyond REF RFC4287 \h [RFC4287] to the atom:id element for feeds.
Element metadata:count
The atom:feed element MAY contain a metadata:count element to specify the total count of rows in the result. This MAY be greater than the number of rows in the feed if server side paging has been applied, in which case the feed MUST include a HYPERLINK \l "AdditionalResultsAsAnAtomLink" next results link:
42
...
Element atom:link
Atom requires that feeds contain a self link. The atom:feed element MAY contain a next link to indicate the presence of additional entries that belong to the feed. The atom:feed element representing the final page of results may contain a delta link that can be used to fetch subsequent changes (deltas) to the result.
All three cases are distinguished from another by the value of the rel attribute as described in the following subsection.
Note that the actual set of entries contained within the atom:feed MAY be a subset of those retrieved using the self link, for example, if filtering has been applied.
Attribute rel
A self link is represented as an atom:link with a rel="self" attribute and an href that can be used to retrieve the feed from which the current entries are taken. If the feed represents a set of related entities (addressed with a request URL ending in a to-many navigation property, or an inlined feed requested with $expand), the self link MUST identify the specific feed of related entities.
A self link is represented as an atom:link with a rel="self" attribute and an href that can be used to retrieve the feed from which the current entries are taken. If the feed represents a set of related entities (addressed with a request URL ending in a to-many navigation property, or an inlined feed requested with $expand), the self link MUST identify the specific feed of related entities.
A next link is represented as an atom:link with a rel="next" attribute and an href attribute containing a URL that can be used to retrieve the next set of results.
For example, the following atom:link element within an atom:feed element indicates that additional results can be returned by following the specified href:
The contents of the href SHOULD be treated as an opaque URL that can be used to fetch the next set of results.
A delta link is represented as an atom:link element with a rel attribute of " http://docs.oasis-open.org/odata/ns/delta" and an href attribute containing a URL that can be used to retrieve subsequent changes.
A delta link is represented as an atom:link element with a rel attribute of " http://docs.oasis-open.org/odata/ns/delta" and an href attribute containing a URL that can be used to retrieve subsequent changes.
For example, the following atom:link element within an atom:feed element indicates that changes may be retrieved by following the specified href:
The contents of the href should be treated as an opaque URL that can be used to fetch subsequent changes.
The delta link MUST only appear on the last page of results. A page of results MUST NOT have both a delta link and a HYPERLINK \l "_Additional_Results_as" next link.
Resource Reference
A resource reference is a reference to an entity or a property of an entity. A resource reference referring to an entity is called an entity reference.
An entity reference MAY take the place of an HYPERLINK \l "_Entity_Instances" entity instance in an Atom payload, based on the client request.
For example, the following shows an entity reference to order 10643:
Element metadata:ref
A reference to an entity or one of its properties is represented in Atom using a metadata:ref element. The ref attribute MUST be present and used as described in the following subsection.
Attribute ref
The ref attribute MUST be present. For entities the ref attribute MUST be the HYPERLINK \l "_The_atom:id_Element" atom:id of the referenced entity, for entity properties it MUST be the HYPERLINK \l "_The_atom:id_Element" atom:id of the entity followed by the resource path segment identifying the property.
Delta Response
Responses from a delta request are returned as an HYPERLINK \l "_Collection_of_Entities" atom:feed. The feed MUST contain all HYPERLINK \l "_Changed/Added_Entities_as" added, HYPERLINK \l "_Changed/Added_Entities_as" changed, or HYPERLINK \l "_Deleted_entities_as_1" deleted entities, as well as HYPERLINK \l "_Links_as_metadata:linkEntry" added or HYPERLINK \l "_Deleted_Links_as" deleted links between entities, and MAY contain additional, unchanged entities.
All added, changed, or deleted entities and links, including related entities, are returned as direct children of the HYPERLINK \l "_Collection_of_Entities" atom:feed element.
Entities that are not part of the set specified by the value of metadata:metadata MUST include the HYPERLINK \l "_The_metadata:set_Attribute" metadata:metadata attribute in the atom:id element to specify the set of the related entity.
If the delta response contains a partial list of changes, it MUST include a HYPERLINK \l "_Additional_Results_as" next link for the client to retrieve the next set of changes.
If the delta response contains a partial list of changes, it MUST include a HYPERLINK \l "_Additional_Results_as" next link for the client to retrieve the next set of changes.
Changes are generally ordered by the service according to when the last change occurred to an entity, but MUST be ordered such that applying all changes across all pages, in order, to the initial set yields a consistent result.
The last page of a delta response SHOULD contain a HYPERLINK \l "_Delta_Link_as" delta link for retrieving subsequent changes once the current set of changes has been applied to the initial set.
If the response from the delta link contains an HYPERLINK \l "_Count_as_a" inlinecount, the returned count is the count of added, changed, or deleted entities. $count and $inlinecount returned from a delta link do not include added or deleted links.
The following example shows the following ordered changes:
ContactName for customer 'BOTTM' was changed to "Susan Halvenstern"
Order 10643 was removed from customer 'ALFKI'
Order 10645 was added to customer 'BOTTM'
The shipping information for order 10643 was updated
Customer 'ANTON' was deleted
Customershttp://DeltaService.svc/Customers2011-02-16T01:00:25Zhttp://DeltaService/Customers('BOTTM')2011-02-16T01:00:25ZSusan Halvensternhttp://DeltaService/Orders('10643')2011-02-16T01:00:25ZBottom-Dollar Markets23 Tsawassen Blvd.TsawassenBCT2F 8M4Canada
Added/Changed Entity
Added or changed entities within a delta response are represented as HYPERLINK \l "_The_atom:entry_Element" atom:entry elements.
Added or changed entities MUST NOT include HYPERLINK \l "_Inline_Content_within" inline content.
Added entities MUST include all selected properties and MAY include additional, unselected properties. Collection-valued properties are treated as atomic values; any collection-valued properties returned from a delta request MUST contain all current values for that collection.
Added entities MUST include HYPERLINK \l "_Relationships_as_atom:link" navigation links.
Changed entities MUST include all selected properties that have changed and MAY include additional properties.
Entities whose set cannot be determined from the metadata URL of the feed MUST include the HYPERLINK \l "_Attribute_metadata:metadata" metadata:metadata attribute in the atom:entry element to specify the metadata URL of the entity (in this metadata URL specifies the set, the entity belongs to). This metadata URL MAY be absolute or relative to the metadata URL of the feed.
Deleted Entity
Element atom-tombstone:deleted-entry
A deleted entitiy within a delta response is represented as an atom-tombstone:deleted-entry element, defined within the HYPERLINK \l "_Atom_Tombstone_Namespace" Atom Tombstone namespace, as defined in HYPERLINK \l "RFC6721" [RFC6721].
The ref and a when attribute MUST be present, the metadata:reason attribute MAY be present. All attributes have to be used as described in the following subsection.
Attribute ref
As defined in HYPERLINK \l "RFC6721" [RFC6721], the ref attribute MUST be present. The value of the ref attribute MUST specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the deleted entry.
Attribute when
As defined in HYPERLINK \l "RFC6721" [RFC6721], the when attribute MUST be present The value of the when attribute MUST specify the time at which the entity was deleted. The value may be the empty string if the service is unable to determine the time at which the deletion occurred.
Attribute metadata:reason
The metadata:reason attribute MAY be present. The value of the metadata:reason attribute MUST specify the string value "deleted", if the entity was deleted (destroyed), or "changed" if the entity was removed from membership in the result (i.e., due to a data change).
Link
Element metadata:link-entry
A Link within a delta response is represented by a metadata:link-entry element.
A Delta Response MUST contain a metadata:link-entry for each added link that corresponds to a $expand path in the initial request.
The HYPERLINK \l "_Entity_Id_as" source, HYPERLINK \l "_Navigation_Property_as" relationship, and HYPERLINK \l "_Entity_Id_as_1" target attribute MUST be present, the when attribute MAY be present. All attributes have to be used as described in the following subsection.
Attribute source
The source attribute MUST be present and specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the entity from which the link originates.
Attribute relationship
The relationship MUST be present and specify the name of the navigation property on the HYPERLINK \l "_Entity_Id_as" source entity for which the link exists.
Attribute target
The target attribute MUST be present and specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the related entity.
Attribute when
The when attribute MAY be present and specify the time at which the link was created. The attribute MAY be the empty string if the service is unable to determine the time at which the creation occurred.
Deleted Link
Element metadata:deleted-link-entry
A Deleted Link within a delta response is represented as a metadata:deleted-link-entry element.
Delta responses MUST contain a metadata:deleted-link-entry for each deleted link that corresponds to a $expand path in the initial request, unless either of the following is true:
The source or target entity has been deleted
The maximum cardinality of the related entity is one and there is a subsequent HYPERLINK \l "_Links_as_metadata:linkEntry" metadata:link-entry that specifies the same source and relationship.
The service MAY return a metadata:deleted-link-entry where one of the entitites has also been deleted, or where there is a subsequent HYPERLINK \l "_Links_as_metadata:linkEntry" metadata:link-entry with the same source and relationship and a maximum cardinality of one for the related end.
The HYPERLINK \l "_Entity_Id_as_2" source, HYPERLINK \l "_Navigation_Property_as_1" relationship and HYPERLINK \l "_Related_Entity_as" target attribute MUST be present, the when attribute MAY be present. All attributes have to be used as described in the following subsection.
Attribute source
The source attribute MUST be present and specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the entity from which the link originates.
Attribute relationship
The target attribute MUST be present and specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the related entity.
Attribute target
The target attribute MUST be present and specify the HYPERLINK \l "_The_atom:id_Element" atom:id of the related entity.
Attribute when
The when attribute MAY be present and specify the time at which the link was created. The attribute MAY be the empty string if the service is unable to determine the time at which the creation occurred
Function
Zero or more functions MAY be bindable to a feed or entry.
The functions associated with a particular feed or entry MAY be described using metadata:function elements that are direct children of the feed or entry to which the functions can be bound.
Example:
Element metadata:function
Each function is represented as a metadata:function element that MUST be a child of the atom:feed or atom:entry element representing the collection or entity on which the function exists.
Attribute metadata
The metadata attribute MUST be present and specify the namespace- or alias-qualified name of the function, preceded by a #.
A function may have multiple overloads with different parameters. If the URL in the HYPERLINK \l "_Attribute_target" target attribute of the metadata:function element cannot be used to invoke all overloads for the function, then it MUST further be distinguished by appending a comma-separated ordered list of parameter type names, enclosed in parenthesis. For example, #Schema.Function(Schema.Product,Edm.String).
Example:
Attribute target
The target attribute MUST be present and specify the URL to GET from in order to invoke the function.
The first parameter of the function MUST be a binding parameter that is bound to the feed or entity on which the function is specified, and MUST NOT be provided as a separate parameter by the client when invoking the function.
Attribute title
The title attribute MUST be present and contain a human-readable, possibly language-dependent, and not necessarily unique name for the function, commonly used by clients to describe the function to a user.
Action
Zero or more actions may be bindable to a feed or entry.
The actions associated with a particular feed or entry MAY be described using metadata:action elements that are direct children of the feed or entry to which the actions can be bound.
Example:
Element metadata:action
Each action is represented as a metadata:action element that MUST be a direct child of the atom:feed or atom:entry element representing the feed or entity on which the action exists.
Attribute metadata
The metadata attribute MUST be present and specify the namespace- or alias-qualified name of the action element describing the action, preceded by a #.
This function element name combined with the binding parameter type MUST be unique within the entity container.
Attribute target
The target attribute MUST be present and specify the URL to POST to in order to invoke the action.
The target attribute MUST be present and specify the URL to POST to in order to invoke the action.
The first parameter of the action MUST be a binding parameter that is bound to the feed or entity on which the action is specified, and MUST NOT be provided as a separate parameter by the client when invoking the action.
Attribute title
The title attribute MUST be present and contain a human-readable, possibly language-dependent, and not necessarily unique name for the action, commonly used by clients to describe the action to a user.
Action Parameters
Action parameter values in the request body MUST be encoded as an HYPERLINK \l "_Individual_Primitive_or" individual complex scalar value with the name parameters and no metadata:type attribute for the parameters element.
Each non-binding parameter value specified MUST be encoded as an individual primitive or complex scalar value. The name of the scalar value is the name of the parameter. The value is the parameter value in the XML representation appropriate for its type.
Any parameter values not specified in the request body MUST be assumed to have the default value specified in the service metadata, see REF ODataCSDL \h [OData-CSDL].
Example:
42One Microsoft Way9805214299
Instance Annotations
Annotations MAY be applied to an instance of a HYPERLINK \l "_Collections_of_Entities" feed, HYPERLINK \l "_Entity_Instances" entity, HYPERLINK \l "_Entity_Properties_within" property, HYPERLINK \l "_Toc341794897" complex scalar value, HYPERLINK \l "_Functions" function, HYPERLINK \l "_Actions" action, or HYPERLINK \l "_Errors_as_XML" error within an Atom payload.
Element metadata:annotation
An instance annotation in Atom is represented as an XML element with the name Annotation in the HYPERLINK \l "_OData_Metadata_Namespace" metadata namespace.
The value of the annotation is specified according to the HYPERLINK \l "_Annotation_Value" Annotation Value, described below.
Attribute target
The target attribute MAY be used to specify the annotation target. If the target attribute is not specified the target of the annotation is the element represented by the direct parent of the HYPERLINK \l "_The_metadata:Annotation_Element" metadata:annotation element.
Attribute term
The HYPERLINK \l "_The_metadata:Annotation_Element" metadata:annotation element MUST have a term attribute that specifies the namespace- or alias-qualified name of the term being applied.
Attribute metadata:type
If the type of the annotation value being specified is anything other than Edm.String the HYPERLINK \l "_The_metadata:Annotation_Element" metadata:annotation element MUST contain a metadata:type attribute to specify the appropriate type of the annotation value.
Attribute metadata:null
Null-valued annotations are represented as empty metadata:annotation elements with the metadata:null="true" attribute.
The metadata:null attribute distinguishes null values from other empty content (such as an empty string).
The absence of the metadata:null attribute is equivalent to specifying metadata:null="false".
Annotation Values
An instance annotation value may be specified as a HYPERLINK \l "_Primitive_Values" primitive value, HYPERLINK \l "_Structure_Annotations" structured value, or HYPERLINK \l "_Collection_Values_1" collection value.
Primitive Values
When specified in the content of an annotation element representing a primitive value, the content MUST be formatted as per HYPERLINK \l "_Primitive_Types_in" Primitive Types in Atom. If the type of the annotation value is anything other than Edm.String, then the annotation element MUST contain the HYPERLINK \l "_The_type_attribute" metadata:type attribute specifying the appropriate primitive type.
For example; the following annotates the "Phone" property with a string value of "Home" for the PhoneNumberType annotation term.
ALFKI Alfreds Futterkiste 030-0074321Home
Collection Values
The content of an element representing a collection-valued annotation MUST be the individual elements of that collection formatted as direct child elements of the HYPERLINK \l "_The_metadata:Annotation_Element" metadata:annotation element as described in HYPERLINK \l "_Collections_of_Primitive" Collections of Primitive or Complex Scalar Values.
For collection-valued annotations, the annotation element MUST contain the HYPERLINK \l "_The_type_attribute" metadata:type attribute specifying the appropriate collection type.
For example, the following annotates the customer instance with two phone numbers.
Customers(ALFKI)ALFKIAlfreds Futterkiste030-0074321(203)555-1718(203)555-1719
Structure Annotations
The content of an element representing a structured annotation MUST be a single child element for each property of the annotation type being specified, formatted as per HYPERLINK \l "_Entity_Properties_within" properties within an entity type.
For structural-valued annotations, the annotation element MUST contain the HYPERLINK \l "_The_type_attribute" metadata:type attribute specifying the appropriate structural type.
For example; the following specifies the StreetAddress, City, Region, Country and PostalCode properties of an Address annotation applied to a customer entity:
Customers(ALFKI)ALFKIAlfreds Futterkiste030-0074321Obere Str. 578Toronto12209Germany
Instance Annotation Targets
Instance annotations may target model elements represented by a HYPERLINK \l "_Collections_of_Entities" feed, HYPERLINK \l "_Entity_Instances" entity, HYPERLINK \l "_Entity_Content_within" complex scalar value, HYPERLINK \l "_Entity_Properties_within" property, HYPERLINK \l "_Functions" function, HYPERLINK \l "_Actions" action, or HYPERLINK \l "_Errors_as_XML" error element in an Atom payload.
Feed
When annotating a feed, annotation elements MUST be direct children of the HYPERLINK \l "_Collections_of_Entities" atom:feed element, and they MUST appear in a group at the beginning of the feed or (another) group at the end of the feed, depending on whether they are needed beforehand to understand the feed content, or can only be computed after serializing the feed content.
Entry
When annotating an entity, the annotation element MUST be a direct child of the HYPERLINK \l "_Entity_Instances" atom:entry element representing the entity.
Complex Type
When annotating an instance of a complex type, the annotation element MUST be a direct child of the HYPERLINK \l "_Entity_Instances" metadata:value element representing the complex-typed value.
Property
When annotating a property, the annotation element MUST be a direct child of the HYPERLINK "file:///C:\\Users\\d037427\\Downloads\\Instance%20Annotations%20in%20Atom%20(1).docx" \l "_Entity_Properties_within" metadata:properties element, or a direct child of the element representing a HYPERLINK \l "_Complex_Typed_Properties" complex type in the case of annotating the property of a complex type. The value of the HYPERLINK \l "_The_Target_Attribute_1" target attribute MUST specify the name of the property being annotated. The annotation elements MUST immediately precede the target property element.
Instance annotations are not supported when serializing single primitive properties in XML as described in HYPERLINK \l "_Individual_Primitive_or" Individual Primitive or Complex Scalar Values HYPERLINK "file:///C:\\Users\\d037427\\Downloads\\Instance%20Annotations%20in%20Atom%20(1).docx" \l "z174ab0b818ff4c6a9131aa62331e8133" .
Navigation Property
When annotating a navigation property, named stream, or other element represented by an HYPERLINK \l "_Relationship_Links_as" atom:link element, the annotation element must be a direct child of the atom:link element.
Function or Action
When annotating a function or action, the annotation element must be a direct child of the element representing the function or action.
Error
When annotating an HYPERLINK \l "_Errors_as_XML" error, the HYPERLINK \l "_The_metadata:Annotation_Element" metadata:annotation element MUST be a direct child of the HYPERLINK \l "_The_metadata:error_Element" metadata:error element. The annotation element MAY have a HYPERLINK \l "_The_Target_Attribute_1" target attribute value of " HYPERLINK \l "_The_metadata:code_Element" code", " HYPERLINK \l "_The_metadata:message_Element" message", or " HYPERLINK \l "_The_metadata:innererror_Element" innererror". If the target attribute is not specified, then the annotation is applied to the error itself. The annotation elements MUST follow the other child elements of the error element.
Error Reponse
In the case of an error being generated in response to a request specifying an Accept header of application/xml or application/atom+xml, or that does not specify an Accept header, the service MUST respond with an error formatted as XML.
When formatting error responses as XML, servers SHOULD include a Content-Type response header with the value "application/xml".
Element metadata:error
Errors formatted as XML MUST have a root metadata:error element. The metadata:error element MUST have at least two child elements: HYPERLINK \l "metadataCode" metadata:code and HYPERLINK \l "metadataMessage" metadata:message.
In addition, errors may be annotated using custom HYPERLINK \l "Annotations" annotations.
For example:
501Functionality not supported.301$search query option not supported.$search
Element metadata:code
The metadata:error element MUST contain one metadata:code element specifying a service-defined string. This value MAY be used to provide a more specific substatus to the returned HTTP response code.
Element metadata:message
The metadata:error element MUST contain a metadata:message element specifying a human readable, language-dependent message describing the error. The Content-Language header MUST contain the language code from REF rfc5646 \h [RFC5646] corresponding to the language in which the value for message is written.
Element metadata:target
The metadata:error element MAY contain a metadata:target element to specify the target of the error (for example, the name of the property in error).
Element metadata:details
The metadata:error element MAY contain a metadata:details element containing one or more metadata:detail elements specifying detail about the error.
Element metadata:detail
The metadata:detail element specifies information about an individual error detail.
Element metadata:code
The metadata:detail element MUST contain one metadata:code element specifying a service-defined string. This value MAY be used to provide a more specific substatus to the returned HTTP response code.
Element metadata:message
The metadata:detail element MUST contain a metadata:message element specifying a human readable, language-dependent message describing the error.
Element metadata:target
The metadata:detail element MAY contain a metadata:detail element to specify the target of the error.
Element metadata:innererror
The metadata:error element MAY contain a metadata:innererror element containing service specific debugging information that might assist a service implementer in determining the cause of an error.
The metadata:innererror element SHOULD only be used in development environments in order to guard against potential security concerns around information disclosure.
Extensibility
Implementations MAY add custom content anywhere allowed by REF RFC4287 \h \* MERGEFORMAT [RFC4287], Section 6, Extending Atom, and REF RFC5023 \h [RFC5023], Section 6.2 Document Extensibility. However, custom elements and attributes MUST NOT be defined in the HYPERLINK \l "ODataDataNamespace" OData Data Namespace nor the HYPERLINK \l "ODataMetadataNamespace" OData Metadata Namespace, and SHOULD not be required to be understood by the receiving party in order to correctly interpret the rest of the payload as the receiving party MUST ignore unknown foreign markup according to REF RFC4287 \h \* MERGEFORMAT [RFC4287].
Conformance
Conforming clients MUST be prepared to consume a service that uses any or all of the constructs defined in this specification. The exception to this are the constructs defined in HYPERLINK \l "_Delta_Response_1" Delta Response, which are only required for clients that request changes
The exception to this are the constructs defined in HYPERLINK \l "_Delta_Response_1" Delta Response, which are only required for clients that request changes.
A conforming OData service MUST comply with one of the conformance levels defined in [ REF ODataCore \h Error! Reference source not found.].
In order to conform to the OData Atom format, a service:
MUST support the application/atom+xml, application/xml and application/atomsvc+xml media types in the HYPERLINK \l "_Requesting_the_Atom" Accept header
SHOULD support the HYPERLINK \l "_Requesting_the_Atom" $format system query option
MUST include the HYPERLINK \l "_Element_atom:link" next link in feeds containing partial results
MUST return HYPERLINK \l "_Toc354440398" service documents as Atom service documents
MUST return XML responses in well formed XML according to this specification
MUST return well-formed Atom payloads with the following exceptions:
The HYPERLINK \l "_Element_atom:link" next link MAY be returned at the end of the payload
The HYPERLINK \l "_Delta_Link_as" delta link MAY be returned at the end of the payload
MUST NOT violate any other aspects of this OData Atom specification
In order to be a conforming consumer of the OData ATOM format, a client or service:
MUST be prepared to receive all data types
defined in this specification defined in HYPERLINK \l "ODataCSDL" [OData-CSDL] (client)
exposed by the service (service)
MUST be prepared to receive custom HYPERLINK \l "_Instance_Annotations" annotations
MUST be prepared to receive additional constructs not defined in this version of the specification
Acknowledgments
The contributions of the OASIS OData Technical Committee members, enumerated in [ HYPERLINK \l "ODataProtocol" OData-Protocol][OData-Protocol], are gratefully acknowledged.
Revision History
RevisionDateEditorChanges MadeWorking Draft 012012-08-22Michael PizzoTranslated Contribution to OASIS format/template
odata-atom-format-v4.0-csd01 26 April 2013
Standards Track Work Product Copyright OASIS Open 2013. All Rights Reserved. Page PAGE 1 of NUMPAGES 48
MACROBUTTON NoMacro [document identifier] MACROBUTTON NoMacro [specification date]
Copyright OASIS Open 2004.All Rights Reserved. Page PAGE 5 of NUMPAGES 48
> @ A I J L M N O \ b g h n p q } < = > M N O [ Ƚxnh_hn hB9 hB9 0J
hB9 0J j hB9 0J Uh7 h1D 0J B* ph hY&