-
Notifications
You must be signed in to change notification settings - Fork 1
/
odata-protocol.html
3004 lines (2951 loc) · 396 KB
/
odata-protocol.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<meta name="description" content="The Open Data Protocol (OData) enables the creation of REST-based data services, which allow resources, identified using Uniform Resource Locators (URLs) and defined in an Entity Data Model (EDM), to be published and edited by Web clients using simple HTTP messages. This document defines the core semantics and facilities of the protocol." />
<title>OData Version 4.02. Part 1: Protocol</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
ul.task-list li input[type="checkbox"] {
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="styles/markdown-styles-v1.7.3b.css" />
<link rel="stylesheet" href="styles/odata.css" />
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js" type="text/javascript"></script>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<p><img src="https://docs.oasis-open.org/templates/OASISLogo-v3.0.png" alt="OASIS Logo" /></p>
<hr />
<h1 id="odata-version-402-part-1-protocol">OData Version 4.02. Part 1: Protocol</h1>
<h2 id="committee-specification-draft-01">Committee Specification Draft 01</h2>
<h2 id="14-july-2023">14 July 2023</h2>
<p><span class="math inline">\(\hbox{}\)</span></p>
<h4 id="this-stage">This stage:</h4>
<p><a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.md">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.md</a> (Authoritative)<br />
<a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html</a><br />
<a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.pdf">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.pdf</a></p>
<h4 id="previous-stage">Previous stage:</h4>
<p>N/A</p>
<h4 id="latest-stage">Latest stage:</h4>
<p><a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.md">https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.md</a> (Authoritative)<br />
<a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html</a><br />
<a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.pdf">https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.pdf</a></p>
<h4 id="technical-committee">Technical Committee:</h4>
<p><a href="https://www.oasis-open.org/committees/odata/">OASIS Open Data Protocol (OData) TC</a></p>
<h4 id="chairs">Chairs:</h4>
<p>Ralf Handl (<a href="mailto:ralf.handl@sap.com">ralf.handl@sap.com</a>), <a href="http://www.sap.com/">SAP SE</a><br />
Michael Pizzo (<a href="mailto:mikep@microsoft.com">mikep@microsoft.com</a>), <a href="http://www.microsoft.com/">Microsoft</a></p>
<h4 id="editors">Editors:</h4>
<p>Michael Pizzo (<a href="mailto:mikep@microsoft.com">mikep@microsoft.com</a>), <a href="http://www.microsoft.com/">Microsoft</a><br />
Ralf Handl (<a href="mailto:ralf.handl@sap.com">ralf.handl@sap.com</a>), <a href="http://www.sap.com/">SAP SE</a><br />
Heiko Theißen (<a href="mailto:heiko.theissen@sap.com">heiko.theissen@sap.com</a>), <a href="http://www.sap.com/">SAP SE</a></p>
<h4 id="additional-artifacts">Additional artifacts:</h4>
<p>This prose specification is one component of a Work Product that also includes:</p>
<ul>
<li><em>OData Version 4.02 Part 1: Protocol</em> (this document). <a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html</a></li>
<li><em>OData Version 4.02 Part 2: URL Conventions</em>. <a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part2-url-conventions.html">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part2-url-conventions.html</a></li>
</ul>
<h4 id="related-work"><a name="RelatedWork">Related work:</a></h4>
<p>This specification replaces or supersedes:</p>
<ul>
<li><em>OData Version 4.01. Part 1: Protocol</em>. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. OASIS Standard. Latest stage: <a href="https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html</a></li>
<li><em>OData Version 4.0. Part 1: Protocol</em>. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. OASIS Standard. Latest stage: <a href="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</a></li>
</ul>
<p>This specification is related to:</p>
<ul>
<li><em>OData Vocabularies Version 4.0</em>. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html">https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html</a></li>
<li><em>OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02</em>. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html">https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html</a></li>
<li><em>OData Common Schema Definition Language (CSDL) XML Representation Version 4.02</em>. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html">https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html</a></li>
<li><em>OData JSON Format Version 4.02</em>. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html">https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html</a></li>
<li><em>OData Data Aggregation Extension Version 4.0</em>. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, Heiko Theißen, and Martin Zurmuehl. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html">https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html</a></li>
<li><em>OData Extension for Temporal Data Version 4.0</em>. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, Heiko Theißen, and Martin Zurmuehl. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.html">https://docs.oasis-open.org/odata/odata-temporal-ext/v4.0/odata-temporal-ext-v4.0.html</a></li>
</ul>
<h4 id="abstract">Abstract:</h4>
<p>The Open Data Protocol (OData) enables the creation of REST-based data services, which allow resources, identified using Uniform Resource Locators (URLs) and defined in an Entity Data Model (EDM), to be published and edited by Web clients using simple HTTP messages. This document defines the core semantics and facilities of the protocol.</p>
<h4 id="status">Status:</h4>
<p>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 stage" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at <a href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical">https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical</a>.</p>
<p>TC members should send comments on this specification to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "<a href="https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=odata">Send A Comment</a>" button on the TC's web page at <a href="https://www.oasis-open.org/committees/odata/">https://www.oasis-open.org/committees/odata/</a>.</p>
<p>This specification is provided under the <a href="https://www.oasis-open.org/policies-guidelines/ipr/#RF-on-RAND-Mode">RF on RAND Terms Mode</a> of the <a href="https://www.oasis-open.org/policies-guidelines/ipr/">OASIS IPR Policy</a>, the mode chosen when the Technical Committee was established. 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 TC's web page (<a href="https://www.oasis-open.org/committees/odata/ipr.php">https://www.oasis-open.org/committees/odata/ipr.php</a>).</p>
<p>Note that any machine-readable content (<a href="https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26/#wpComponentsCompLang">Computer Language Definitions</a>) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.</p>
<h4 id="key-words">Key words:</h4>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 <a href="#rfc2119">RFC2119</a> and <a href="#rfc8174">RFC8174</a> when, and only when, they appear in all capitals, as shown here.</p>
<h4 id="citation-format">Citation format:</h4>
<p>When referencing this specification the following citation format should be used:</p>
<p><strong>[OData-v4.02-Part1]</strong></p>
<p><em>OData Version 4.02. Part 1: Protocol</em>. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. 14 July 2023. OASIS Committee Specification Draft 01. <a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.02/csd01/odata-v4.02-csd01-part1-protocol.html</a>. Latest stage: <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html">https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html</a>.</p>
<h4 id="notices">Notices</h4>
<p>Copyright © OASIS Open 2023. All Rights Reserved.</p>
<p>Distributed under the terms of the OASIS <a href="https://www.oasis-open.org/policies-guidelines/ipr/">IPR Policy</a>.</p>
<p>The name "OASIS" is a trademark of <a href="https://www.oasis-open.org/">OASIS</a>, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.</p>
<p>For complete copyright information please see the full Notices section in an Appendix below.</p>
<hr />
<h1 id="table-of-contents">Table of Contents</h1>
<div class="toc">
<ul>
<li><a href="#Introduction">1 Introduction</a>
<ul>
<li><a href="#ChangesfromEarlierVersions">1.1 Changes from Earlier Versions</a></li>
<li><a href="#Glossary">1.2 Glossary</a>
<ul>
<li><a href="#DefinitionsofTerms">1.2.1 Definitions of Terms</a></li>
<li><a href="#AcronymsandAbbreviations">1.2.2 Acronyms and Abbreviations</a></li>
<li><a href="#DocumentConventions">1.2.3 Document Conventions</a></li>
</ul></li>
</ul></li>
<li><a href="#Overview">2 Overview</a></li>
<li><a href="#DataModel">3 Data Model</a>
<ul>
<li><a href="#Annotations">3.1 Annotations</a></li>
</ul></li>
<li><a href="#ServiceModel">4 Service Model</a>
<ul>
<li><a href="#EntityIdsandEntityReferences">4.1 Entity-Ids and Entity References</a></li>
<li><a href="#ReadURLsandEditURLs">4.2 Read URLs and Edit URLs</a></li>
<li><a href="#TransientEntities">4.3 Transient Entities</a></li>
<li><a href="#DefaultNamespaces">4.4 Default Namespaces</a></li>
</ul></li>
<li><a href="#Versioning">5 Versioning</a>
<ul>
<li><a href="#ProtocolVersioning">5.1 Protocol Versioning</a></li>
<li><a href="#ModelVersioning">5.2 Model Versioning</a></li>
</ul></li>
<li><a href="#Extensibility">6 Extensibility</a>
<ul>
<li><a href="#QueryOptionExtensibility">6.1 Query Option Extensibility</a></li>
<li><a href="#PayloadExtensibility">6.2 Payload Extensibility</a></li>
<li><a href="#ActionFunctionExtensibility">6.3 Action/Function Extensibility</a></li>
<li><a href="#VocabularyExtensibility">6.4 Vocabulary Extensibility</a></li>
<li><a href="#HeaderFieldExtensibility">6.5 Header Field Extensibility</a></li>
<li><a href="#FormatExtensibility">6.6 Format Extensibility</a></li>
</ul></li>
<li><a href="#Formats">7 Formats</a></li>
<li><a href="#HeaderFields">8 Header Fields</a>
<ul>
<li><a href="#CommonHeaders">8.1 Common Headers</a>
<ul>
<li><a href="#HeaderContentType">8.1.1 Header <code>Content-Type</code></a></li>
<li><a href="#HeaderContentEncoding">8.1.2 Header <code>Content-Encoding</code></a></li>
<li><a href="#HeaderContentLanguage">8.1.3 Header <code>Content-Language</code></a></li>
<li><a href="#HeaderContentLength">8.1.4 Header <code>Content-Length</code></a></li>
<li><a href="#HeaderODataVersion">8.1.5 Header <code>OData-Version</code></a></li>
</ul></li>
<li><a href="#RequestHeaders">8.2 Request Headers</a>
<ul>
<li><a href="#HeaderAccept">8.2.1 Header <code>Accept</code></a></li>
<li><a href="#HeaderAcceptCharset">8.2.2 Header <code>Accept-Charset</code></a></li>
<li><a href="#HeaderAcceptLanguage">8.2.3 Header <code>Accept-Language</code></a></li>
<li><a href="#HeaderIfMatch">8.2.4 Header <code>If-Match</code></a></li>
<li><a href="#HeaderIfNoneMatch">8.2.5 Header <code>If-None-Match</code></a></li>
<li><a href="#HeaderIsolationODataIsolation">8.2.6 Header <code>Isolation</code> (<code>OData-Isolation</code>)</a></li>
<li><a href="#HeaderODataMaxVersion">8.2.7 Header <code>OData-MaxVersion</code></a></li>
<li><a href="#HeaderPrefer">8.2.8 Header <code>Prefer</code></a>
<ul>
<li><a href="#Preferenceallowentityreferencesodataallowentityreferences">8.2.8.1 Preference <code>allow-entityreferences</code> (<code>odata.allow-entityreferences</code>)</a></li>
<li><a href="#Preferencecallbackodatacallback">8.2.8.2 Preference <code>callback</code> (<code>odata.callback</code>)</a></li>
<li><a href="#Preferencecontinueonerrorodatacontinueonerror">8.2.8.3 Preference <code>continue-on-error</code> (<code>odata.continue-on-error</code>)</a></li>
<li><a href="#Preferenceincludeannotationsodataincludeannotations">8.2.8.4 Preference <code>include-annotations</code> (<code>odata.include-annotations</code>)</a></li>
<li><a href="#Preferencemaxpagesizeodatamaxpagesize">8.2.8.5 Preference <code>maxpagesize</code> (<code>odata.maxpagesize</code>)</a></li>
<li><a href="#Preferenceomitvalues">8.2.8.6 Preference <code>omit-values</code></a></li>
<li><a href="#Preferencereturnrepresentationandreturnminimal">8.2.8.7 Preference <code>return=representation</code> and <code>return=minimal</code></a></li>
<li><a href="#Preferencerespondasync">8.2.8.8 Preference <code>respond-async</code></a></li>
<li><a href="#Preferencetrackchangesodatatrackchanges">8.2.8.9 Preference <code>track-changes</code> (<code>odata.track-changes</code>)</a></li>
<li><a href="#Preferencewait">8.2.8.10 Preference <code>wait</code></a></li>
</ul></li>
</ul></li>
<li><a href="#ResponseHeaders">8.3 Response Headers</a>
<ul>
<li><a href="#HeaderAsyncResult">8.3.1 Header <code>AsyncResult</code></a></li>
<li><a href="#HeaderETag">8.3.2 Header <code>ETag</code></a></li>
<li><a href="#HeaderLocation">8.3.3 Header <code>Location</code></a></li>
<li><a href="#HeaderODataEntityId">8.3.4 Header <code>OData-EntityId</code></a></li>
<li><a href="#HeaderODataError">8.3.5 Header <code>OData-Error</code></a></li>
<li><a href="#HeaderPreferenceApplied">8.3.6 Header <code>Preference-Applied</code></a></li>
<li><a href="#HeaderRetryAfter">8.3.7 Header <code>Retry-After</code></a></li>
<li><a href="#HeaderVary">8.3.8 Header <code>Vary</code></a></li>
</ul></li>
</ul></li>
<li><a href="#CommonResponseStatusCodes">9 Common Response Status Codes</a>
<ul>
<li><a href="#SuccessResponses">9.1 Success Responses</a>
<ul>
<li><a href="#ResponseCode200OK">9.1.1 Response Code <code>200 OK</code></a></li>
<li><a href="#ResponseCode201Created">9.1.2 Response Code <code>201 Created</code></a></li>
<li><a href="#ResponseCode202Accepted">9.1.3 Response Code <code>202 Accepted</code></a></li>
<li><a href="#ResponseCode204NoContent">9.1.4 Response Code <code>204 No Content</code></a></li>
<li><a href="#ResponseCode3xxRedirection">9.1.5 Response Code <code>3xx Redirection</code></a></li>
<li><a href="#ResponseCode304NotModified">9.1.6 Response Code <code>304 Not Modified</code></a></li>
</ul></li>
<li><a href="#ClientErrorResponses">9.2 Client Error Responses</a>
<ul>
<li><a href="#ResponseCode404NotFound">9.2.1 Response Code <code>404 Not Found</code></a></li>
<li><a href="#ResponseCode405MethodNotAllowed">9.2.2 Response Code <code>405 Method Not Allowed</code></a></li>
<li><a href="#ResponseCode406NotAcceptable">9.2.3 Response Code <code>406 Not Acceptable</code></a></li>
<li><a href="#ResponseCode410Gone">9.2.4 Response Code <code>410 Gone</code></a></li>
<li><a href="#ResponseCode412PreconditionFailed">9.2.5 Response Code <code>412 Precondition Failed</code></a></li>
<li><a href="#ResponseCode424FailedDependency">9.2.6 Response Code <code>424 Failed Dependency</code></a></li>
</ul></li>
<li><a href="#ServerErrorResponses">9.3 Server Error Responses</a>
<ul>
<li><a href="#ResponseCode501NotImplemented">9.3.1 Response Code <code>501 Not Implemented</code></a></li>
</ul></li>
<li><a href="#ErrorResponseBody">9.4 Error Response Body</a></li>
<li><a href="#InStreamErrors">9.5 In-Stream Errors</a></li>
</ul></li>
<li><a href="#ContextURL">10 Context URL</a>
<ul>
<li><a href="#ServiceDocument">10.1 Service Document</a></li>
<li><a href="#CollectionofEntities">10.2 Collection of Entities</a></li>
<li><a href="#Entity">10.3 Entity</a></li>
<li><a href="#Singleton">10.4 Singleton</a></li>
<li><a href="#CollectionofDerivedEntities">10.5 Collection of Derived Entities</a></li>
<li><a href="#DerivedEntity">10.6 Derived Entity</a></li>
<li><a href="#CollectionofProjectedEntities">10.7 Collection of Projected Entities</a></li>
<li><a href="#ProjectedEntity">10.8 Projected Entity</a></li>
<li><a href="#CollectionofExpandedEntities">10.9 Collection of Expanded Entities</a></li>
<li><a href="#ExpandedEntity">10.10 Expanded Entity</a></li>
<li><a href="#CollectionofEntityReferences">10.11 Collection of Entity References</a></li>
<li><a href="#EntityReference">10.12 Entity Reference</a></li>
<li><a href="#PropertyValue">10.13 Property Value</a></li>
<li><a href="#CollectionofComplexorPrimitiveTypes">10.14 Collection of Complex or Primitive Types</a></li>
<li><a href="#ComplexorPrimitiveType">10.15 Complex or Primitive Type</a></li>
<li><a href="#OperationResult">10.16 Operation Result</a></li>
<li><a href="#DeltaPayloadResponse">10.17 Delta Payload Response</a></li>
<li><a href="#IteminaDeltaPayloadResponse">10.18 Item in a Delta Payload Response</a></li>
<li><a href="#allResponse">10.19 <code>$all</code> Response</a></li>
<li><a href="#crossjoinResponse">10.20 <code>$crossjoin</code> Response</a></li>
</ul></li>
<li><a href="#DataServiceRequests">11 Data Service Requests</a>
<ul>
<li><a href="#MetadataRequests">11.1 Metadata Requests</a>
<ul>
<li><a href="#ServiceDocumentRequest">11.1.1 Service Document Request</a></li>
<li><a href="#MetadataDocumentRequest">11.1.2 Metadata Document Request</a></li>
</ul></li>
<li><a href="#RequestingData">11.2 Requesting Data</a>
<ul>
<li><a href="#SystemQueryOptions">11.2.1 System Query Options</a></li>
<li><a href="#RequestingIndividualEntities">11.2.2 Requesting Individual Entities</a></li>
<li><a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">11.2.3 Requesting the Media Stream of a Media Entity using <code>$value</code></a></li>
<li><a href="#RequestingIndividualProperties">11.2.4 Requesting Individual Properties</a>
<ul>
<li><a href="#RequestingaPropertysRawValueusingvalue">11.2.4.1 Requesting a Property's Raw Value using <code>$value</code></a></li>
</ul></li>
<li><a href="#SpecifyingPropertiestoReturn">11.2.5 Specifying Properties to Return</a>
<ul>
<li><a href="#SystemQueryOptionselect">11.2.5.1 System Query Option <code>$select</code></a></li>
<li><a href="#SystemQueryOptionexpand">11.2.5.2 System Query Option <code>$expand</code></a>
<ul>
<li><a href="#ExpandOptions">11.2.5.2.1 Expand Options</a>
<ul>
<li><a href="#ExpandOptionlevels">11.2.5.2.1.1 Expand Option <code>$levels</code></a></li>
</ul></li>
</ul></li>
<li><a href="#SystemQueryOptioncompute">11.2.5.3 System Query Option <code>$compute</code></a></li>
</ul></li>
<li><a href="#QueryingCollections">11.2.6 Querying Collections</a>
<ul>
<li><a href="#SystemQueryOptionfilter">11.2.6.1 System Query Option <code>$filter</code></a>
<ul>
<li><a href="#BuiltinFilterOperations">11.2.6.1.1 Built-in Filter Operations</a></li>
<li><a href="#BuiltinQueryFunctions">11.2.6.1.2 Built-in Query Functions</a></li>
<li><a href="#ParameterAliases">11.2.6.1.3 Parameter Aliases</a></li>
</ul></li>
<li><a href="#SystemQueryOptionorderby">11.2.6.2 System Query Option <code>$orderby</code></a></li>
<li><a href="#SystemQueryOptiontop">11.2.6.3 System Query Option <code>$top</code></a></li>
<li><a href="#SystemQueryOptionskip">11.2.6.4 System Query Option <code>$skip</code></a></li>
<li><a href="#SystemQueryOptioncount">11.2.6.5 System Query Option <code>$count</code></a></li>
<li><a href="#SystemQueryOptionsearch">11.2.6.6 System Query Option <code>$search</code></a></li>
<li><a href="#ServerDrivenPaging">11.2.6.7 Server-Driven Paging</a></li>
<li><a href="#RequestinganIndividualMemberofanOrderedCollection">11.2.6.8 Requesting an Individual Member of an Ordered Collection</a></li>
</ul></li>
<li><a href="#RequestingRelatedEntities">11.2.7 Requesting Related Entities</a></li>
<li><a href="#RequestingEntityReferences">11.2.8 Requesting Entity References</a></li>
<li><a href="#ResolvinganEntityId">11.2.9 Resolving an Entity-Id</a></li>
<li><a href="#RequestingtheNumberofItemsinaCollection">11.2.10 Requesting the Number of Items in a Collection</a></li>
<li><a href="#SystemQueryOptionformat">11.2.11 System Query Option <code>$format</code></a></li>
<li><a href="#SystemQueryOptionschemaversion">11.2.12 System Query Option <code>$schemaversion</code></a></li>
</ul></li>
<li><a href="#RequestingChanges">11.3 Requesting Changes</a>
<ul>
<li><a href="#DeltaLinks">11.3.1 Delta Links</a></li>
<li><a href="#UsingDeltaLinks">11.3.2 Using Delta Links</a></li>
<li><a href="#DeltaPayloads">11.3.3 Delta Payloads</a></li>
</ul></li>
<li><a href="#DataModification">11.4 Data Modification</a>
<ul>
<li><a href="#CommonDataModificationSemantics">11.4.1 Common Data Modification Semantics</a>
<ul>
<li><a href="#UseofETagsforAvoidingUpdateConflicts">11.4.1.1 Use of ETags for Avoiding Update Conflicts</a></li>
<li><a href="#HandlingofDateTimeOffsetValues">11.4.1.2 Handling of DateTimeOffset Values</a></li>
<li><a href="#HandlingofPropertiesNotAdvertisedinMetadata">11.4.1.3 Handling of Properties Not Advertised in Metadata</a></li>
<li><a href="#HandlingofIntegrityConstraints">11.4.1.4 Handling of Integrity Constraints</a></li>
<li><a href="#ReturningResultsfromDataModificationRequests">11.4.1.5 Returning Results from Data Modification Requests</a></li>
</ul></li>
<li><a href="#CreateanEntity">11.4.2 Create an Entity</a>
<ul>
<li><a href="#LinktoRelatedEntitiesWhenCreatinganEntity">11.4.2.1 Link to Related Entities When Creating an Entity</a></li>
<li><a href="#CreateRelatedEntitiesWhenCreatinganEntity">11.4.2.2 Create Related Entities When Creating an Entity</a></li>
</ul></li>
<li><a href="#UpdateanEntity">11.4.3 Update an Entity</a>
<ul>
<li><a href="#UpdateRelatedEntitiesWhenUpdatinganEntity">11.4.3.1 Update Related Entities When Updating an Entity</a></li>
</ul></li>
<li><a href="#UpsertanEntity">11.4.4 Upsert an Entity</a></li>
<li><a href="#DeleteanEntity">11.4.5 Delete an Entity</a></li>
<li><a href="#ModifyingRelationshipsbetweenEntities">11.4.6 Modifying Relationships between Entities</a>
<ul>
<li><a href="#AddaReferencetoaCollectionValuedNavigationProperty">11.4.6.1 Add a Reference to a Collection-Valued Navigation Property</a></li>
<li><a href="#RemoveaReferencetoanEntity">11.4.6.2 Remove a Reference to an Entity</a></li>
<li><a href="#ChangetheReferenceinaSingleValuedNavigationProperty">11.4.6.3 Change the Reference in a Single-Valued Navigation Property</a></li>
<li><a href="#ReplaceallReferencesinaCollectionValuedNavigationProperty">11.4.6.4 Replace all References in a Collection-Valued Navigation Property</a></li>
</ul></li>
<li><a href="#ManagingMediaEntities">11.4.7 Managing Media Entities</a>
<ul>
<li><a href="#CreateaMediaEntity">11.4.7.1 Create a Media Entity</a></li>
<li><a href="#UpdateaMediaEntityStream">11.4.7.2 Update a Media Entity Stream</a></li>
<li><a href="#DeleteaMediaEntity">11.4.7.3 Delete a Media Entity</a></li>
</ul></li>
<li><a href="#ManagingStreamProperties">11.4.8 Managing Stream Properties</a>
<ul>
<li><a href="#UpdateStreamValues">11.4.8.1 Update Stream Values</a></li>
<li><a href="#DeleteStreamValues">11.4.8.2 Delete Stream Values</a></li>
</ul></li>
<li><a href="#ManagingValuesandPropertiesDirectly">11.4.9 Managing Values and Properties Directly</a>
<ul>
<li><a href="#UpdateaPrimitiveProperty">11.4.9.1 Update a Primitive Property</a></li>
<li><a href="#SetaValuetoNull">11.4.9.2 Set a Value to Null</a></li>
<li><a href="#UpdateaComplexProperty">11.4.9.3 Update a Complex Property</a></li>
<li><a href="#UpdateaCollectionProperty">11.4.9.4 Update a Collection Property</a></li>
</ul></li>
<li><a href="#ManagingMembersofanOrderedCollection">11.4.10 Managing Members of an Ordered Collection</a></li>
<li><a href="#PositionalInserts">11.4.11 Positional Inserts</a></li>
<li><a href="#UpdateaCollectionofEntities">11.4.12 Update a Collection of Entities</a></li>
<li><a href="#UpdateMembersofaCollection">11.4.13 Update Members of a Collection</a></li>
<li><a href="#DeleteMembersofaCollection">11.4.14 Delete Members of a Collection</a></li>
</ul></li>
<li><a href="#Operations">11.5 Operations</a>
<ul>
<li><a href="#BindinganOperationtoaResource">11.5.1 Binding an Operation to a Resource</a></li>
<li><a href="#ApplyinganActiontoMembersofaCollection">11.5.2 Applying an Action to Members of a Collection</a></li>
<li><a href="#AdvertisingAvailableOperationswithinaPayload">11.5.3 Advertising Available Operations within a Payload</a></li>
<li><a href="#Functions">11.5.4 Functions</a>
<ul>
<li><a href="#InvokingaFunction">11.5.4.1 Invoking a Function</a>
<ul>
<li><a href="#InlineParameterSyntax">11.5.4.1.1 Inline Parameter Syntax</a></li>
</ul></li>
<li><a href="#Functionoverloadresolution">11.5.4.2 Function overload resolution</a></li>
</ul></li>
<li><a href="#Actions">11.5.5 Actions</a>
<ul>
<li><a href="#InvokinganAction">11.5.5.1 Invoking an Action</a></li>
<li><a href="#ActionOverloadResolution">11.5.5.2 Action Overload Resolution</a></li>
</ul></li>
</ul></li>
<li><a href="#AsynchronousRequests">11.6 Asynchronous Requests</a></li>
<li><a href="#BatchRequests">11.7 Batch Requests</a>
<ul>
<li><a href="#BatchRequestHeaders">11.7.1 Batch Request Headers</a></li>
<li><a href="#RequestDependencies">11.7.2 Request Dependencies</a></li>
<li><a href="#IdentifyingIndividualRequests">11.7.3 Identifying Individual Requests</a></li>
<li><a href="#ReferencingReturnedEntities">11.7.4 Referencing Returned Entities</a></li>
<li><a href="#ReferencingtheETagofanEntity">11.7.5 Referencing the ETag of an Entity</a></li>
<li><a href="#ReferencingValuesfromResponseBodies">11.7.6 Referencing Values from Response Bodies</a></li>
<li><a href="#MultipartBatchFormat">11.7.7 Multipart Batch Format</a>
<ul>
<li><a href="#MultipartBatchRequestBody">11.7.7.1 Multipart Batch Request Body</a></li>
<li><a href="#ReferencingNewEntities">11.7.7.2 Referencing New Entities</a></li>
<li><a href="#ReferencinganETag">11.7.7.3 Referencing an ETag</a></li>
<li><a href="#ProcessingaMultipartBatchRequest">11.7.7.4 Processing a Multipart Batch Request</a></li>
<li><a href="#MultipartBatchResponse">11.7.7.5 Multipart Batch Response</a></li>
<li><a href="#AsynchronousBatchRequests">11.7.7.6 Asynchronous Batch Requests</a></li>
</ul></li>
</ul></li>
</ul></li>
<li><a href="#Conformance">12 Conformance</a>
<ul>
<li><a href="#OData40ServiceConformanceLevels">12.1 OData 4.0 Service Conformance Levels</a>
<ul>
<li><a href="#OData40MinimalConformanceLevel">12.1.1 OData 4.0 Minimal Conformance Level</a></li>
<li><a href="#OData40IntermediateConformanceLevel">12.1.2 OData 4.0 Intermediate Conformance Level</a></li>
<li><a href="#OData40AdvancedConformanceLevel">12.1.3 OData 4.0 Advanced Conformance Level</a></li>
</ul></li>
<li><a href="#OData401ServiceConformanceLevels">12.2 OData 4.01 Service Conformance Levels</a>
<ul>
<li><a href="#OData401MinimalConformanceLevel">12.2.1 OData 4.01 Minimal Conformance Level</a></li>
<li><a href="#OData401IntermediateConformanceLevel">12.2.2 OData 4.01 Intermediate Conformance Level</a></li>
<li><a href="#OData401AdvancedConformanceLevel">12.2.3 OData 4.01 Advanced Conformance Level</a></li>
</ul></li>
<li><a href="#InteroperableODataClients">12.3 Interoperable OData Clients</a></li>
</ul></li>
<li><a href="#References">A References</a>
<ul>
<li><a href="#NormativeReferences">A.1 Normative References</a></li>
<li><a href="#InformativeReferences">A.2 Informative References</a></li>
</ul></li>
<li><a href="#SafetySecurityandPrivacyConsiderations">B Safety, Security and Privacy Considerations</a>
<ul>
<li><a href="#Authentication">B.1 Authentication</a></li>
</ul></li>
<li><a href="#Acknowledgments">C Acknowledgments</a>
<ul>
<li><a href="#SpecialThanks">C.1 Special Thanks</a></li>
<li><a href="#Participants">C.2 Participants</a></li>
</ul></li>
<li><a href="#RevisionHistory">D Revision History</a></li>
<li><a href="#Notices">E Notices</a></li>
</ul>
</div>
<hr />
<h1 id="1-introduction"><a name="Introduction" href="#Introduction">1 Introduction</a></h1>
<p>The Open Data Protocol (OData) enables the creation of REST-based data services which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines the core semantics and the behavioral aspects of the protocol.</p>
<p>The <a href="#ODataURL">OData-URL</a> specification defines a set of rules for constructing URLs to identify the data and metadata exposed by an OData service as well as a set of reserved URL query options.</p>
<p>The <a href="#ODataCSDL">OData-CSDLJSON</a> specification defines a JSON representation of the entity data model exposed by an OData service.</p>
<p>The <a href="#ODataCSDL">OData-CSDLXML</a> specification defines an XML representation of the entity data model exposed by an OData service.</p>
<p>The <a href="#ODataJSON">OData-JSON</a> document specifies the JSON format of the resource representations that are exchanged using OData.</p>
<h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" href="#ChangesfromEarlierVersions">1.1 Changes from Earlier Versions</a></h2>
<!-- TODO -->
<!-- Describe significant changes from previous differently-numbered Versions, not changes between stages of the current Version -->
<h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
<h3 id="121-definitions-of-terms"><a name="DefinitionsofTerms" href="#DefinitionsofTerms">1.2.1 Definitions of Terms</a></h3>
<h3 id="122-acronyms-and-abbreviations"><a name="AcronymsandAbbreviations" href="#AcronymsandAbbreviations">1.2.2 Acronyms and Abbreviations</a></h3>
<!-- TODO -->
<h3 id="123-document-conventions"><a name="DocumentConventions" href="#DocumentConventions">1.2.3 Document Conventions</a></h3>
<p>Keywords defined by this specification use <code>this monospaced font</code>.</p>
<p>Some sections of this specification are illustrated with non-normative examples.</p>
<div class="example">
<p>Example 1: text describing an example uses this paragraph style</p>
<pre><code>Non-normative examples use this paragraph style.</code></pre>
</div>
<p>All examples in this document are non-normative and informative only.</p>
<p>All other text is normative unless otherwise labeled.</p>
<div class="example">
<p>Here is a customized command line which will generate HTML from this markdown file (named <code>odata-v4.02-csd01-part1-protocol.md</code>). Line breaks are added for readability only:</p>
<pre><code>pandoc -f gfm+tex_math_dollars+fenced_divs
-t html
-o odata-v4.02-csd01-part1-protocol.html
-c styles/markdown-styles-v1.7.3b.css
-c styles/odata.css
-s
--mathjax
--eol=lf
--wrap=none
--metadata pagetitle="OData Version 4.02. Part 1: Protocol"
odata-v4.02-csd01-part1-protocol.md</code></pre>
<p>This uses pandoc 3.1.2 from <a href="https://github.com/jgm/pandoc/releases/tag/3.1.2">https://github.com/jgm/pandoc/releases/tag/3.1.2</a>.</p>
</div>
<hr />
<h1 id="2-overview"><a name="Overview" href="#Overview">2 Overview</a></h1>
<p>The OData Protocol is an application-level protocol for interacting with data via RESTful interfaces. The protocol supports the description of data models and the editing and querying of data according to those models. It provides facilities for:</p>
<ul>
<li>Metadata: a machine-readable description of the data model exposed by a particular service.</li>
<li>Data: sets of data entities and the relationships between them.</li>
<li>Querying: requesting that the service perform a set of filtering and other transformations to its data, then return the results.</li>
<li>Editing: creating, updating, and deleting data.</li>
<li>Operations: invoking custom logic</li>
<li>Vocabularies: attaching custom semantics</li>
</ul>
<p>The OData Protocol is different from other REST-based web service approaches in that it provides a uniform way to describe both the data and the data model. This improves semantic interoperability between systems and allows an ecosystem to emerge.</p>
<p>Towards that end, the OData Protocol follows these design principles:</p>
<ul>
<li>Prefer mechanisms that work on a variety of data sources. In particular, do not assume a relational data model.</li>
<li>Extensibility is important. Services should be able to support extended functionality without breaking clients unaware of those extensions.</li>
<li>Follow REST principles.</li>
<li>OData should build incrementally. A very basic, compliant service should be easy to build, with additional work necessary only to support additional capabilities.</li>
<li>Keep it simple. Address the common cases and provide extensibility where necessary.</li>
</ul>
<hr />
<h1 id="3-data-model"><a name="DataModel" href="#DataModel">3 Data Model</a></h1>
<p>This section provides a high-level description of the <em>Entity Data Model (EDM)</em>: the abstract data model that is used to describe the data exposed by an OData service. An <a href="#MetadataDocumentRequest">OData Metadata Document</a> is a representation of a service's data model exposed for client consumption.</p>
<p>The central concepts in the EDM are entities, relationships, entity sets, actions, and functions.</p>
<p><em>Entities</em> are instances of entity types (e.g. <code>Customer</code>, <code>Employee</code>, etc.).</p>
<p><em>Entity types</em> are named structured types with a key. They define the named properties and relationships of an entity. Entity types may derive by single inheritance from other entity types.</p>
<p>The <em>key</em> of an entity type is formed from a subset of the primitive properties (e.g. <code>CustomerId</code>, <code>OrderId</code>, <code>LineId</code>, etc.) of the entity type.</p>
<p><em>Complex types</em> are keyless named structured types consisting of a set of properties. These are value types whose instances cannot be referenced outside of their containing entity. Complex types are commonly used as property values in an entity or as parameters to operations.</p>
<p>Properties declared as part of a structured type's definition are called <em>declared properties</em>. Instances of structured types may contain additional undeclared <em>dynamic properties</em>. A dynamic property cannot have the same name as a declared property. Entity or complex types which allow clients to persist additional undeclared properties are called <em>open types</em>.</p>
<p>Relationships from one entity to another are represented as <em>navigation properties.</em> Navigation properties are generally defined as part of an entity type, but can also appear on entity instances as undeclared <em>dynamic navigation properties</em>. Each relationship has a cardinality.</p>
<p><em>Enumeration types</em> are named primitive types whose values are named constants with underlying integer values.</p>
<p><em>Type definitions</em> are named primitive types with fixed facet values such as maximum length or precision. Type definitions can be used in place of primitive typed properties, for example, within property definitions.</p>
<p><em>Entity sets</em> are named collections of entities (e.g. <code>Customers</code> is an entity set containing <code>Customer</code> entities). An entity's key uniquely identifies the entity within an entity set. If multiple entity sets use the same entity type, the same combination of key values can appear in more than one entity set and identifies different entities, one per entity set where this key combination appears. Each of these entities has a different <a href="#EntityIdsandEntityReferences">entity-id</a>. Entity sets provide entry points into the data model.</p>
<p><em>Operations</em> allow the execution of custom logic on parts of a data model. <a href="#Functions"><em>Functions</em></a> are operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action. <a href="#Actions"><em>Actions</em></a> are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior. Actions and functions are either <em>bound</em> to a type, enabling them to be called as members of an instance of that type, or unbound, in which case they are called as static operations. <em>Action imports</em> and <em>function imports</em> enable unbound actions and functions to be called from the service root.</p>
<p><em>Singletons</em> are named entities which can be accessed as direct children of the entity container. A singleton may also be a member of an entity set.</p>
<p>An OData <em>resource</em> is anything in the model that can be addressed (an entity set, entity, property, or operation).</p>
<p>Refer to <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a> for more information on the OData entity data model.</p>
<h2 id="31-annotations"><a name="Annotations" href="#Annotations">3.1 Annotations</a></h2>
<p>Model and instance elements can be decorated with <em>Annotations</em>.</p>
<p>Annotations can be used to specify an individual fact about an element, such as whether it is read-only, or to define a common concept, such as a person or a movie.</p>
<p>Applied <em>annotations</em> consist of a <em>term</em> (the namespace-qualified name of the annotation being applied), a <em>target</em> (the model or instance element to which the term is applied), and a <em>value</em>. The value may be a static value, or an expression that may contain a path to one or more properties of an annotated entity.</p>
<p>Annotation terms are defined in metadata and have a name and a type.</p>
<p>A set of related terms in a common namespace comprises a <em>Vocabulary</em>.</p>
<hr />
<h1 id="4-service-model"><a name="ServiceModel" href="#ServiceModel">4 Service Model</a></h1>
<p>OData services are defined using a common data model. The service advertises its concrete data model in a machine-readable form, allowing generic clients to interact with the service in a well-defined way.</p>
<p>An OData service exposes two well-defined resources that describe its data model; a service document and a metadata document.</p>
<p>The <a href="#ServiceDocumentRequest"><em>service document</em></a> lists entity sets, functions, and singletons that can be retrieved. Clients can use the service document to navigate the model in a hypermedia-driven fashion.</p>
<p>The <a href="#MetadataDocumentRequest"><em>metadata document</em></a> describes the types, sets, functions and actions understood by the OData service. Clients can use the metadata document to understand how to query and interact with entities in the service.</p>
<p>In addition to these two "fixed" resources, an OData service consists of dynamic resources. The URLs for many of these resources can be computed from the information in the metadata document.</p>
<p>See <a href="#RequestingData">Requesting Data</a> and <a href="#DataModification">Data Modification</a> for details.</p>
<h2 id="41-entity-ids-and-entity-references"><a name="EntityIdsandEntityReferences" href="#EntityIdsandEntityReferences">4.1 Entity-Ids and Entity References</a></h2>
<p>Whereas entities within an entity set are uniquely identified by their key values, entities are also uniquely identified by a durable, opaque, globally unique <em>entity-id</em>. The entity-id MUST be an IRI as defined in <a href="#rfc3987">RFC3987</a> and MAY be expressed in payloads, headers, and URLs as a relative reference as appropriate. While the client MUST be prepared to accept any IRI, services MUST use valid URIs in this version of the specification since there is currently no lossless representation of an IRI in the <a href="#HeaderODataEntityId"><code>EntityId</code></a> header.</p>
<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <strong>OData-URL</strong> as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs"><code>Core.DereferenceableIDs</code></a> term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource <code>$entity</code> provides a general mechanism for <a href="#ResolvinganEntityId">resolving an entity-id</a> into an entity representation.</p>
<p>Services that use the standard URL conventions for entity-ids annotate their entity container with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#ConventionalIDs"><code>Core.ConventionalIDs</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p><em>Entity references</em> refer to an entity using the entity's entity-id.</p>
<h2 id="42-read-urls-and-edit-urls"><a name="ReadURLsandEditURLs" href="#ReadURLsandEditURLs">4.2 Read URLs and Edit URLs</a></h2>
<p>The read URL of an entity is the URL that can be used to read the entity.</p>
<p>The edit URL of an entity is the URL that can be used to update or delete the entity.</p>
<p>The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property.</p>
<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <strong>OData-URL</strong> for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.</p>
<h2 id="43-transient-entities"><a name="TransientEntities" href="#TransientEntities">4.3 Transient Entities</a></h2>
<p>Transient entities are instances of an entity type that are "calculated on the fly" and only exist within a single payload. They cannot be reread or updated and consequently possess neither a stable entity-id nor a read URL or an update URL.</p>
<h2 id="44-default-namespaces"><a name="DefaultNamespaces" href="#DefaultNamespaces">4.4 Default Namespaces</a></h2>
<p>References to actions, functions, and types within a URL typically requires prefixing the name of the action, function, or type with the namespace or alias in which it is defined. This namespace qualification enables differentiating between similarly named elements across schema, or between properties and bound functions, actions, or types with the same name.</p>
<p>Services MAY define one or more default namespaces through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. Functions, actions and types in a default namespace can be referenced in URLs with or without namespace or alias qualification.</p>
<p>Service designers should ensure uniqueness of schema children across all default namespaces, and should avoid naming bound functions, actions, or derived types with the same name as a structural or navigation property of the type.</p>
<p>In the case where ambiguity does exist, an unqualified segment appended to a structured value is always first compared to the list of properties defined on the structured type. If no defined property with a name matching the unqualified segment exists, or the preceding segment represents a collection or a scalar value, it is next compared to the names of any bound functions or actions, or derived type names, defined within any default namespace. If it still does not match, and the preceding segment represents a structured value, it is interpreted as a dynamic property.</p>
<p>Services MAY disallow dynamic properties on structured values whose names conflict with a bound action, function, or derived type defined within in a default namespace.</p>
<p>The behavior if name conflicts occur across children of default namespaces is undefined. Generic clients are encouraged to always qualify action, function, and type names in order to avoid any possible ambiguity.</p>
<hr />
<h1 id="5-versioning"><a name="Versioning" href="#Versioning">5 Versioning</a></h1>
<p>Versioning enables clients and services to evolve independently. OData defines semantics for both protocol and data model versioning.</p>
<h2 id="51-protocol-versioning"><a name="ProtocolVersioning" href="#ProtocolVersioning">5.1 Protocol Versioning</a></h2>
<p>OData requests and responses are versioned according to the <a href="#HeaderODataVersion"><code>OData-Version</code></a> header.</p>
<p>OData clients include the <a href="#HeaderODataMaxVersion"><code>OData-MaxVersion</code></a> header in requests in order to specify the maximum acceptable response version. Services respond with the maximum supported version that is less than or equal to the requested <code>OData-MaxVersion</code>, using decimal comparison. The syntax of the <code>OData-Version</code> and <code>OData-MaxVersion</code> header fields is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>Services SHOULD advertise supported versions of OData through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#ODataVersions"><code>Core.ODataVersions</code></a> term, defined in <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>This version of the specification defines OData version values <code>4.0</code> and <code>4.01</code>. Content that applies only to one version or another is explicitly called out in the text.</p>
<h2 id="52-model-versioning"><a name="ModelVersioning" href="#ModelVersioning">5.2 Model Versioning</a></h2>
<p>The <a href="#DataModel">Data Model</a> exposed by an OData Service defines a contract between the OData service and its clients. Services are allowed to extend their model only to the degree that it does not break existing clients. Breaking changes, such as removing properties, changing the type of existing properties, adding or removing key properties, or reordering action or function parameters, require that a new service version is provided at a different service root URL for the new model, or that the service version its metadata using the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>Services that version their metadata MUST support version-specific requests according to the <a href="#SystemQueryOptionschemaversion"><code>$schemaversion</code></a> system query option. The following Data Model additions are considered safe and do not require services to version their entry point or schema.</p>
<ul>
<li>Adding a property that is nullable or has a default value; if it has the same name as an existing dynamic property, it must have the same type (or base type) as the existing dynamic property</li>
<li>Adding a navigation property that is nullable or collection-valued; if it has the same name as an existing dynamic navigation property, it must have the same type (or base type) as the existing dynamic navigation property</li>
<li>Adding a new entity type to the model</li>
<li>Adding a new complex type to the model</li>
<li>Adding a new entity set</li>
<li>Adding a new singleton</li>
<li>Adding an action, a function, an action import, or function import</li>
<li>Adding an action parameter that is nullable after existing parameters</li>
<li>Adding an action or function parameter that is annotated with <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> after existing parameters</li>
<li>Adding a type definition or enumeration</li>
<li>Adding a new term</li>
<li>Adding any annotation to a model element that does not need to be understood by the client in order to correctly interact with the service</li>
</ul>
<p>Clients SHOULD be prepared for services to make such incremental changes to their model. In particular, clients SHOULD be prepared to receive properties and derived types not previously defined by the service.</p>
<p>Services SHOULD NOT change their data model depending on the authenticated user. If the data model is user or user-group dependent, all changes MUST be <em>safe changes</em> as defined in this section when comparing the full model to the model visible to users with restricted authorizations.</p>
<hr />
<h1 id="6-extensibility"><a name="Extensibility" href="#Extensibility">6 Extensibility</a></h1>
<p>The OData protocol supports both user- and version-driven extensibility through a combination of versioning, convention, and explicit extension points.</p>
<h2 id="61-query-option-extensibility"><a name="QueryOptionExtensibility" href="#QueryOptionExtensibility">6.1 Query Option Extensibility</a></h2>
<p>Query options within the request URL can control how a particular request is processed by the service.</p>
<p>OData-defined system query options are optionally prefixed with "<code>$</code>". Services may support additional custom query options not defined in the OData specification, but they MUST NOT begin with the "<code>$</code>" or "<code>@</code>" character and MUST NOT conflict with any OData-defined system query options defined in the OData version supported by the service.</p>
<p>OData services SHOULD NOT require any query options to be specified in a request. Services SHOULD fail any request that contains query options that they do not understand and MUST fail any request that contains unsupported OData query options defined in the version of this specification supported by the service.</p>
<p>In many cases OData services return URLs to identify resources that are later requested by clients. Where possible, interoperability is enhanced by providing all identifying information in the path portion of the URL. However, clients should be prepared for such URLs to include custom query options and propagate any such custom query options in future requests to the identified resource.</p>
<h2 id="62-payload-extensibility"><a name="PayloadExtensibility" href="#PayloadExtensibility">6.2 Payload Extensibility</a></h2>
<p>OData supports extensibility in the payload, according to the specific format.</p>
<p>Regardless of the format, additional content MUST NOT be present if it needs to be understood by the receiver in order to correctly interpret the payload according to the specified <a href="#HeaderODataVersion"><code>OData-Version</code></a> header. Thus, clients and services MUST be prepared to handle or safely ignore any content not specifically defined in the version of the payload specified by the <code>OData-Version</code> header.</p>
<h2 id="63-actionfunction-extensibility"><a name="ActionFunctionExtensibility" href="#ActionFunctionExtensibility">6.3 Action/Function Extensibility</a></h2>
<p><a href="#Actions">Actions</a> and <a href="#Functions">Functions</a> extend the set of operations that can be performed on or with a service or resource. Actions can have side-effects. For example, Actions can be used to modify data or to invoke custom operations. Functions MUST NOT have side-effects. Functions can be invoked from a URL that addresses a resource or within an expression to a <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> system query option.</p>
<p>Fully qualified action and function names include a namespace or alias prefix. The <code>Edm</code>, <code>odata</code> and <code>geo</code> namespaces are reserved for the use of this specification.</p>
<p>An OData service MUST fail any request that contains actions or functions that it does not understand.</p>
<h2 id="64-vocabulary-extensibility"><a name="VocabularyExtensibility" href="#VocabularyExtensibility">6.4 Vocabulary Extensibility</a></h2>
<p>The set of <a href="#Annotations">annotations</a> defined within a schema comprise a <em>vocabulary</em>. Shared vocabularies provide a powerful extensibility point for OData.</p>
<p>Metadata annotations can be used to define additional characteristics or capabilities of a metadata element, such as a service, entity type, property, function, action or parameter. For example, a metadata annotation could define ranges of valid values for a particular property.</p>
<p>Instance annotations can be used to define additional information associated with a particular result, entity, property, or error; for example whether a property is read-only for a particular instance.</p>
<p>Where annotations apply across all instances of a type, services are encouraged to specify the annotation in metadata rather than repeating in each instance of the payload. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the one specified at the metadata level.</p>
<p>A service MUST NOT require the client to understand custom annotations in order to accurately interpret a response.</p>
<p>OData defines a <code>Core</code> vocabulary with a set of basic terms describing behavioral aspects along with terms that can be used in defining other vocabularies; see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<h2 id="65-header-field-extensibility"><a name="HeaderFieldExtensibility" href="#HeaderFieldExtensibility">6.5 Header Field Extensibility</a></h2>
<p>OData defines semantics around certain HTTP request and response headers. Services that support a version of OData conform to the processing requirements for the headers defined by this specification for that version.</p>
<p>Individual services may define custom headers. These headers MUST NOT begin with <code>OData</code>. Custom headers SHOULD be optional when making requests to the service. A service MUST NOT require the client to understand custom headers to accurately interpret the response.</p>
<h2 id="66-format-extensibility"><a name="FormatExtensibility" href="#FormatExtensibility">6.6 Format Extensibility</a></h2>
<p>An OData service MUST support <a href="#ODataJSON">OData-JSON</a> and MAY support additional formats for both request and response bodies.</p>
<hr />
<h1 id="7-formats"><a name="Formats" href="#Formats">7 Formats</a></h1>
<p>The client MAY request a particular response format through the <a href="#HeaderAccept"><code>Accept</code></a> header, as defined in <a href="#rfc7231">RFC7231</a>, or through the system query option <a href="#SystemQueryOptionformat"><code>$format</code></a>.</p>
<p>In the case that both the <code>Accept</code> header and the <code>$format</code> system query option are specified on a request, the value specified in the <code>$format</code> query option MUST be used.</p>
<p>If the service does not support the requested format, it replies with a <a href="#ResponseCode406NotAcceptable"><code>406 Not Acceptable</code></a> error response.</p>
<p>Services SHOULD advertise their supported formats in the metadata document by annotating their entity container with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#SupportedFormats"><code>Capabilities.SupportedFormats</code></a>, as defined in <a href="#ODataVocCap">OData-VocCap</a>, listing all available formats and combinations of supported format parameters.</p>
<p>The media types for the JSON and XML representation of the metadata document are described in section "<a href="#MetadataDocumentRequest">Metadata Document Request</a>".</p>
<p>The format specification <a href="#ODataJSON">OData-JSON</a> describes the media type and the format parameters for non-metadata requests and responses.</p>
<p>For non-metadata requests, if neither the <code>Accept</code> header nor the <code>$format</code> query option are specified, the service MAY respond to requests in any format.</p>
<p>Client libraries MUST retain the order of objects within an array in JSON responses, and elements in document order for XML responses, including CSDL documents.</p>
<hr />
<h1 id="8-header-fields"><a name="HeaderFields" href="#HeaderFields">8 Header Fields</a></h1>
<p>OData defines semantics around the following request and response headers. Additional headers may be specified, but have no unique semantics defined in OData.</p>
<h2 id="81-common-headers"><a name="CommonHeaders" href="#CommonHeaders">8.1 Common Headers</a></h2>
<p>The following headers are common between OData requests and responses.</p>
<h3 id="811-header-content-type"><a name="HeaderContentType" href="#HeaderContentType">8.1.1 Header <code>Content-Type</code></a></h3>
<p>The format of a non-empty individual request or response body, alone or within a batch, MUST be specified in the <code>Content-Type</code> header of a request or response. The exception to this is if the body represents the media stream of a <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entity</a> or <a href="#ManagingStreamProperties">stream property</a>, in which case the <code>Content-Type</code> header SHOULD be present.</p>
<p>The specified format MAY include format parameters. Clients MUST be prepared for the service to return custom format parameters not defined in OData and SHOULD NOT expect that such format parameters can be ignored. Custom format parameters MUST NOT start with "odata" and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload.</p>
<p>See <a href="#ODataJSON">OData-JSON</a> for format-specific details about format parameters within the <code>Content-Type</code> header.</p>
<h3 id="812-header-content-encoding"><a name="HeaderContentEncoding" href="#HeaderContentEncoding">8.1.2 Header <code>Content-Encoding</code></a></h3>
<p>As defined in <a href="#rfc7231">RFC7231</a>, the <code>Content-Encoding</code> header field is used as a modifier to the media-type (as indicated in the <code>Content-Type</code>). When present, its value indicates what additional content codings have been applied to the entity-body. A service MAY specify a list of acceptable content codings using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#AcceptableEncodings"><code>Capabilities.AcceptableEncodings</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>If the <code>Content-Encoding</code> header is specified on an individual request or response within a batch, then it specifies the encoding for that individual request or response. Individual requests or responses that don't include the <code>Content-Encoding</code> header inherit the encoding of the overall batch request or response.</p>
<h3 id="813-header-content-language"><a name="HeaderContentLanguage" href="#HeaderContentLanguage">8.1.3 Header <code>Content-Language</code></a></h3>
<p>As defined in <a href="#rfc7231">RFC7231</a>, a request or response can include a <code>Content-Language</code> header to indicate the natural language of the intended audience for the enclosed message body. OData does not add any additional requirements over HTTP for including <code>Content-Language</code>. OData services can annotate model elements whose content depends on the content language with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent"><code>Core.IsLanguageDependent</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>If the <code>Content-Language</code> header is specified on an individual request or response within a batch, then it specifies the language for that individual request or response. Individual requests or responses that don't include the <code>Content-Language</code> header inherit the language of the overall batch request or response.</p>
<h3 id="814-header-content-length"><a name="HeaderContentLength" href="#HeaderContentLength">8.1.4 Header <code>Content-Length</code></a></h3>
<p>As defined in <a href="#rfc7230">RFC7230</a>, a request or response SHOULD include a <code>Content-Length</code> header when the message's length can be determined prior to being transferred. OData does not add any additional requirements over HTTP for writing <code>Content-Length</code>.</p>
<p>If the <code>Content-Length</code> header is specified on an individual request or response within a batch, then it specifies the length for that individual request or response.</p>
<h3 id="815-header-odata-version"><a name="HeaderODataVersion" href="#HeaderODataVersion">8.1.5 Header <code>OData-Version</code></a></h3>
<p>OData clients SHOULD use the <code>OData-Version</code> header on a request to specify the version of the protocol used to generate the request payload.</p>
<p>If present on a request, the service MUST interpret the request payload according to the rules defined in the specified version of the protocol or fail the request with a <code>4xx</code> response code.</p>
<p>If not specified in a request, the service MUST assume the request payload is generated using the minimum of the <a href="#HeaderODataMaxVersion"><code>OData-MaxVersion</code></a>, if specified, and the maximum version of the protocol that the service understands.</p>
<p>OData services MUST include the <code>OData-Version</code> header on a response to specify the version of the protocol used to generate the response payload. The client MUST interpret the response payload according to the rules defined in the specified version of the protocol. Request and response payloads are independent and may have different <code>OData-Version</code> headers according to the above rules.</p>
<p>For more details, see <a href="#Versioning">Versioning</a>.</p>
<p>If the <code>OData-Version</code> header is specified on an individual request or response within a batch, then it specifies the OData version for that individual request or response. Individual requests or responses that don't include the <code>OData-Version</code> header inherit the OData version of the overall batch request or response. This OData version does not typically vary within a batch.</p>
<h2 id="82-request-headers"><a name="RequestHeaders" href="#RequestHeaders">8.2 Request Headers</a></h2>
<p>In addition to the <a href="#CommonHeaders">Common Headers</a>, the client may specify any combination of the following request headers.</p>
<h3 id="821-header-accept"><a name="HeaderAccept" href="#HeaderAccept">8.2.1 Header <code>Accept</code></a></h3>
<p>As defined in <a href="#rfc7231">RFC7231</a>, the client MAY specify the set of accepted <a href="#Formats">formats</a> with the <code>Accept</code> Header.</p>
<p>Services MUST reject formats that specify unknown or unsupported format parameters.</p>
<p>If a media type specified in the <code>Accept</code> header includes a <code>charset</code> format parameter and the request also contains an <a href="#HeaderAcceptCharset"><code>Accept-Charset</code></a> header, then the <code>Accept-Charset</code> header MUST be used.</p>
<p>If the media type specified in the <code>Accept</code> header does not include a <code>charset</code> format parameter, then the <a href="#HeaderContentType"><code>Content-Type</code></a> header of the response MUST NOT contain a <code>charset</code> format parameter.</p>
<p>The service SHOULD NOT add any format parameters to the <code>Content-Type</code> parameter not specified in the <code>Accept</code> header.</p>
<p>If the <code>Accept</code> header is specified on an individual request within a batch, then it specifies the acceptable formats for that individual request. Requests within a batch that don't include the <code>Accept</code> header inherit the acceptable formats of the overall batch request.</p>
<h3 id="822-header-accept-charset"><a name="HeaderAcceptCharset" href="#HeaderAcceptCharset">8.2.2 Header <code>Accept-Charset</code></a></h3>
<p>As defined in <a href="#rfc7231">RFC7231</a>, the client MAY specify the set of accepted character sets with the <code>Accept-Charset</code> header.</p>
<p>If the <code>Accept-Charset</code> header is specified on an individual request within a batch, then it specifies the acceptable character sets for that individual request. Requests within a batch that don't include the <code>Accept-Charset</code> header inherit the acceptable character sets of the overall batch request.</p>
<h3 id="823-header-accept-language"><a name="HeaderAcceptLanguage" href="#HeaderAcceptLanguage">8.2.3 Header <code>Accept-Language</code></a></h3>
<p>As defined in <a href="#rfc7231">RFC7231</a>, the client MAY specify the set of accepted natural languages with the <code>Accept-Language</code> header.</p>
<p>If the <code>Accept-Language</code> header is specified on an individual request within a batch, then it specifies the acceptable languages for that individual request. Requests within a batch that don't include the <code>Accept-Language</code> header inherit the acceptable languages of the overall batch request.</p>
<h3 id="824-header-if-match"><a name="HeaderIfMatch" href="#HeaderIfMatch">8.2.4 Header <code>If-Match</code></a></h3>
<p>As defined in <a href="#rfc7232">RFC7232</a>, a client MAY include an <code>If-Match</code> header in a request to <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code>. The value of the <code>If-Match</code> request header MUST be an ETag value previously retrieved for the resource, or <code>*</code> to match any value.</p>
<p>If an operation on an existing resource requires an ETag, (see term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency"><code>Core.OptimisticConcurrency</code></a><code> </code>in <a href="#ODataVocCore">OData-VocCore</a> and property <code>OptimisticConcurrencyControl</code> of type <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#NavigationPropertyRestriction"><code>Capabilities.NavigationPropertyRestriction</code></a> in <a href="#ODataVocCap">OData-VocCap</a>) and the client does not specify an <code>If-Match</code> request header in a <a href="#DataModification">Data Modification Request</a> or in an <a href="#Actions">Action Request</a> invoking an action bound to the resource, the service responds with a <code>428 Precondition Required</code> and MUST ensure that no observable change occurs as a result of the request.</p>
<p>If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending <a href="#HeaderETag"><code>ETag</code> headers</a> with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from <a href="#rfc7232">RFC7232</a>.</p>
<p>If the value does not match the current ETag value of the resource for a <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a>, the service MUST respond with <a href="#ResponseCode412PreconditionFailed"><code>412 Precondition Failed</code></a> and MUST ensure that no observable change occurs as a result of the request. In the case of an <a href="#UpsertanEntity">upsert</a>, if the addressed entity does not exist the provided ETag value is considered not to match.</p>
<p>An <code>If-Match</code> header with a value of <code>*</code> in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an update and not an insert.</p>
<p>The <code>If-Match</code> header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.</p>
<h3 id="825-header-if-none-match"><a name="HeaderIfNoneMatch" href="#HeaderIfNoneMatch">8.2.5 Header <code>If-None-Match</code></a></h3>
<p>As defined in <a href="#rfc7232">RFC7232</a>, a client MAY include an <code>If-None-Match</code> header in a request to <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code>. The value of the <code>If-None-Match</code> request header MUST be an ETag value previously retrieved for the resource, or <code>*</code>.</p>
<p>If present, the request MUST only be processed if the specified ETag value does not match the current ETag value of the resource, using the weak comparison function (see <a href="#rfc7232">RFC7232</a>). If the value matches the current ETag value of the resource, then for a <code>GET</code> request, the service SHOULD respond with <a href="#ResponseCode304NotModified"><code>304 Not Modified</code></a>, and for a <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a>, the service MUST respond with <a href="#ResponseCode412PreconditionFailed"><code>412 Precondition Failed</code></a> and MUST ensure that no observable change occurs as a result of the request.</p>
<p>An <code>If-None-Match</code> header with a value of <code>*</code> in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an <a href="#CreateanEntity">insert</a> and not an <a href="#UpdateanEntity">update</a>.</p>
<p>The <code>If-None-Match</code> header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.</p>
<h3 id="826-header-isolation-odata-isolation"><a name="HeaderIsolationODataIsolation" href="#HeaderIsolationODataIsolation">8.2.6 Header <code>Isolation</code> (<code>OData-Isolation</code>)</a></h3>
<p>The <code>Isolation</code> header specifies the isolation of the current request from external changes. The only supported value for this header is <code>snapshot</code>.</p>
<p>If the service doesn't support <code>Isolation:snapshot</code> and this header was specified on the request, the service MUST NOT process the request and MUST respond with <a href="#ResponseCode412PreconditionFailed"><code>412 Precondition Failed</code></a>.</p>
<p><em>Snapshot isolation</em> guarantees that all data returned for a request, including multiple requests within a <a href="#BatchRequests">batch</a> or results retrieved across multiple <a href="#ServerDrivenPaging">pages</a>, will be consistent as of a single point in time. Only data modifications made within the request (for example, by a data modification request within the same batch) are visible. The effect is as if the request generates a "snapshot" of the committed data as it existed at the start of the request.</p>
<p>The<code> Isolation</code> header may be specified on a single or batch request. If it is specified on a batch then the value is applied to all statements within the batch.</p>
<p>Next links returned within a snapshot return results within the same snapshot as the initial request; the client is not required to repeat the header on each individual page request.</p>
<p>The <code>Isolation</code> header has no effect on links other than the next link. Navigation links, read links, and edit links return the current version of the data.</p>
<p>A service returns <a href="#ResponseCode410Gone"><code>410 Gone</code></a> or <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a> if a consumer tries to follow a next link referring to a snapshot that is no longer available.</p>
<p>The syntax of the <code>Isolation</code> header is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>A service MAY specify the support for <code>Isolation:snapshot</code> using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#IsolationSupported"><code>Capabilities.IsolationSupported</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>Note: The <code>Isolation</code> header was named <code>OData-Isolation</code> in OData version 4.0. Services that support the<code> Isolation</code> header SHOULD also support <code>OData-Isolation</code> for OData 4.0 clients and clients SHOULD use <code>OData-Isolation</code> for compatibility with OData 4.0 services. If both <code>Isolation</code> and <code>OData-Isolation</code> headers are specified in the same request, the value of the <code>Isolation</code> header SHOULD be used.</p>
<h3 id="827-header-odata-maxversion"><a name="HeaderODataMaxVersion" href="#HeaderODataMaxVersion">8.2.7 Header <code>OData-MaxVersion</code></a></h3>
<p>Clients SHOULD specify an <code>OData-MaxVersion</code> request header.</p>
<p>If specified, the service MUST generate a response with the greatest supported <a href="#HeaderODataVersion"><code>OData-Version</code></a> less than or equal to the specified <code>OData-MaxVersion</code>.</p>
<p>If <code>OData-MaxVersion</code> is not specified, then the service SHOULD return responses with the same OData version over time and interpret the request as having an <code>OData-MaxVersion</code> equal to the maximum OData version supported by the service at its initial publication.</p>
<p>If the <code>OData-MaxVersion</code> header is specified on an individual request within a batch, then it specifies the maximum OData version for that individual request. Individual requests that don't include the <code>OData-MaxVersion</code> header inherit the maximum OData version of the overall batch request or response. The maximum OData version does not typically vary within a batch.</p>
<p>For more details, see <a href="#Versioning">Versioning</a>.</p>
<h3 id="828-header-prefer"><a name="HeaderPrefer" href="#HeaderPrefer">8.2.8 Header <code>Prefer</code></a></h3>
<p>The <code>Prefer</code> header, as defined in <a href="#rfc7240">RFC7240</a>, allows clients to request certain behavior from the service. The service MUST ignore preference values that are either not supported or not known by the service.</p>
<p>The value of the <code>Prefer</code> header is a comma-separated list of <em>preferences</em>. The following subsections describe preferences whose meaning in OData is defined by this specification.</p>
<p>In response to a request containing a <code>Prefer</code> header, the service MAY return the <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> and <a href="#HeaderVary"><code>Vary</code></a> headers.</p>
<h4 id="8281-preference-allow-entityreferences-odataallow-entityreferences"><a name="Preferenceallowentityreferencesodataallowentityreferences" href="#Preferenceallowentityreferencesodataallowentityreferences">8.2.8.1 Preference <code>allow-entityreferences</code> (<code>odata.allow-entityreferences</code>)</a></h4>
<p>The <code>allow-entityreferences</code> preference indicates that the service is allowed to return entity references in place of entities that have previously been returned, with at least the properties requested, in the same response (for example, when serializing the expanded results of many-to-many relationships). The service MUST NOT return entity references in place of requested entities if <code>allow-entityreferences</code> has not been specified in the request, unless explicitly defined by other rules in this document. The syntax of the <code>allow-entityreferences</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>In the case the service applies the <code>allow-entityreferences</code> preference it MUST include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header containing the <code>allow-entityreferences</code> preference to indicate that entity references MAY be returned in place of entities that have previously been returned.</p>
<p>If the <code>allow-entityreferences</code> preference is specified on an individual request within a batch, then it specifies the preference for that individual request. Individual requests within a batch that don't include the <code>allow-entityreferences</code> preference inherit the preference of the overall batch request.</p>
<p>Note: The <code>allow-entityreferences</code> preference was named <code>odata.allow-entityreferences</code> in OData version 4.0. Services that support the<code> allow-entityreferences</code> preference SHOULD also support <code>odata.allow-entityreferences</code> for OData 4.0 clients and clients SHOULD use <code>odata.allow-entityreferences</code> for compatibility with OData 4.0 services.</p>
<h4 id="8282-preference-callback-odatacallback"><a name="Preferencecallbackodatacallback" href="#Preferencecallbackodatacallback">8.2.8.2 Preference <code>callback</code> (<code>odata.callback</code>)</a></h4>
<p>For scenarios in which links returned by the service are used by the client to poll for additional information, the client can specify the <code>callback</code> preference to request that the service notify the client when data is available.</p>
<p>The <code>callback</code> preference can be specified:</p>
<ul>
<li>when requesting asynchronous processing of a request with the <a href="#Preferencerespondasync"><code>respond-async</code></a> preference, or</li>
<li>on a <code>GET</code> request to a <a href="#DeltaLinks">delta link</a>.</li>
</ul>
<p>The <code>callback</code> preference MUST include the parameter <code>url</code> whose value is the URL of a callback endpoint to be invoked by the OData service when data is available. The syntax of the <code>callback</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>For HTTP based callbacks, the OData service executes an HTTP <code>GET</code> request against the specified URL.</p>
<p>Services that support <code>callback</code> SHOULD support notifying the client through HTTP. Services can advertise callback support using the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#CallbackSupported"><code>Capabilities.CallbackSupported</code></a> annotation term defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>If the service applies the <code>callback</code> preference it MUST include the <code>callback</code> preference in the <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header.</p>
<p>When the <code>callback</code> preference is applied to asynchronous requests, the OData service invokes the callback endpoint once it has finished processing the request. The status monitor resource, returned in the <a href="#HeaderLocation"><code>Location</code> header</a> of the previously returned <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response, can then be used to retrieve the results of the asynchronously executed request.</p>
<p>When the <code>callback</code> preference is specified on a <code>GET</code> request to a delta link and there are no changes available, the OData service returns a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response with a <a href="#HeaderLocation"><code>Location</code> header</a> specifying the delta link to be used to check for future updates. The OData service then invokes the specified callback endpoint once new changes become available.</p>
<p>Combining <a href="#Preferencerespondasync"><code>respond-async</code></a>, <code>callback</code> and <a href="#Preferencetrackchangesodatatrackchanges"><code>track-changes</code></a> preferences on a <code>GET</code> request to a delta-link might influence the response in a couple of ways.</p>
<ul>
<li>If the service processes the request synchronously, and no updates are available, then the response is the same as if the respond-async hadn’t been specified and results in a response as described above.</li>
<li>If the service processes the request asynchronously, then it responds with a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response specifying the URL to the status monitor resource as it would have with any other asynchronous request. Once the service has finished processing the asynchronous request to the delta link resource, if changes are available it invokes the specified callback endpoint. If no changes are available, the service SHOULD wait to notify the client until changes are available. Once notified, the client uses the status monitor resource from the Location header of the previously returned <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response to retrieve the results. In case no updates were available after processing the initial request, the result will contain no updates and the client can use the delta-link contained in the result to retrieve the updates that have since become available.</li>
</ul>
<p>If the consumer specifies the same URL as callback endpoint in multiple requests, the service MAY collate them into a single notification once additional data is available for any of the requests. However, the consumer MUST be prepared to deal with receiving up to as many notifications as it requested.</p>
<div class="example">
<p>Example 2: using a HTTP callback endpoint to receive notification</p>
<pre><code>Prefer: callback; url="http://myserver/notfication/token/12345"</code></pre>
</div>
<p>If the <code>callback</code> preference is specified on an individual request within a batch, then it specifies the callback to be used for tracking changes to that individual request. If the <code>callback</code> preference is specified on a batch, then it specifies the callback to be used for async responses to the batch.</p>
<p>Note: The <code>callback</code> preference was named <code>odata.callback</code> in OData version 4.0. Services that support the<code> callback</code> preference SHOULD also support <code>odata.callback</code> for OData 4.0 clients and clients SHOULD use <code>odata.callback</code> for compatibility with OData 4.0 services. If both <code>callback</code> and <code>odata.callback</code> preferences are specified in the same request, the value of the <code>callback</code> preference SHOULD be used.</p>
<h4 id="8283-preference-continue-on-error-odatacontinue-on-error"><a name="Preferencecontinueonerrorodatacontinueonerror" href="#Preferencecontinueonerrorodatacontinueonerror">8.2.8.3 Preference <code>continue-on-error</code> (<code>odata.continue-on-error</code>)</a></h4>
<p>The <code>continue-on-error</code> preference on a <a href="#BatchRequests">batch request</a> is used to request whether, upon encountering a request within the batch that returns an error, the service return the error for that request and continue processing additional requests within the batch (if specified with an implicit or explicit value of <code>true</code>), or rather stop further processing (if specified with an explicit value of <code>false</code>). The syntax of the <code>continue-on-error</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>The <code>continue-on-error</code> preference can also be used on a <a href="#UpdateaCollectionofEntities">delta update</a>, <a href="#UpdateMembersofaCollection">set-based update</a>, or <a href="#DeleteMembersofaCollection">set-based delete</a> to request that the service continue attempting to process changes after receiving an error.</p>
<p>A service MAY specify support for the <code>continue-on-error</code> preference using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#BatchContinueOnErrorSupported"><code>Capabilities.BatchContinueOnErrorSupported</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>The <code>continue-on-error</code> preference SHOULD NOT be applied to individual requests within a batch.</p>
<p>Note: The <code>continue-on-error</code> preference was named <code>odata.continue-on-error</code> in OData version 4.0. Services that support the<code> continue-on-error</code> preference SHOULD also support <code>odata.continue-on-error</code> for OData 4.0 clients and clients SHOULD use <code>odata.continue-on-error</code> for compatibility with OData 4.0 services.</p>
<h4 id="8284-preference-include-annotations-odatainclude-annotations"><a name="Preferenceincludeannotationsodataincludeannotations" href="#Preferenceincludeannotationsodataincludeannotations">8.2.8.4 Preference <code>include-annotations</code> (<code>odata.include-annotations</code>)</a></h4>
<p>The <code>include-annotations</code> preference in a request for <a href="#RequestingData">data</a> or <a href="#MetadataDocumentRequest">metadata</a> is used to specify the set of annotations the client requests to be included, where applicable, in the response.</p>
<p>The value of the <code>include-annotations</code> preference is a comma-separated list of namespace-qualified term names or term name patterns to include or exclude, with <code>*</code> as a wildcard for name segments. Term names and term name patterns can optionally be followed by a hash (<code>#</code>) character and an annotation qualifier. The full syntax of the <code>include-annotations</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>The most specific identifier always takes precedence, with an explicit name taking precedence over a name pattern, and a longer pattern taking precedence over a shorter pattern. If the same identifier value is requested to both be excluded and included the behavior is undefined; the service MAY return or omit the specified vocabulary but MUST NOT raise an exception.</p>
<div class="example">
<p>Example 3: a <code>Prefer</code> header requesting all annotations within a metadata document to be returned</p>
<pre><code>Prefer: include-annotations="*"</code></pre>
</div>
<div class="example">
<p>Example 4: a <code>Prefer</code> header requesting that no annotations are returned</p>
<pre><code>Prefer: include-annotations="-*"</code></pre>
</div>
<div class="example">
<p>Example 5: a <code>Prefer</code> header requesting that all annotations defined under the "display" namespace (recursively) be returned</p>
<pre><code>Prefer: include-annotations="display.*"</code></pre>
</div>
<div class="example">
<p>Example 6: a <code>Prefer</code> header requesting that the annotation with the term name <code>subject</code> within the <code>display</code> namespace be returned</p>
<pre><code>Prefer: include-annotations="display.subject"</code></pre>
</div>
<div class="example">
<p>Example 7: a <code>Prefer</code> header requesting that all annotations defined under the "display" namespace (recursively) with the qualifier "tablet" be returned</p>
<pre><code>Prefer: include-annotations="display.*#tablet"</code></pre>
</div>
<p>The <code>include-annotations</code> preference is only a hint to the service. The service MAY ignore the preference and is free to decide whether or not to return annotations not specified in the <code>include-annotations</code> preference.</p>
<p>In the case that the client has specified the <code>include-annotations</code> preference in the request, the service SHOULD include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header containing the <code>include-annotations</code> preference to specify the annotations actually included, where applicable, in the response. This value may differ from the annotations requested in the <a href="#HeaderPrefer"><code>Prefer</code></a> header of the request.</p>
<p>If the <code>include-annotations</code> preference is specified on an individual request within a batch, then it specifies the preference for that individual request. Individual requests within a batch that don't include the <code>include-annotations</code> preference inherit the preference of the overall batch request.</p>
<p>Note: The <code>include-annotations </code>preference was named <code>odata.include-annotations</code> in OData version 4.0. Services that support the<code>include-annotations</code>preference SHOULD also support <code>odata.include-annotations</code> for OData 4.0 clients and clients SHOULD use <code>odata.include-annotations</code> for compatibility with OData 4.0 services. If both <code>include-annotations</code> and <code>odata.include-annotations</code> preferences are specified in the same request, the value of the <code>include-annotations</code> preference SHOULD be used.</p>
<h4 id="8285-preference-maxpagesize-odatamaxpagesize"><a name="Preferencemaxpagesizeodatamaxpagesize" href="#Preferencemaxpagesizeodatamaxpagesize">8.2.8.5 Preference <code>maxpagesize</code> (<code>odata.maxpagesize</code>)</a></h4>
<p>The <code>maxpagesize</code> preference is used to request that each collection within the response contain no more than the number of items specified as the positive integer value of this preference. The syntax of the <code>maxpagesize</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<div class="example">
<p>Example 8: a request for customers and their orders would result in a response containing one collection with customer entities and for every customer a separate collection with order entities. The client could specify <code>maxpagesize=50</code> in order to request that each page of results contain a maximum of 50 customers, each with a maximum of 50 orders.</p>
</div>
<p>If a collection within the result contains more than the specified <code>maxpagesize</code>, the collection SHOULD be <a href="#ServerDrivenPaging">a partial set of the results</a> with a <a href="#ServerDrivenPaging">next link</a> to the next page of results. The client MAY specify a different value for this preference with every request following a next link.</p>
<p>In the example given above, the result page should include a next link for the customer collection, if there are more than 50 customers, and additional next links for all returned orders collections with more than 50 entities.</p>
<p>If the client has specified the <code>maxpagesize</code> preference in the request, and the service limits the number of items in collections within the response through <a href="#ServerDrivenPaging">server-driven paging</a>, the service MAY include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header containing the <code>maxpagesize</code> preference and the maximum page size applied. This value may differ from the value requested by the client.</p>
<p>The <code>maxpagesize</code> preference SHOULD NOT be applied to a batch request, but MAY be applied to individual requests within a batch.</p>
<p>Note: The <code>maxpagesize</code> preference was named <code>odata.maxpagesize</code> in OData version 4.0. Services that support the<code> maxpagesize</code> preference SHOULD also support <code>odata.maxpagesize</code> for OData 4.0 clients and clients SHOULD use <code>odata.maxpagesize</code> for compatibility with OData 4.0 services. If both <code>maxpagesize</code> and <code>odata.maxpagesize</code> preferences are specified in the same request, the value of the <code>maxpagesize</code> preference SHOULD be used.</p>
<h4 id="8286-preference-omit-values"><a name="Preferenceomitvalues" href="#Preferenceomitvalues">8.2.8.6 Preference <code>omit-values</code></a></h4>
<p>The <code>omit-values</code> preference specifies values that MAY be omitted from a response payload. Valid values are <code>nulls</code> or <code>defaults</code>.</p>
<p>If <code>nulls</code> is specified, then the service MAY omit properties containing null values from the response, in which case it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=nulls</code>.</p>
<p>If <code>defaults</code> is specified, then the service MAY omit properties containing default values from the response, including nulls for properties that have no other defined default value. Nulls MUST be included for properties that have a non-null default value defined. If the service omits default values, it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=defaults</code>.</p>
<p>Properties with instance annotations are not affected by this preference and MUST be included in the payload if they would be included without this preference. Clients MUST NOT try to reconstruct a null or default value for properties for which an instance annotation is present and no property value is present, for example if the property is omitted due to permissions and has been replaced with the instance annotation <code>Core.Permissions</code> and a value of <code>None</code>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>Properties with null or default values MUST be included in delta payloads, if modified.</p>
<p>The response to a POST operation MUST include any properties not set to their default value, and the response to a PUT/PATCH operation MUST include any properties whose values were changed as part of the operation.</p>
<p>The <code>omit-values</code> preference does not affect a request payload.</p>
<h4 id="8287-preference-returnrepresentation-and-returnminimal"><a name="Preferencereturnrepresentationandreturnminimal" href="#Preferencereturnrepresentationandreturnminimal">8.2.8.7 Preference <code>return=representation</code> and <code>return=minimal</code></a></h4>
<p>The <code>return=representation</code> and <code>return=minimal</code> preferences are defined in <a href="#rfc7240">RFC7240</a>.</p>
<p>In OData, <code>return=representation</code> or <code>return=minimal</code> is defined for use with a <code>POST</code>, <code>PUT</code>, or <code>PATCH</code> <a href="#DataModification">Data Modification Request</a>, or with an <a href="#Actions">Action Request</a>. Specifying a preference of <code>return=representation</code> or <code>return=minimal</code> in a <code>GET</code> or <code>DELETE</code> request does not have any effect.</p>
<p>A preference of <code>return=representation</code> or <code>return=minimal</code> is allowed on an individual <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a> within a batch, subject to the same restrictions, but SHOULD return a <code>4xx Client Error</code> if specified on the batch request itself.</p>
<p>A preference of <code>return=minimal</code> requests that the service invoke the request but does not return content in the response. The service MAY apply this preference by returning <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> in which case it MAY include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a><code> </code>response header containing the <code>return=minimal </code>preference.</p>
<p>A preference of <code>return=representation</code> requests that the service invokes the request and returns the modified resource. The service MAY apply this preference by returning the representation of the successfully modified resource in the body of the response, formatted according to the rules specified for the requested <a href="#Formats">format</a>. In this case the service MAY include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header containing the <code>return=representation</code> preference.</p>
<p>The <code>return</code> preference SHOULD NOT be applied to a batch request, but MAY be applied to individual requests within a batch.</p>
<h4 id="8288-preference-respond-async"><a name="Preferencerespondasync" href="#Preferencerespondasync">8.2.8.8 Preference <code>respond-async</code></a></h4>
<p>The <code>respond-async </code>preference, as defined in <a href="#rfc7240">RFC7240</a>, allows clients to request that the service process the request asynchronously.</p>
<p>If the client has specified<code> respond-async</code> in the request, the service MAY process the request asynchronously and return a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response.</p>
<p>The <code>respond-async</code> preference MAY be used for batch requests, in which case it applies to the batch request as a whole and not to individual requests within the batch request.</p>
<p>In the case that the service applies the <code>respond-async</code> preference it MUST include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a><code> </code>response header containing the <code>respond-async</code> preference.</p>
<p>A service MAY specify the support for the <code>respond-async</code> preference using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#AsynchronousRequestsSupported"><code>Capabilities.AsynchronousRequestsSupported</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<div class="example">
<p>Example 9: a service receiving the following header might choose to respond</p>
<ul>
<li>asynchronously if the synchronous processing of the request will take longer than 10 seconds</li>
<li>synchronously after 5 seconds</li>
<li>asynchronously (ignoring the <a href="#Preferencewait"><code>wait</code></a> preference)</li>
<li>synchronously after 15 seconds (ignoring <code>respond-async</code> preference and the <a href="#Preferencewait"><code>wait</code></a> preference)</li>
</ul>
<pre><code>Prefer: respond-async, wait=10</code></pre>
</div>
<h4 id="8289-preference-track-changes-odatatrack-changes"><a name="Preferencetrackchangesodatatrackchanges" href="#Preferencetrackchangesodatatrackchanges">8.2.8.9 Preference <code>track-changes</code> (<code>odata.track-changes</code>)</a></h4>
<p>The <code>track-changes</code> preference is used to request that the service return a <a href="#DeltaLinks">delta link</a> that can subsequently be used to obtain <a href="#RequestingChanges">changes</a> (deltas) to this result. The syntax of the <code>track-changes</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>For <a href="#ServerDrivenPaging">paged results</a>, the preference MUST be specified on the initial request. Services MUST ignore the <a href="#Preferencetrackchangesodatatrackchanges"><code>track-changes</code></a> preference if applied to the next link.</p>
<p>The delta link MUST only be returned on the final page of results in place of the next link.</p>
<p>The service includes a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header in the first page of the response containing the <code>track-changes</code> preference to signal that changes are being tracked.</p>
<p>A service MAY specify the support for the <code>track-changes</code> preference using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#ChangeTracking"><code>Capabilities.ChangeTracking</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>The <code>track-changes</code> preference SHOULD NOT be applied to a batch request, but MAY be applied to individual requests within a batch.</p>
<p>Note: The <code>track-changes</code> preference was named <code>odata.track-changes</code> in OData version 4.0. Services that support the<code> track-changes</code> preference SHOULD also support <code>odata.track-changes</code> for OData 4.0 clients and clients SHOULD use <code>odata.track-changes</code> for compatibility with OData 4.0 services.</p>
<h4 id="82810-preference-wait"><a name="Preferencewait" href="#Preferencewait">8.2.8.10 Preference <code>wait</code></a></h4>
<p>The <code>wait</code> preference, as defined in <a href="#rfc7240">RFC7240</a>, is used to establish an upper bound on the length of time, in seconds, the client is prepared to wait for the service to process the request synchronously once it has been received.</p>
<p>If the <a href="#Preferencerespondasync"><code>respond-async</code></a> preference is also specified, the client requests that the service respond asynchronously after the specified length of time.</p>
<p>If the <code>respond-async</code> preference has not been specified, the service MAY interpret the <code>wait</code> as a request to timeout after the specified period of time.</p>
<p>If the <code>wait</code> preference is specified on an individual request within a batch, then it specifies the maximum amount of time to wait for that individual request. If the <code>wait</code> preference is specified on a batch, then it specifies the maximum time to wait for the entire batch.</p>
<h2 id="83-response-headers"><a name="ResponseHeaders" href="#ResponseHeaders">8.3 Response Headers</a></h2>
<p>In addition to the <a href="#CommonHeaders">Common Headers</a>, the following response headers have defined meaning in OData.</p>
<h3 id="831-header-asyncresult"><a name="HeaderAsyncResult" href="#HeaderAsyncResult">8.3.1 Header <code>AsyncResult</code></a></h3>
<p>A 4.01 service MUST include the <code>AsyncResult</code> header in <a href="#ResponseCode200OK"><code>200 OK</code></a> responses from a status monitor resource in order to indicate the final <a href="#CommonResponseStatusCodes">HTTP Response Status Code</a> of an <a href="#AsynchronousRequests">asynchronously executed request</a>. The header value is the three-digit HTTP response code, see <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>The <code>AsyncResult</code> header SHOULD NOT be applied to individual responses within a batch.</p>
<h3 id="832-header-etag"><a name="HeaderETag" href="#HeaderETag">8.3.2 Header <code>ETag</code></a></h3>
<p>A response MAY include an <code>ETag</code> header, see <a href="#rfc7232">RFC7232</a>. Services MUST include this header if they require an ETag to be specified when modifying the resource.</p>
<p>Services MUST support specifying the value returned in the <code>ETag</code> header in an <a href="#HeaderIfNoneMatch"><code>If-None-Match</code></a> header of a subsequent <a href="#RequestingData">Data Request</a> for the resource. Clients MUST specify the value returned in the <code>ETag</code> header, or star (<code>*</code>), in an <a href="#HeaderIfMatch"><code>If-Match</code></a> header of a subsequent <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a> in order to apply <a href="#UseofETagsforAvoidingUpdateConflicts">optimistic concurrency</a> control in updating, deleting, or invoking an action bound to the resource.</p>
<p>As OData allows multiple formats for representing the same structured information, services SHOULD use weak ETags that only depend on the representation-independent entity state. A strong ETag MUST change whenever the representation of an entity changes, so it has to depend on the <a href="#HeaderContentType"><code>Content-Type</code></a>, the <a href="#HeaderContentEncoding"><code>Content-Encoding</code></a>, and potentially other characteristics of the response.</p>
<p>An <code>ETag</code> header MAY also be returned on a <a href="#MetadataDocumentRequest">metadata document request</a> or <a href="#ServiceDocumentRequest">service document request</a> to allow the client subsequently to make a conditional request for the metadata or service document. Clients can also compare the value of the <code>ETag</code> header returned from a metadata document request to the metadata ETag returned in a response in order to verify the version of the metadata used to generate that response.</p>
<p>The <code>ETag</code> header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.</p>
<h3 id="833-header-location"><a name="HeaderLocation" href="#HeaderLocation">8.3.3 Header <code>Location</code></a></h3>
<p>The <code>Location</code> header MUST be returned in the response from a <a href="#CreateanEntity">Create Entity</a> or <a href="#CreateaMediaEntity">Create Media Entity</a> request to specify the edit URL, or for read-only entities the read URL, of the created entity, and in responses returning <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> to specify the URL that the client can use to request the status of an asynchronous request.</p>
<p>The <code>Location</code> header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.</p>
<h3 id="834-header-odata-entityid"><a name="HeaderODataEntityId" href="#HeaderODataEntityId">8.3.4 Header <code>OData-EntityId</code></a></h3>
<p>A response to a <a href="#CreateanEntity">create</a> or <a href="#UpsertanEntity">upsert</a> operation that returns <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> MUST include an <code>OData-EntityId</code> response header. The value of the header is the <a href="#EntityIdsandEntityReferences">entity-id</a> of the entity that was acted on by the request. The syntax of the <code>OData-EntityId</code> header is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>The <code>OData-EntityID</code> header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.</p>
<h3 id="835-header-odata-error"><a name="HeaderODataError" href="#HeaderODataError">8.3.5 Header <code>OData-Error</code></a></h3>
<p>A response with an <a href="#InStreamErrors">in-stream error</a> MAY include an <code>OData-Error</code> trailing header if the transport protocol supports trailing headers (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).</p>
<p>The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. <a href="#ODataJSON">OData-JSON</a>.</p>
<h3 id="836-header-preference-applied"><a name="HeaderPreferenceApplied" href="#HeaderPreferenceApplied">8.3.6 Header <code>Preference-Applied</code></a></h3>
<p>In a response to a request that specifies a <a href="#HeaderPrefer"><code>Prefer</code></a> header, a service MAY include a <code>Preference-Applied</code> header, as defined in <a href="#rfc7240">RFC7240</a>, specifying how individual preferences within the request were handled.</p>
<p>The value of the <code>Preference-Applied</code> header is a comma-separated list of preferences applied in the response. For more information on the individual preferences, see the <a href="#HeaderPrefer"><code>Prefer</code></a> header.</p>
<p>If the <code>Preference-Applied</code> header is specified on an individual response within a batch, then it specifies the preferences applied to that individual response. If the <code>Preference-Applied</code> header is specified on a batch response, then it specifies the preferences applied to the overall batch.</p>
<h3 id="837-header-retry-after"><a name="HeaderRetryAfter" href="#HeaderRetryAfter">8.3.7 Header <code>Retry-After</code></a></h3>
<p>A service MAY include a <code>Retry-After</code> header, as defined in <a href="#rfc7231">RFC7231</a>, in <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> and in <a href="#ResponseCode3xxRedirection"><code>3xx Redirect</code></a> responses</p>
<p>The <code>Retry-After</code> header specifies the duration of time, in seconds, that the client is asked to wait before retrying the request or issuing a request to the resource returned as the value of the <a href="#HeaderLocation"><code>Location</code> header</a>.</p>
<h3 id="838-header-vary"><a name="HeaderVary" href="#HeaderVary">8.3.8 Header <code>Vary</code></a></h3>
<p>If a response varies depending on the <a href="#HeaderODataVersion"><code>OData-Version</code></a> of the response, the service MUST include a <code>Vary</code> header listing the <a href="#HeaderODataMaxVersion"><code>OData-MaxVersion</code></a> request header field to allow correct caching of the response.</p>
<p>If a response varies depending on the applied preferences (<a href="#Preferenceallowentityreferencesodataallowentityreferences"><code>allow-entityreferences</code></a>, <a href="#Preferenceincludeannotationsodataincludeannotations"><code>include-annotations</code></a>, <a href="#Preferenceomitvalues"><code>omit-values</code></a><code>, </code><a href="#Preferencereturnrepresentationandreturnminimal"><code>return</code></a>), the service MUST include a <code>Vary</code> header listing the <a href="#HeaderPrefer"><code>Prefer</code></a> request header field to allow correct caching of the response.</p>
<p>Alternatively, the server MAY include a <code>Vary</code> header with the special value <code>*</code> as defined by <a href="#rfc7231">RFC7231</a>, Section 8.2.1. Note that this will make it impossible for a proxy to cache the response, see <a href="#rfc7240">RFC7240</a>.</p>
<hr />
<h1 id="9-common-response-status-codes"><a name="CommonResponseStatusCodes" href="#CommonResponseStatusCodes">9 Common Response Status Codes</a></h1>
<p>An OData service MAY respond to any request using any valid HTTP status code appropriate for the request. A service SHOULD be as specific as possible in its choice of HTTP status codes.</p>
<p>The following represent the most common success response codes. In some cases, a service MAY respond with a more specific success code.</p>
<h2 id="91-success-responses"><a name="SuccessResponses" href="#SuccessResponses">9.1 Success Responses</a></h2>
<p>The following response codes represent successful requests.</p>
<h3 id="911-response-code-200-ok"><a name="ResponseCode200OK" href="#ResponseCode200OK">9.1.1 Response Code <code>200 OK</code></a></h3>
<p>A request that does not create a resource returns <code>200 OK</code> if it is completed successfully and the value of the resource is not <code>null</code>. In this case, the response body MUST contain the value of the resource specified in the request URL.</p>
<h3 id="912-response-code-201-created"><a name="ResponseCode201Created" href="#ResponseCode201Created">9.1.2 Response Code <code>201 Created</code></a></h3>
<p>A <a href="#CreateanEntity">Create Entity</a>, <a href="#CreateaMediaEntity">Create Media Entity</a>, or <a href="#InvokinganAction">Invoke Action</a> request that successfully creates a resource returns <code>201 Created</code>. In this case, the response body MUST contain the resource created.</p>
<h3 id="913-response-code-202-accepted"><a name="ResponseCode202Accepted" href="#ResponseCode202Accepted">9.1.3 Response Code <code>202 Accepted</code></a></h3>
<p><code>202 Accepted</code> indicates that the <a href="#DataServiceRequests">Data Service Request</a> has been accepted and has not yet completed executing asynchronously. The asynchronous handling of requests is defined in the sections on <a href="#AsynchronousRequests">Asynchronous Requests</a> and <a href="#AsynchronousBatchRequests">Asynchronous Batch Requests</a>.</p>
<h3 id="914-response-code-204-no-content"><a name="ResponseCode204NoContent" href="#ResponseCode204NoContent">9.1.4 Response Code <code>204 No Content</code></a></h3>
<p>A request returns <code>204 No Content</code> if the requested resource has the <code>null</code> value, or if the service applies a <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=minimal</code> preference</a>. In this case, the response body MUST be empty.</p>
<p>As defined in <a href="#rfc7231">RFC7231</a>, a <a href="#DataModification">Data Modification Request</a> that responds with <code>204 No Content MAY </code>include an <code>ETag</code> header with a value reflecting the result of the data modification if and only if the client can reasonably "know" the new representation of the resource without actually receiving it. For a <code>PUT</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have been identical to the request body, i.e. no server-side modification of values sent in the request body, no server-calculated values etc. For a <code>PATCH</code> request this means that the response body of a corresponding <code>200 OK</code> or <code>201 Created</code> response would have consisted of all values sent in the request body, plus (for values not sent in the request body) server-side values corresponding to the <code>ETag</code> value sent in the <code>If-Match</code> header of the <code>PATCH</code> request, i.e. the previous values "known" to the client.</p>
<h3 id="915-response-code-3xx-redirection"><a name="ResponseCode3xxRedirection" href="#ResponseCode3xxRedirection">9.1.5 Response Code <code>3xx Redirection</code></a></h3>
<p>As per <a href="#rfc7231">RFC7231</a>, a <code>3xx Redirection</code> indicates that further action needs to be taken by the client in order to fulfill the request. In this case, the response SHOULD include a <a href="#HeaderLocation"><code>Location</code> header</a>, as appropriate, with the URL from which the result can be obtained; it MAY include a <a href="#HeaderRetryAfter"><code>Retry-After</code> header</a>.</p>
<h3 id="916-response-code-304-not-modified"><a name="ResponseCode304NotModified" href="#ResponseCode304NotModified">9.1.6 Response Code <code>304 Not Modified</code></a></h3>
<p>As per <a href="#rfc7232">RFC7232</a>, a <code>304 Not Modified</code> is returned when the client performs a <code>GET</code> request containing an <a href="#HeaderIfNoneMatch"><code>If-None-Match</code></a> header and the content has not changed. In this case the response SHOULD NOT include other headers in order to prevent inconsistencies between cached entity-bodies and updated headers.</p>
<p>The service MUST ensure that no observable change has occurred to the state of the service as a result of any request that returns a <code>304 Not Modified</code>.</p>
<h2 id="92-client-error-responses"><a name="ClientErrorResponses" href="#ClientErrorResponses">9.2 Client Error Responses</a></h2>
<p>Error codes in the <code>4xx</code> range indicate a client error, such as a malformed request.</p>
<p>The service MUST ensure that no observable change has occurred to the state of the service as a result of any request that returns an error status code.</p>
<p>In the case that a response body is defined for the error code, the body of the error is as defined for the appropriate <a href="#Formats">format</a>.</p>
<h3 id="921-response-code-404-not-found"><a name="ResponseCode404NotFound" href="#ResponseCode404NotFound">9.2.1 Response Code <code>404 Not Found</code></a></h3>
<p><code>404 Not Found </code>indicates that the resource specified by the request URL does not exist. The response body MAY provide additional information.</p>
<h3 id="922-response-code-405-method-not-allowed"><a name="ResponseCode405MethodNotAllowed" href="#ResponseCode405MethodNotAllowed">9.2.2 Response Code <code>405 Method Not Allowed</code></a></h3>
<p><code>405 Method Not Allowed</code> indicates that the resource specified by the request URL does not support the request method. In this case the response MUST include an <code>Allow</code> header containing a list of valid request methods for the requested resource as defined in <a href="#rfc7231">RFC7231</a>.</p>
<h3 id="923-response-code-406-not-acceptable"><a name="ResponseCode406NotAcceptable" href="#ResponseCode406NotAcceptable">9.2.3 Response Code <code>406 Not Acceptable</code></a></h3>
<p><code>406 Not Acceptable</code> indicates that the resource specified by the request URL does not have a current representation that would be acceptable for the client according to the request headers <a href="#HeaderAccept"><code>Accept</code></a>, <a href="#HeaderAcceptCharset"><code>Accept-Charset</code></a>, and <a href="#HeaderAcceptLanguage"><code>Accept-Language</code></a>, and that the service is unwilling to supply a default representation.</p>
<h3 id="924-response-code-410-gone"><a name="ResponseCode410Gone" href="#ResponseCode410Gone">9.2.4 Response Code <code>410 Gone</code></a></h3>
<p><code>410 Gone</code> indicates that the requested resource is no longer available. This can happen if a client has waited too long to follow a <a href="#DeltaLinks">delta link</a> or a <a href="#AsynchronousRequests">status-monitor-resource</a> link, or a next link on a collection that was requested with <a href="#HeaderIsolationODataIsolation">snapshot isolation</a>.</p>
<h3 id="925-response-code-412-precondition-failed"><a name="ResponseCode412PreconditionFailed" href="#ResponseCode412PreconditionFailed">9.2.5 Response Code <code>412 Precondition Failed</code></a></h3>
<p>As defined in <a href="#rfc7232">RFC7232</a>, <code>412 Precondition Failed</code> indicates that the client has performed a conditional request and the resource fails the condition. The service MUST ensure that no observable change occurs as a result of the request.</p>
<h3 id="926-response-code-424-failed-dependency"><a name="ResponseCode424FailedDependency" href="#ResponseCode424FailedDependency">9.2.6 Response Code <code>424 Failed Dependency</code></a></h3>
<p><code>424 Failed Dependency</code> indicates that a request was not performed due to a failed dependency; for example, a request within a batch that depended upon a request that failed.</p>
<h2 id="93-server-error-responses"><a name="ServerErrorResponses" href="#ServerErrorResponses">9.3 Server Error Responses</a></h2>
<p>As defined in <a href="#rfc7231">RFC7231</a>, error codes in the <code>5xx</code> range indicate service errors.</p>
<h3 id="931-response-code-501-not-implemented"><a name="ResponseCode501NotImplemented" href="#ResponseCode501NotImplemented">9.3.1 Response Code <code>501 Not Implemented</code></a></h3>
<p>If the client requests functionality not implemented by the OData Service, the service responds with <code>501 Not Implemented</code> and SHOULD include a response body describing the functionality not implemented.</p>
<h2 id="94-error-response-body"><a name="ErrorResponseBody" href="#ErrorResponseBody">9.4 Error Response Body</a></h2>
<p>The representation of an error response body is format-specific. It consists at least of the following information:</p>
<ul>
<li><code>code</code>: required non-null, non-empty, language-independent string. Its value is a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.</li>
<li><code>message</code>: required non-null, non-empty, language-dependent, human-readable string describing the error. The <a href="#HeaderContentLanguage"><code>Content-Language</code></a> header MUST contain the language code from <a href="#rfc5646">RFC5646</a> corresponding to the language in which the value for message is written.</li>
<li><code>target</code>: optional nullable, potentially empty string indicating the target of the error, for example, the name of the property in error.</li>
<li><code>details</code>: optional, potentially empty collection of structured instances with <code>code</code>, <code>message</code>, and <code>target</code> following the rules above.</li>
<li><code>innererror</code>: optional structured instance with service-defined content.</li>
</ul>
<p>Service implementations SHOULD carefully consider which information to include in production environments to guard against potential security concerns around information disclosure.</p>
<h2 id="95-in-stream-errors"><a name="InStreamErrors" href="#InStreamErrors">9.5 In-Stream Errors</a></h2>
<p>In the case that the service encounters an error after sending a success status to the client, the service MUST leave the response malformed according to its <a href="#HeaderContentType">content-type</a>. Clients MUST treat the entire response as being in error.</p>
<p>Services MAY include the header <a href="#HeaderODataError"><code>OData-Error</code></a> as a trailing header if supported by the transport protocol (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).</p>
<hr />
<h1 id="10-context-url"><a name="ContextURL" href="#ContextURL">10 Context URL</a></h1>
<p>The <em>context URL</em> describes the content of the payload. It consists of the canonical <a href="#MetadataDocumentRequest">metadata document URL</a> and a fragment identifying the relevant portion of the metadata document. The context URL makes response payloads "self-contained", allowing a recipient to retrieve metadata, resolve references, and construct canonical links omitted from response payloads in certain optimized formats.</p>
<p>Request payloads generally do not require context URLs as the type of the payload can generally be determined from the request URL.</p>
<p>For details on how the context URL is used to describe a payload, see the relevant sections in the particular format.</p>
<p>The following subsections describe how the context URL is constructed for each category of payload by providing a <em>context URL template</em>. The context URL template uses the following terms:</p>
<ul>
<li><code>{context-url}</code> is the canonical resource path to the <code>$metadata</code> document,</li>
<li><code>{entity-set}</code> is the name of an entity set or path to a containment navigation property,</li>
<li><code>{entity}</code> is the canonical URL for an entity,</li>
<li><code>{singleton}</code> is the canonical URL for a singleton entity,</li>
<li><code>{select-list}</code> is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions,</li>
<li><code>{property-path}</code> is the path to a structural property of the entity,</li>
<li><code>{type-name}</code> is a qualified type name,</li>
<li><code>{/type-name}</code> is an optional type-cast segment containing the qualified name of a derived or implemented type prefixed with a forward slash.</li>
</ul>
<p>The full grammar for the context URL is defined in <a href="#ODataABNF">OData-ABNF</a>. Note that the syntax of the context URL is independent of whatever URL conventions the service uses for addressing individual entities.</p>
<h2 id="101-service-document"><a name="ServiceDocument" href="#ServiceDocument">10.1 Service Document</a></h2>
<p>Context URL template:</p>
<pre><code>{context-url}</code></pre>
<p>The context URL of the service document is the metadata document URL of the service.</p>
<div class="example">
<p>Example 10: resource URL and corresponding context URL</p>
<pre><code>http://host/service/
http://host/service/$metadata</code></pre>
</div>
<h2 id="102-collection-of-entities"><a name="CollectionofEntities" href="#CollectionofEntities">10.2 Collection of Entities</a></h2>
<p>Context URL template:</p>
<pre><code>{context-url}#{entity-set}
{context-url}#Collection({type-name})</code></pre>
<p>If all entities in the collection are members of one entity set, its name is the context URL fragment.</p>
<div class="example">
<p>Example 11: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers
http://host/service/$metadata#Customers</code></pre>
</div>
<p>If the entities are contained, then <code>entity-set</code> is the top-level entity set or singleton followed by the path to the containment navigation property of the containing entity.</p>
<div class="example">
<p>Example 12: resource URL and corresponding context URL for contained entities</p>
<pre><code>http://host/service/Orders(4711)/Items
http://host/service/$metadata#Orders(4711)/Items</code></pre>
</div>
<p>If the entities in the response are not bound to a single entity set, such as from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL specifies the type of the returned entity collection.</p>
<h2 id="103-entity"><a name="Entity" href="#Entity">10.3 Entity</a></h2>
<p>Context URL template:</p>
<pre><code>{context-url}#{entity-set}/$entity
{context-url}#{type-name}</code></pre>
<p>If a response or response part is a single entity of the declared type of an entity set, <code>/$entity</code> is appended to the context URL.</p>
<div class="example">
<p>Example 13: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers(1)
http://host/service/$metadata#Customers/$entity</code></pre>
</div>
<p>If the entity is contained, then <code>entity-set</code> is the canonical URL for the containment navigation property of the containing entity, e.g. Orders(4711)/Items.</p>
<div class="example">
<p>Example 14: resource URL and corresponding context URL for contained entity</p>
<pre><code>http://host/service/Orders(4711)/Items(1)
http://host/service/$metadata#Orders(4711)/Items/$entity</code></pre>
</div>
<p>If the response is not bound to a single entity set, such as an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL specifies the type of the returned entity.</p>
<h2 id="104-singleton"><a name="Singleton" href="#Singleton">10.4 Singleton</a></h2>
<p>Context URL template:</p>
<pre><code>{context-url}#{singleton}</code></pre>
<p>If a response or response part is a singleton, its name is the context URL fragment.</p>
<div class="example">
<p>Example 15: resource URL and corresponding context URL</p>
<pre><code>http://host/service/MainSupplier`
http://host/service/$metadata#`MainSupplier</code></pre>
</div>
<h2 id="105-collection-of-derived-entities"><a name="CollectionofDerivedEntities" href="#CollectionofDerivedEntities">10.5 Collection of Derived Entities</a></h2>
<p>Context URL template:</p>
<pre><code>{context-url}#{entity-set}{/type-name}</code></pre>
<p>If an entity set consists exclusively of derived entities, a type-cast segment is added to the context URL.</p>
<div class="example">