-
Notifications
You must be signed in to change notification settings - Fork 1
/
odata-json-format.html
2128 lines (2123 loc) · 311 KB
/
odata-json-format.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) for representing and interacting with structured content is comprised of a set of specifications. The core specification for the protocol is in OData Version 4.02 Part 1: Protocol. This document extends the core specification by defining representations for OData requests and responses using a JSON format." />
<title>OData JSON Format Version 4.02</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-json-format-version-402">OData JSON Format Version 4.02</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-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.md">https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.md</a> (Authoritative)<br />
<a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.html">https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.html</a><br />
<a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.pdf">https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.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-json-format/v4.02/odata-json-format-v4.02.md">https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.md</a> (Authoritative)<br />
<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><br />
<a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.pdf">https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.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>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><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="related-work"><a name="RelatedWork">Related work:</a></h4>
<p>This specification replaces or supersedes:</p>
<ul>
<li>OData JSON Format Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Mark Biamonte. OASIS Standard. Latest stage: <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html">https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html</a>.</li>
<li>OData JSON Format Version 4.0. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. OASIS Standard. Latest stage: <a href="http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html">http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html</a>.</li>
</ul>
<p>This specification is related to:</p>
<ul>
<li><em>OData Version 4.02</em>. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes:
<ul>
<li><em>OData Version 4.02 Part 1: Protocol</em>. 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></li>
<li><em>OData Version 4.02 Part 2: URL Conventions</em>. Latest stage. <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html">https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html</a></li>
<li><em>ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases</em>. <a href="https://docs.oasis-open.org/odata/odata/v4.02/csd01/abnf/">https://docs.oasis-open.org/odata/odata/v4.02/csd01/abnf/</a></li>
</ul></li>
<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>
</ul>
<h4 id="abstract">Abstract:</h4>
<p>The Open Data Protocol (OData) for representing and interacting with structured content is comprised of a set of specifications. The core specification for the protocol is in OData Version 4.02 Part 1: Protocol. This document extends the core specification by defining representations for OData requests and responses using a JSON format.</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-JSON-Format-v4.02]</strong></p>
<p><em>OData JSON Format Version 4.02</em>. Edited by Ralf Handl, Michael Pizzo, and Heiko Theißen. 14 July 2023. OASIS Committee Specification Draft 01. <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.html">https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.html</a>. 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>.</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 <a href="#Notices">below</a>.</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="#JSONFormatDesign">2 JSON Format Design</a></li>
<li><a href="#RequestingtheJSONFormat">3 Requesting the JSON Format</a>
<ul>
<li><a href="#ControllingtheAmountofControlInformationinResponses">3.1 Controlling the Amount of Control Information in Responses</a>
<ul>
<li><a href="#metadataminimalodatametadataminimal">3.1.1 <code>metadata=minimal</code> (<code>odata.metadata=minimal</code>)</a></li>
<li><a href="#metadatafullodatametadatafull">3.1.2 <code>metadata=full</code> (<code>odata.metadata=full</code>)</a></li>
<li><a href="#metadatanoneodatametadatanone">3.1.3 <code>metadata=none</code> (<code>odata.metadata=none</code>)</a></li>
</ul></li>
<li><a href="#ControllingtheRepresentationofNumbers">3.2 Controlling the Representation of Numbers</a></li>
</ul></li>
<li><a href="#CommonCharacteristics">4 Common Characteristics</a>
<ul>
<li><a href="#HeaderContentType">4.1 Header Content-Type</a></li>
<li><a href="#MessageBody">4.2 Message Body</a></li>
<li><a href="#RelativeURLs">4.3 Relative URLs</a></li>
<li><a href="#PayloadOrderingConstraints">4.4 Payload Ordering Constraints</a></li>
<li><a href="#ControlInformation">4.5 Control Information</a>
<ul>
<li><a href="#ControlInformationcontextodatacontext">4.5.1 Control Information: <code>context</code> (<code>odata.context</code>)</a></li>
<li><a href="#ControlInformationmetadataEtagodatametadataEtag">4.5.2 Control Information: <code>metadataEtag</code> (<code>odata.metadataEtag</code>)</a></li>
<li><a href="#ControlInformationtypeodatatype">4.5.3 Control Information: <code>type</code> (<code>odata.type</code>)</a></li>
<li><a href="#ControlInformationcountodatacount">4.5.4 Control Information: <code>count</code> (<code>odata.count</code>)</a></li>
<li><a href="#ControlInformationnextLinkodatanextLink">4.5.5 Control Information: <code>nextLink</code> (<code>odata.nextLink</code>)</a></li>
<li><a href="#ControlInformationdeltaodatadelta">4.5.6 Control Information: <code>delta</code> (<code>odata.delta</code>)</a></li>
<li><a href="#ControlInformationdeltaLinkodatadeltaLink">4.5.7 Control Information: <code>deltaLink</code> (<code>odata.deltaLink</code>)</a></li>
<li><a href="#ControlInformationidodataid">4.5.8 Control Information: <code>id</code> (<code>odata.id</code>)</a></li>
<li><a href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.5.9 Control Information: <code>editLink</code> and <code>readLink</code> (<code>odata.editLink</code> and <code>odata.readLink</code>)</a></li>
<li><a href="#ControlInformationetagodataetag">4.5.10 Control Information: <code>etag</code> (<code>odata.etag</code>)</a></li>
<li><a href="#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink">4.5.11 Control Information: <code>navigationLink</code> and <code>associationLink</code> (<code>odata.navigationLink</code> and <code>odata.associationLink</code>)</a></li>
<li><a href="#ControlInformationmediaodatamedia">4.5.12 Control Information: <code>media*</code> (<code>odata.media*</code>)</a></li>
<li><a href="#ControlInformationremovedodataremoved">4.5.13 Control Information: <code>removed</code> (<code>odata.removed</code>)</a></li>
<li><a href="#ControlInformationcollectionAnnotationsodatacollectionAnnotations">4.5.14 Control Information: <code>collectionAnnotations</code> (<code>odata.collectionAnnotations</code>)</a></li>
</ul></li>
</ul></li>
<li><a href="#ServiceDocument">5 Service Document</a></li>
<li><a href="#Entity">6 Entity</a></li>
<li><a href="#StructuralProperty">7 Structural Property</a>
<ul>
<li><a href="#PrimitiveValue">7.1 Primitive Value</a></li>
<li><a href="#ComplexValue">7.2 Complex Value</a></li>
<li><a href="#CollectionofPrimitiveValues">7.3 Collection of Primitive Values</a></li>
<li><a href="#CollectionofComplexValues">7.4 Collection of Complex Values</a></li>
<li><a href="#UntypedValue">7.5 Untyped Value</a></li>
</ul></li>
<li><a href="#NavigationProperty">8 Navigation Property</a>
<ul>
<li><a href="#NavigationLink">8.1 Navigation Link</a></li>
<li><a href="#AssociationLink">8.2 Association Link</a></li>
<li><a href="#ExpandedNavigationProperty">8.3 Expanded Navigation Property</a></li>
<li><a href="#DeepInsert">8.4 Deep Insert</a></li>
<li><a href="#BindOperation">8.5 Bind Operation</a></li>
<li><a href="#CollectionETag">8.6 Collection ETag</a></li>
</ul></li>
<li><a href="#StreamProperty">9 Stream Property</a></li>
<li><a href="#MediaEntity">10 Media Entity</a></li>
<li><a href="#IndividualPropertyorOperationResponse">11 Individual Property or Operation Response</a></li>
<li><a href="#CollectionofOperationResponses">12 Collection of Operation Responses</a></li>
<li><a href="#CollectionofEntities">13 Collection of Entities</a></li>
<li><a href="#EntityReference">14 Entity Reference</a></li>
<li><a href="#DeltaPayload">15 Delta Payload</a>
<ul>
<li><a href="#DeltaResponses">15.1 Delta Responses</a></li>
<li><a href="#AddedChangedEntity">15.2 Added/Changed Entity</a></li>
<li><a href="#DeletedEntity">15.3 Deleted Entity</a></li>
<li><a href="#AddedLink">15.4 Added Link</a></li>
<li><a href="#DeletedLink">15.5 Deleted Link</a></li>
<li><a href="#UpdateaCollectionofEntities">15.6 Update a Collection of Entities</a></li>
</ul></li>
<li><a href="#BoundFunction">16 Bound Function</a></li>
<li><a href="#BoundAction">17 Bound Action</a></li>
<li><a href="#ActionInvocation">18 Action Invocation</a></li>
<li><a href="#BatchRequestsandResponses">19 Batch Requests and Responses</a>
<ul>
<li><a href="#BatchRequest">19.1 Batch Request</a></li>
<li><a href="#ReferencingNewEntities">19.2 Referencing New Entities</a></li>
<li><a href="#ReferencinganETag">19.3 Referencing an ETag</a></li>
<li><a href="#ProcessingaBatchRequest">19.4 Processing a Batch Request</a></li>
<li><a href="#BatchResponse">19.5 Batch Response</a></li>
<li><a href="#AsynchronousBatchRequests">19.6 Asynchronous Batch Requests</a></li>
</ul></li>
<li><a href="#InstanceAnnotations">20 Instance Annotations</a>
<ul>
<li><a href="#AnnotateaJSONObject">20.1 Annotate a JSON Object</a></li>
<li><a href="#AnnotateaJSONArrayorPrimitive">20.2 Annotate a JSON Array or Primitive</a></li>
<li><a href="#AnnotateaPrimitiveValuewithinaJSONArray">20.3 Annotate a Primitive Value within a JSON Array</a></li>
</ul></li>
<li><a href="#ErrorHandling">21 Error Handling</a>
<ul>
<li><a href="#ErrorResponse">21.1 Error Response</a></li>
<li><a href="#InStreamError">21.2 In-Stream Error</a></li>
<li><a href="#ErrorInformationinaSuccessPayload">21.3 Error Information in a Success Payload</a>
<ul>
<li><a href="#PrimitiveValueErrors">21.3.1 Primitive Value Errors</a></li>
<li><a href="#StructuredTypeErrors">21.3.2 Structured Type Errors</a></li>
<li><a href="#CollectionErrors">21.3.3 Collection Errors</a></li>
</ul></li>
</ul></li>
<li><a href="#Extensibility">22 Extensibility</a></li>
<li><a href="#Conformance">23 Conformance</a></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></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 OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in <a href="#ODataProtocol">OData-Protocol</a>; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using the JavaScript Object Notation (JSON), see [RFC8259].</p>
<p>An OData JSON payload may represent:</p>
<ul>
<li>a <a href="#PrimitiveValue">single primitive value</a></li>
<li>a <a href="#CollectionofPrimitiveValues">collection of primitive values</a></li>
<li>a <a href="#ComplexValue">single complex type value</a></li>
<li>a <a href="#CollectionofComplexValues">collection of complex type values</a></li>
<li>a <a href="#Entity">single entity</a> or <a href="#EntityReference">entity reference</a></li>
<li>a <a href="#CollectionofEntities">collection of entities</a> or <a href="#EntityReference">entity references</a></li>
<li>a <a href="#DeltaPayload">collection of changes</a></li>
<li>a <a href="#ServiceDocument">service document</a> describing the top-level resources exposed by the service</li>
<li>an <a href="#ErrorResponse">error</a>.</li>
</ul>
<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-json-format-v4.02-csd01.md</code>). Line breaks are added for readability only:</p>
<pre><code>pandoc -f gfm+tex_math_dollars+fenced_divs
-t html
-o odata-json-format-v4.02-csd01.html
-c styles/markdown-styles-v1.7.3b.css
-c styles/odata.css
-s
--mathjax
--eol=lf
--wrap=none
--metadata pagetitle="OData JSON Format Version 4.02"
odata-json-format-v4.02-csd01.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-json-format-design"><a name="JSONFormatDesign" href="#JSONFormatDesign">2 JSON Format Design</a></h1>
<p>JSON, as described in <a href="#rfc8259">RFC8259</a> defines a text format for serializing structured data. Objects are serialized as an unordered collection of name/value pairs.</p>
<p>JSON does not define any semantics around the name/value pairs that make up an object, nor does it define an extensibility mechanism for adding control information to a payload.</p>
<p>OData's JSON format extends JSON by defining general conventions for name/value pairs that annotate a JSON object, property or array. OData defines a set of canonical name/value pairs for control information such as ids, types, and links, and <a href="#InstanceAnnotations">instance annotations</a> MAY be used to add domain-specific information to the payload.</p>
<p>A key feature of OData's JSON format is to allow omitting predictable parts of the wire format from the actual payload. To reconstitute this data on the receiving end, expressions are used to compute missing links, type information, and other control data. These expressions (together with the data on the wire) can be used by the client to compute predictable payload pieces as if they had been included on the wire directly.</p>
<p>Control information is used in JSON to capture instance metadata that cannot be predicted (e.g. the next link of a collection) as well as a mechanism to provide values where a computed value would be wrong (e.g. if the media read link of one particular entity does not follow the standard URL conventions). Computing values from metadata expressions is compute intensive and some clients might opt for a larger payload size to avoid computational complexity; to accommodate for this the <code>Accept</code> header allows the client to control the amount of control information added to the response.</p>
<p>To optimize streaming scenarios, there are a few restrictions that MAY be imposed on the sequence in which name/value pairs appear within JSON objects. For details on the ordering requirements see <a href="#PayloadOrderingConstraints">Payload Ordering Constraints</a>.</p>
<hr />
<h1 id="3-requesting-the-json-format"><a name="RequestingtheJSONFormat" href="#RequestingtheJSONFormat">3 Requesting the JSON Format</a></h1>
<p>The OData JSON format can be requested using the <code>$format</code> query option in the request URL with the media type <code>application/json</code>, optionally followed by format parameters, or the case-insensitive abbreviation <code>json</code> which MUST NOT be followed by format parameters.</p>
<p>Alternatively, this format can be requested using the <code>Accept</code> header with the media type <code>application/json</code>, optionally followed by format parameters.</p>
<p>If specified, <code>$format</code> overrides any value specified in the <code>Accept</code> header.</p>
<p>Possible format parameters are:</p>
<ul>
<li><a href="#ControllingtheRepresentationofNumbers"><code>ExponentialDecimals</code></a></li>
<li><a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a></li>
<li><a href="#ControllingtheAmountofControlInformationinResponses"><code>metadata</code></a></li>
<li><a href="#PayloadOrderingConstraints"><code>streaming</code></a></li>
</ul>
<p>The names and values of these format parameters are case-insensitive.</p>
<p>Services SHOULD advertise the supported media types by annotating the 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> defined in <a href="#ODataVocCap">OData-VocCap</a>, listing all available formats and combinations of supported format parameters.</p>
<h2 id="31-controlling-the-amount-of-control-information-in-responses"><a name="ControllingtheAmountofControlInformationinResponses" href="#ControllingtheAmountofControlInformationinResponses">3.1 Controlling the Amount of Control Information in Responses</a></h2>
<p>The amount of <a href="#ControlInformation">control information</a> needed (or desired) in the payload depends on the client application and device. The <code>metadata</code> parameter can be applied to the <code>Accept</code> header of an OData request to influence how much control information will be included in the response.</p>
<p>Other <code>Accept</code> header parameters (e.g., <code>streaming</code>) are orthogonal to the <code>metadata</code> parameter and are therefore not mentioned in this section.</p>
<p>If a client prefers a very small wire size and is intelligent enough to compute data using metadata expressions, the <code>Accept</code> header should include <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a>. If computation is more critical than wire size or the client is incapable of computing control information, <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> directs the service to inline the control information that normally would be computed from metadata expressions in the payload. <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is an option for clients that have out-of-band knowledge or don't require control information.</p>
<p>In addition, the client may use the <code>include-annotations</code> preference in the <code>Prefer</code> header to request additional control information. Services supporting this MUST NOT omit control information required by the chosen <code>metadata</code> parameter, and services MUST NOT exclude the <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a>, <a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a>, and <a href="#ControlInformationcountodatacount"><code>count</code></a> if they are required by the response type.</p>
<p>If the client includes the <code>OData-MaxVersion</code> header in a request and does not specify the <code>metadata</code> format parameter in either the <code>Accept</code> header or <code>$format</code> query option, the service MUST return at least the <a href="#metadataminimalodatametadataminimal">minimal control information</a>.</p>
<p>Note that in OData 4.0 the <code>metadata</code> format parameter was prefixed with <code>odata.</code>. Payloads with an <code>OData-Version</code> header equal to <code>4.0</code> MUST include the <code>odata.</code> prefix. Payloads with an <code>OData-Version</code> header equal to <code>4.01</code> or greater SHOULD NOT include the <code>odata.</code> prefix.</p>
<h3 id="311-metadataminimal-odatametadataminimal"><a name="metadataminimalodatametadataminimal" href="#metadataminimalodatametadataminimal">3.1.1 <code>metadata=minimal</code> (<code>odata.metadata=minimal</code>)</a></h3>
<p>The <code>metadata=minimal</code> format parameter indicates that the service SHOULD remove computable control information from the payload wherever possible. The response payload MUST contain at least the following <a href="#ControlInformation">control information</a>:</p>
<ul>
<li><a href="#ControlInformationcontextodatacontext"><code>context</code></a>: the root context URL of the payload and the context URL for any deleted entries or added or deleted links in a delta response, or for entities or entity collections whose set cannot be determined from the root context URL</li>
<li><a href="#ControlInformationetagodataetag"><code>etag</code></a>: the ETag of the entity or collection, as appropriate</li>
<li><a href="#ControlInformationcountodatacount"><code>count</code></a>: the total count of a collection of entities or collection of entity references, if requested</li>
<li><a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a>: the next link of a collection with partial results</li>
<li><a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a>: the delta link for obtaining changes to the result, if requested</li>
</ul>
<p>In addition, control information MUST appear in the payload for cases where actual values are not the same as the computed values and MAY appear otherwise. When control information appears in the payload, it is treated as exceptions to the computed values.</p>
<p>Media entities and stream properties MAY in addition contain the following control information:</p>
<ul>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaEtag</code></a>: the ETag of the stream, as appropriate</li>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a>: the media type of the stream</li>
</ul>
<h3 id="312-metadatafull-odatametadatafull"><a name="metadatafullodatametadatafull" href="#metadatafullodatametadatafull">3.1.2 <code>metadata=full</code> (<code>odata.metadata=full</code>)</a></h3>
<p>The <code>metadata=full</code> format parameter indicates that the service MUST include all control information explicitly in the payload.</p>
<p>The full list of control information that may appear in a <code>metadata=full</code> response is as follows:</p>
<ul>
<li><a href="#ControlInformationcontextodatacontext"><code>context</code></a>: the context URL for a collection, entity, primitive value, or service document.</li>
<li><a href="#ControlInformationcountodatacount"><code>count</code></a>: the total count of a collection of entities or collection of entity references, if requested.</li>
<li><a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a>: the next link of a collection with partial results</li>
<li><a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a>: the delta link for obtaining changes to the result, if requested</li>
<li><a href="#ControlInformationidodataid"><code>id</code></a>: the ID of the entity</li>
<li><a href="#ControlInformationetagodataetag"><code>etag</code></a>: the ETag of the entity or collection, as appropriate</li>
<li><a href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink"><code>readLink</code></a>: the link used to read the entity, if the edit link cannot be used to read the entity</li>
<li><a href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink"><code>editLink</code></a>: the link used to edit/update the entity, if the entity is updatable and the <code>id</code> does not represent a URL that can be used to edit the entity</li>
<li><a href="#NavigationLink"><code>navigationLink</code></a>: the link used to retrieve the values of a navigation property</li>
<li><a href="#AssociationLink"><code>associationLink</code></a>: the link used to describe the relationship between this entity and related entities</li>
<li><a href="#ControlInformationtypeodatatype"><code>type</code></a>: the type of the containing object or targeted property if the type of the object or targeted property cannot be heuristically determined from the data value, see section "<a href="#ControlInformationtypeodatatype">Control Information: type (odata.type)</a>".</li>
</ul>
<p>Media entities and stream properties may in addition contain the following control information:</p>
<ul>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaReadLink</code></a>: the link used to read the stream</li>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaEditLink</code></a>: the link used to edit/update the stream</li>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaEtag</code></a>: the ETag of the stream, as appropriate</li>
<li><a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a>: the media type of the stream</li>
</ul>
<h3 id="313-metadatanone-odatametadatanone"><a name="metadatanoneodatametadatanone" href="#metadatanoneodatametadatanone">3.1.3 <code>metadata=none</code> (<code>odata.metadata=none</code>)</a></h3>
<p>The <code>metadata=none</code> format parameter indicates that the service SHOULD omit control information other than <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> and <a href="#ControlInformationcountodatacount"><code>count</code></a>. This control information MUST continue to be included, as applicable, even in the <code>metadata=none</code> case.</p>
<p>It is not valid to specify <code>metadata=none</code> on a <a href="#DeltaPayload">delta request</a>.</p>
<h2 id="32-controlling-the-representation-of-numbers"><a name="ControllingtheRepresentationofNumbers" href="#ControllingtheRepresentationofNumbers">3.2 Controlling the Representation of Numbers</a></h2>
<p>The <code>IEEE754Compatible=true</code> format parameter indicates that the service MUST serialize <code>Edm.Int64</code> and <code>Edm.Decimal</code> numbers (including the <a href="#ControlInformationcountodatacount"><code>count</code></a>, if requested) as strings. This is in conformance with <a href="#rfc7493">RFC7493</a>.</p>
<p>If not specified, or specified as <code>IEEE754Compatible=false</code>, all numbers MUST be serialized as JSON numbers.</p>
<p>This enables support for JavaScript numbers that are defined to be 64-bit binary format IEEE 754 values (see <strong>[<a href="#ECMAScript">ECMAScript</a>, <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-4.3.19">section 4.3.1.9</a>]</strong>) resulting in integers losing precision past 15 digits, and decimals losing precision due to the conversion from base 10 to base 2.</p>
<p>OData JSON request and response payloads that format <code>Edm.Int64</code> and <code>Edm.Decimal</code> values as strings MUST specify this format parameter in the media type sent in the <a href="#HeaderContentType"><code>Content-Type</code></a> header.</p>
<p>Services producing responses without format parameter <code>IEEE754Compatible=true</code> which are unable to produce exact JSON numbers MAY serialize <code>Edm.Int64</code> and <code>Edm.Decimal</code> numbers with a rounded/inexact value as a JSON number and annotate that value with an instance annotation with term <code>Core.ValueException</code> defined in <a href="#ODataVocCore">OData-VocCore</a> containing the exact value as a string. This situation can for example happen if the client only accepts <code>application/json</code> without any format parameters and the service is written in JavaScript.</p>
<p>For payloads with an <code>OData-Version</code> header equal to <code>4.0</code> the <code>ExponentialDecimals=true</code> format parameter indicates that the service MAY serialize <code>Edm.Decimal</code> numbers in exponential notation (e.g. <code>1e-6</code> instead of <code>0.000001</code>).</p>
<p>The sender of a request MUST specify <code>ExponentialDecimals=true</code> in the <code>Content-Type</code> header if the request body contains <code>Edm.Decimal</code> values in exponential notation.</p>
<p>If not specified, or specified as <code>ExponentialDecimals=false</code>, all <code>Edm.Decimal</code> values MUST be serialized in long notation, using only an optional sign, digits, and an optional decimal point followed by digits.</p>
<p>Payloads with an <code>OData-Version</code> header equal to <code>4.01</code> or greater always allow exponential notation for numbers and the <code>ExponentialDecimals</code> format parameter is not needed or used.</p>
<hr />
<h1 id="4-common-characteristics"><a name="CommonCharacteristics" href="#CommonCharacteristics">4 Common Characteristics</a></h1>
<p>This section describes common characteristics of the representation for OData values in JSON. A request or response body consists of several parts. It contains OData values as part of a larger document. Requests and responses are structured almost identical; the few existing differences will be explicitly called out in the respective subsections.</p>
<h2 id="41-header-content-type"><a name="HeaderContentType" href="#HeaderContentType">4.1 Header Content-Type</a></h2>
<p>Requests and responses with a JSON message body MUST have a <code>Content-Type</code> header value of <code>application/json</code>.</p>
<p>Requests MAY add the <code>charset</code> parameter to the content type. Allowed values are <code>UTF-8</code>,<code> UTF-16</code>, and <code>UTF-32</code>. If no <code>charset</code> parameter is present, <code>UTF-8</code> MUST be assumed.</p>
<p>Responses MUST include the <a href="#ControllingtheAmountofControlInformationinResponses"><code>metadata</code></a> parameter to specify the amount of metadata included in the response.</p>
<p>Requests and responses MUST include the <a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a> parameter if <code>Edm.Int64</code> and <code>Edm.Decimal</code> numbers are represented as strings.</p>
<p>Requests and responses MAY add the <code>streaming</code> parameter with a value of <code>true</code> or <code>false</code>, see section "<a href="#PayloadOrderingConstraints">Payload Ordering Constraints</a>".</p>
<h2 id="42-message-body"><a name="MessageBody" href="#MessageBody">4.2 Message Body</a></h2>
<p>Each message body is represented as a single JSON object. This object is either the representation of an <a href="#Entity">entity</a>, an <a href="#EntityReference">entity reference</a> or a <a href="#ComplexValue">complex type instance</a>, or it contains a name/value pair whose name MUST be <code>value</code> and whose value is the correct representation for a <a href="#PrimitiveValue">primitive value</a>, a <a href="#CollectionofPrimitiveValues">collection of primitive values</a>, a <a href="#CollectionofComplexValues">collection of complex values</a>, a <a href="#CollectionofEntities">collection of entities</a>, or a collection of objects that represent <a href="#DeltaPayload">changes to a previous result</a>.</p>
<p>Client libraries MUST retain the order of objects within an array in JSON responses.</p>
<h2 id="43-relative-urls"><a name="RelativeURLs" href="#RelativeURLs">4.3 Relative URLs</a></h2>
<p>URLs present in a payload (whether request or response) MAY be represented as relative URLs.</p>
<p>Relative URLs, other than those in <a href="#ControlInformationtypeodatatype"><code>type</code></a>, are relative to their base URL, which is</p>
<ul>
<li>the <a href="#ControlInformationcontextodatacontext">context URL</a> of the same JSON object, if one exists, otherwise</li>
<li>the context URL of the enclosing object, if one exists, otherwise</li>
<li>the context URL of the next enclosing object, if one exists, etc. until the document root, otherwise</li>
<li>the request URL.</li>
</ul>
<p>For context URLs, these rules apply starting with the second bullet point.</p>
<p>Within the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information, relative URLs are relative to the base type URL, which is</p>
<ul>
<li>the <code>type</code> of the enclosing object, if one exists, otherwise</li>
<li>the <code>type</code> of the next enclosing object, if one exists, etc. until the document root, otherwise</li>
<li>the context URL of the document root, if one exists, otherwise</li>
<li>the request URL.</li>
</ul>
<p>Processors expanding the URLs MUST use normal URL expansion rules as defined in <a href="#rfc3986">RFC3986</a>. This means that if the base URL is a context URL, the part starting with <code>$metadata#</code> is ignored when resolving the relative URL.</p>
<p>Clients that receive relative URLs in response payloads SHOULD use the same relative URLs, where appropriate, in request payloads (such as <a href="#BindOperation">bind operations</a> and batch requests) and in system query options (such as <code>$id</code>).</p>
<p>URLs represented as a string within a JSON payload, including <a href="#BatchRequest">batch requests</a>, must follow standard OData encoding rules. For relative URLs this means that colons in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the scheme separator. Colons within the query part, i.e. after the question mark character (<code>?</code>), need not be percent-encoded.</p>
<div class="example">
<p>Example 2:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@editLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')"</span><span class="fu">,</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@navigationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Orders"</span><span class="fu">,</span></span>
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>The resulting absolute URLs are <code>http://host/service/Customers('ALFKI')</code> and <code>http://host/service/Customers('ALFKI')/Orders</code>.</p>
<h2 id="44-payload-ordering-constraints"><a name="PayloadOrderingConstraints" href="#PayloadOrderingConstraints">4.4 Payload Ordering Constraints</a></h2>
<p>Ordering constraints MAY be imposed on the JSON payload in order to support streaming scenarios. These ordering constraints MUST only be assumed if explicitly specified as some clients (and services) might not be able to control, or might not care about, the order of the JSON properties in the payload.</p>
<p>Clients can request that a JSON response conform to these ordering constraints by specifying a media type of <code>application/json</code> with the <code>streaming=true</code> parameter in the <code>Accept</code> header or <code>$format</code> query option. Services MUST return <code>406 Not Acceptable</code> if the client only requests streaming and the service does not support it.</p>
<p>Clients may specify the <code>streaming=true</code> parameter in the <code>Content-Type</code> header of requests to indicate that the request body follows the payload ordering constraints. In the absence of this parameter, the service must assume that the JSON properties in the request are unordered.</p>
<p>Processors MUST only assume streaming support if it is explicitly indicated in the <code>Content-Type</code> header via the <code>streaming=true</code> parameter.</p>
<div class="example">
<p>Example 3: a payload with</p>
<pre><code>Content-Type: application/json;metadata=minimal;streaming=true</code></pre>
<p>can be assumed to support streaming, whereas a payload with</p>
<pre><code>Content-Type: application/json;metadata=minimal</code></pre>
<p>cannot be assumed to support streaming.</p>
</div>
<p>JSON producers are encouraged to follow the payload ordering constraints whenever possible (and include the <code>streaming=true</code> content-type parameter) to support the maximum set of client scenarios.</p>
<p>To support streaming scenarios the following payload ordering constraints have to be met:</p>
<ul>
<li>If present, the <code>context</code> control information MUST be the first property in the JSON object.</li>
<li>The <code>type</code> control information, if present, MUST appear next in the JSON object.</li>
<li>The <code>id</code> and <code>etag</code> control information MUST appear before any property, property annotation, or property control information.</li>
<li>All annotations or control information for a structural or navigation property MUST appear as a group immediately before the property itself. The one exception is the <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> of a collection which MAY appear after the collection it annotates.</li>
<li>All other control information can appear anywhere in the payload as long as it does not violate any of the above rules.</li>
<li>For 4.0 payloads, annotations and control information for navigation properties MUST appear after all structural properties. 4.01 clients MUST NOT assume this ordering.</li>
</ul>
<p>Note that in OData 4.0 the <code>streaming</code> format parameter was prefixed with <code>odata.</code>. Payloads with an <code>OData-Version</code> header equal to <code>4.0</code> MUST include the <code>odata.</code> prefix. Payloads with an <code>OData-Version</code> header equal to <code>4.01</code> or greater SHOULD NOT include the <code>odata.</code> prefix.</p>
<h2 id="45-control-information"><a name="ControlInformation" href="#ControlInformation">4.5 Control Information</a></h2>
<p>In addition to the "pure data" a message body MAY contain <a href="#InstanceAnnotations">annotations</a> and control information that is represented as name/value pairs whose names start with <code>@</code>.</p>
<p>In requests and responses with an <code>OData-Version</code> header with a value of <code>4.0</code> control information names are prefixed with <code>@odata.</code>, e.g. <code>@odata.context</code>. In requests and responses without such a header the <code>odata.</code> prefix SHOULD be omitted, e.g. <code>@context</code>.</p>
<p>In some cases, control information is required in request payloads; this is called out in the following subsections.</p>
<p>Receivers that encounter unknown annotations in any namespace or unknown control information MUST NOT stop processing and MUST NOT signal an error.</p>
<h3 id="451-control-information-context-odatacontext"><a name="ControlInformationcontextodatacontext" href="#ControlInformationcontextodatacontext">4.5.1 Control Information: <code>context</code> (<code>odata.context</code>)</a></h3>
<p>The <code>context</code> control information returns the context URL (see <a href="#ODataProtocol">OData-Protocol</a>) for the payload. This URL can be absolute or <a href="#RelativeURLs">relative</a>.</p>
<p>The <code>context</code> control information is not returned if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested. Otherwise it MUST be the first property of any JSON response.</p>
<p>The <code>context</code> control information MUST also be included in requests and responses for entities whose entity set cannot be determined from the context URL of the collection.</p>
<p>For more information on the format of the context URL, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
<p>Request payloads MAY include a context URL as a base URL for <a href="#RelativeURLs">relative URLs</a> in the request payload.</p>
<div class="example">
<p>Example 4:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@metadataEtag"</span><span class="fu">:</span> <span class="st">"W/</span><span class="ch">\"</span><span class="st">A1FF3E230954908F</span><span class="ch">\"</span><span class="st">"</span><span class="fu">,</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h3 id="452-control-information-metadataetag-odatametadataetag"><a name="ControlInformationmetadataEtagodatametadataEtag" href="#ControlInformationmetadataEtagodatametadataEtag">4.5.2 Control Information: <code>metadataEtag</code> (<code>odata.metadataEtag</code>)</a></h3>
<p>The <code>metadataEtag</code> control information MAY appear in a response in order to specify the entity tag (ETag) that can be used to determine the version of the metadata of the response. If an ETag is returned when requesting the metadata document, then the service SHOULD set the <code>metadataEtag</code> control information to the metadata document's ETag in all responses when using <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> or <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a>. If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the <code>metadataEtag</code> control information in any responses.</p>
<p>For details on how ETags are used, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
<h3 id="453-control-information-type-odatatype"><a name="ControlInformationtypeodatatype" href="#ControlInformationtypeodatatype">4.5.3 Control Information: <code>type</code> (<code>odata.type</code>)</a></h3>
<p>The <code>type</code> control information specifies the type of a JSON object or name/value pair. Its value is a URI that identifies the type of the property or object. For built-in primitive types the value is the unqualified name of the primitive type. For payloads described by an <code>OData-Version</code> header with a value of <code>4.0</code>, this name MUST be prefixed with the hash symbol (<code>#</code>); for non-OData 4.0 payloads, built-in primitive type values SHOULD be represented without the hash symbol, but consumers of 4.01 or greater payloads MUST support values with or without the hash symbol. For all other types, the URI may be absolute or relative to the <code>type</code> of the containing object. The root <code>type</code> may be absolute or relative to the root <a href="#ControlInformationcontextodatacontext">context URL</a>.</p>
<p>If the URI references a metadata document (that is, it's not just a fragment), it MAY refer to a specific version of that metadata document using the <code>$schemaversion</code> system query option defined in <a href="#ODataProtocol">OData-Protocol</a>.</p>
<p>For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI fragment. For properties that represent a collection of values, the fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with <code>Collection</code>. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
<p>The <code>type</code> control information MUST appear in requests and in responses with <a href="#metadataminimalodatametadataminimal">minimal</a> or <a href="#metadatafullodatametadatafull">full</a> metadata, if the type cannot be heuristically determined, as described below, and one of the following is true:</p>
<ul>
<li>The type is derived from the type specified for the (collection of) entities or (collection of) complex type instances, or</li>
<li>The type is for a property whose type is not declared in <code>$metadata</code>.</li>
</ul>
<p>It MAY appear in other cases in requests and responses if its value does not contradict the type declared in <code>$metadata</code>.</p>
<p>The following heuristics are used to determine the primitive type of a dynamic property in the absence of the <code>type</code> control information:</p>
<ul>
<li>Boolean values have a first-class representation in JSON and do not need any additional control information.</li>
<li>Numeric values have a first-class representation in JSON but are not further distinguished, so they include a <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information unless their type is <code>Double</code>.</li>
<li>The special floating-point values <code>-INF</code>, <code>INF</code>, and <code>NaN </code>are serialized as strings and MUST have a <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information to specify the numeric type of the property.</li>
<li>String values do have a first class representation in JSON, but there is an obvious collision: OData also encodes a number of other primitive types as strings, e.g. <code>DateTimeOffset</code>, <code>Int64</code> in the presence of the <a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a> format parameter etc. If a property appears in JSON string format, it should be treated as a string value unless the property is known (from the metadata document) to have a different type.</li>
</ul>
<p>For more information on namespace- and alias-qualified names, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
<div class="example">
<p>Example 5: entity of type <code>Model.VipCustomer</code> defined in the metadata document of the same service with a dynamic property of type <code>Edm.Date</code></p>
<div class="sourceCode" id="cb7"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Model.VipCustomer"</span><span class="fu">,</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">2</span><span class="fu">,</span></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DynamicValue@type"</span><span class="fu">:</span> <span class="st">"Date"</span><span class="fu">,</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DynamicValue"</span><span class="fu">:</span> <span class="st">"2016-09-22"</span><span class="fu">,</span></span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<div class="example">
<p>Example 6: entity of type <code>Model.VipCustomer</code> defined in the metadata<code> </code>document of a different service</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"http://host/alternate/$metadata#Model.VipCustomer"</span><span class="fu">,</span></span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">2</span><span class="fu">,</span></span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h3 id="454-control-information-count-odatacount"><a name="ControlInformationcountodatacount" href="#ControlInformationcountodatacount">4.5.4 Control Information: <code>count</code> (<code>odata.count</code>)</a></h3>
<p>The <code>count</code> control information occurs only in responses and can annotate any collection, see <a href="#ODataProtocol">OData-Protocol</a> section 11.2.5.5 System Query Option <code>$count</code>. Its value is an <code>Edm.Int64</code> value corresponding to the total count of members in the collection represented by the request.</p>
<h3 id="455-control-information-nextlink-odatanextlink"><a name="ControlInformationnextLinkodatanextLink" href="#ControlInformationnextLinkodatanextLink">4.5.5 Control Information: <code>nextLink</code> (<code>odata.nextLink</code>)</a></h3>
<p>The <code>nextLink</code> control information indicates that a response is only a subset of the requested collection. It contains a URL that allows retrieving the next subset of the requested collection.</p>
<p>This control information can also be applied to <a href="#ExpandedNavigationProperty">expanded to-many navigation properties</a>.</p>
<h3 id="456-control-information-delta-odatadelta"><a name="ControlInformationdeltaodatadelta" href="#ControlInformationdeltaodatadelta">4.5.6 Control Information: <code>delta</code> (<code>odata.delta</code>)</a></h3>
<p>The <code>delta</code> control information is applied to a collection-valued navigation property within an <a href="#AddedChangedEntity">added/changed entity</a> in a delta payload to represent changes in membership or value of nested entities.</p>
<h3 id="457-control-information-deltalink-odatadeltalink"><a name="ControlInformationdeltaLinkodatadeltaLink" href="#ControlInformationdeltaLinkodatadeltaLink">4.5.7 Control Information: <code>deltaLink</code> (<code>odata.deltaLink</code>)</a></h3>
<p>The <code>deltaLink</code> control information contains a URL that can be used to retrieve changes to the current set of results. The <code>deltaLink</code> control information MUST only appear on the last page of results. A page of results MUST NOT have both a <code>deltaLink</code> control information and a <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> control information.</p>
<h3 id="458-control-information-id-odataid"><a name="ControlInformationidodataid" href="#ControlInformationidodataid">4.5.8 Control Information: <code>id</code> (<code>odata.id</code>)</a></h3>
<p>The <code>id</code> control information contains the entity-id, see <a href="#ODataProtocol">OData-Protocol</a>. By convention the entity-id is identical to the canonical URL of the entity, as defined in <a href="#ODataURL">OData-URL</a>.</p>
<p>The <code>id </code>control information MUST appear in responses if <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> is requested, or if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is requested and any of a non-transient entity's key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity after</p>
<ul>
<li>IRI-to-URI conversion as defined in <a href="#rfc3987">RFC3987</a>,</li>
<li>relative resolution as defined in section 5.2 of <a href="#rfc3986">RFC3986</a>, and</li>
<li>percent-encoding normalization as defined in section 6 of <a href="#rfc3986">RFC3986</a>.</li>
</ul>
<p>Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the <code>id</code> MUST be included if it does not match convention for the localized key values. If the <code>id</code> is represented, it MAY be a <a href="#RelativeURLs">relative URL</a>.</p>
<p>If the entity is transient (i.e. cannot be read or updated), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 payloads transient entities need not have the <code>id</code> control information, and 4.01 clients MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities.</p>
<p>The <code>id</code> control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.</p>
<p>Entities with <code>id</code> equal to <code>null</code> cannot be compared to other entities, reread, or updated. If <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is specified and the <code>id</code> is not present in the entity, then the canonical URL MUST be used as the entity-id.</p>
<h3 id="459-control-information-editlink-and-readlink-odataeditlink-and-odatareadlink"><a name="ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink" href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.5.9 Control Information: <code>editLink</code> and <code>readLink</code> (<code>odata.editLink</code> and <code>odata.readLink</code>)</a></h3>
<p>The <code>editLink</code> control information contains the edit URL of the entity; see <a href="#ODataProtocol">OData-Protocol</a>.</p>
<p>The <code>readLink</code> control information contains the read URL of the entity or collection; see <a href="#ODataProtocol">OData-Protocol</a>.</p>
<p>The <code>editLink</code> and <code>readLink</code> control information is ignored in request payloads and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
<p>The default value of both the edit URL and read URL is the entity's <a href="#ControlInformationidodataid">entity-id</a> appended with a cast segment to the type of the entity if its type is derived from the declared type of the entity set. If neither the <code>editLink</code> nor the <code>readLink</code> control information is present in an entity, the client uses this default value for the edit URL.</p>
<p>For updatable entities:</p>
<ul>
<li>The <code>editLink</code> control information is written if <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> is requested or if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is requested and the edit URL differs from the default value of the edit URL.</li>
<li>The <code>readLink</code> control information is written if the read URL is different from the edit URL. If no <code>readLink</code> control information is present, the read URL is identical to the edit URL.</li>
</ul>
<p>For read-only entities:</p>
<ul>
<li>The <code>readLink</code> control information is written if <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> is requested or if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is requested and its value differs from the default value of the read URL.</li>
<li>The <code>readLink</code> control information may also be written if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is specified in order to signal that an individual entity is read-only.</li>
</ul>
<p>For collections:</p>
<ul>
<li>The <code>readLink</code> control information, if written, MUST be the request URL that produced the collection.</li>
<li>The <code>editLink</code> control information MUST NOT be written as its meaning in this context is reserved for future versions of this specification.</li>
</ul>
<h3 id="4510-control-information-etag-odataetag"><a name="ControlInformationetagodataetag" href="#ControlInformationetagodataetag">4.5.10 Control Information: <code>etag</code> (<code>odata.etag</code>)</a></h3>
<p>The <code>etag</code> control information MAY be applied to an <a href="#Entity">entity</a> or collection in a response. The value of the control information is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity or collection has changed.</p>
<p>For details on how ETags are used, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
<p>The <code>etag</code> control information is ignored in request payloads for single entities and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
<h3 id="4511-control-information-navigationlink-and-associationlink-odatanavigationlink-and-odataassociationlink"><a name="ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink" href="#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink">4.5.11 Control Information: <code>navigationLink</code> and <code>associationLink</code> (<code>odata.navigationLink</code> and <code>odata.associationLink</code>)</a></h3>
<p>The <code>navigationLink</code> control information in a response contains a <em>navigation URL</em> that can be used to retrieve an entity or collection of entities related to the current entity via a <a href="#NavigationProperty">navigation property</a>.</p>
<p>The <em>default computed value of a navigation URL</em> is the value of the <a href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">read URL</a> appended with a segment containing the name of the navigation property. The service MAY omit the <code>navigationLink</code> control information if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> has been specified on the request and the navigation link matches this computed value.</p>
<p>The <code>associationLink</code> control information in a response contains an <em>association URL</em> that can be used to retrieve a reference to an entity or a collection of references to entities related to the current entity via a navigation property.</p>
<p>The <em>default computed value of an association URL</em> is the value of the navigation URL appended with <code>/$ref</code>. The service MAY omit the <code>associationLink</code> control information if the association link matches this computed value.</p>
<p>The <code>navigationLink</code> and <code>associationLink</code> control information is ignored in request payloads and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
<h3 id="4512-control-information-media-odatamedia"><a name="ControlInformationmediaodatamedia" href="#ControlInformationmediaodatamedia">4.5.12 Control Information: <code>media*</code> (<code>odata.media*</code>)</a></h3>
<p>For <a href="#MediaEntity">media entities</a> and <a href="#StreamProperty">stream properties</a> at least one of the control information <code>mediaEditLink</code> and <code>mediaReadLink</code> MUST be included in responses if they don't follow standard URL conventions as defined in <a href="#ODataURL">OData-URL</a>, sections 4.6 Addressing a property and 4.14 Addressing the Media Stream of a Media Entity, or if <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> is requested.</p>
<p>The <code>mediaEditLink</code> control information contains a URL that can be used to update the binary stream associated with the media entity or stream property. It MUST be included for updatable streams if it differs from standard URL conventions relative to the edit link of the entity.</p>
<p>The <code>mediaReadLink</code> control information contains a URL that can be used to read the binary stream associated with the media entity or stream property. It MUST be included if its value differs from the value of the associated <code>mediaEditLink</code>, if present, or if it doesn't follow standard URL conventions relative to the read link of the entity and the associated <code>mediaEditLink</code> is not present.</p>
<p>The <code>mediaContentType </code>control information MAY be included; its value SHOULD match the media type of the binary stream represented by the <code>mediaReadLink</code> URL. This is only a hint; the actual media type will be included in the <code>Content-Type</code> header when the resource is requested.</p>
<p>The <code>mediaEtag</code> control information MAY be included; its value is the ETag of the binary stream represented by this media entity or stream property.</p>
<p>The <code>media*</code> control information is not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
<p>If a stream property is provided inline in a request, the <code>mediaContentType</code> control information may be specified.</p>
<p>If a stream property is annotated with <code>Capabilities.MediaLocationUpdateSupported</code> (see <a href="#ODataVocCap">OData-VocCap</a>) and a value of <code>true</code>, clients MAY specify the <code>mediaEditLink</code> and/or <code>mediaReadLink</code> control information for that stream property in order to change the association between the stream property and a media stream.</p>
<p>In all other cases <code>media*</code> control information is ignored in request payloads.</p>
<div class="example">
<p>Example 7:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Employees/$entity"</span><span class="fu">,</span></span>
<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@mediaReadLink"</span><span class="fu">:</span> <span class="st">"Employees(1)/$value"</span><span class="fu">,</span></span>
<span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@mediaContentType"</span><span class="fu">:</span> <span class="st">"image/jpeg"</span><span class="fu">,</span></span>
<span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb9-6"><a href="#cb9-6" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb9-7"><a href="#cb9-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h3 id="4513-control-information-removed-odataremoved"><a name="ControlInformationremovedodataremoved" href="#ControlInformationremovedodataremoved">4.5.13 Control Information: <code>removed</code> (<code>odata.removed</code>)</a></h3>
<p>The <code>removed</code> control information is used in <a href="#DeletedEntity">delta payloads</a> and indicates that the represented entity is (to be) deleted.</p>
<h3 id="4514-control-information-collectionannotations-odatacollectionannotations"><a name="ControlInformationcollectionAnnotationsodatacollectionAnnotations" href="#ControlInformationcollectionAnnotationsodatacollectionAnnotations">4.5.14 Control Information: <code>collectionAnnotations</code> (<code>odata.collectionAnnotations</code>)</a></h3>
<p>The <code>collectionAnnotations</code> control information can be applied to a collection containing primitive members in order to annotate such primitive members. The value of the <code>collectionAnnotations</code> control information is an array of JSON objects containing an integer property <code>index</code>, specifying the zero-based ordinal index of the primitive item within the collection, along with any annotations that are to be applied to that primitive collection member.</p>
<div class="example">
<p>Example 8: Annotating primitive values within a collection</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Employees/$entity"</span><span class="fu">,</span></span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"EmailAddresses@collectionAnnotations"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"index"</span><span class="fu">:</span> <span class="dv">0</span><span class="fu">,</span></span>
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@emailType"</span><span class="fu">:</span> <span class="st">"Personal"</span></span>
<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"index"</span><span class="fu">:</span> <span class="dv">2</span><span class="fu">,</span></span>
<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@emailType"</span><span class="fu">:</span> <span class="st">"Work"</span></span>
<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"EmailAddresses"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a> <span class="st">"Julie@Swansworth.com"</span><span class="ot">,</span></span>
<span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a> <span class="st">"JulieSwa@live.com"</span><span class="ot">,</span></span>
<span id="cb10-17"><a href="#cb10-17" aria-hidden="true" tabindex="-1"></a> <span class="st">"Julie.Swansworth@work.com"</span></span>
<span id="cb10-18"><a href="#cb10-18" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb10-19"><a href="#cb10-19" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb10-20"><a href="#cb10-20" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<hr />
<h1 id="5-service-document"><a name="ServiceDocument" href="#ServiceDocument">5 Service Document</a></h1>
<p>A service document in JSON is represented as a single JSON object with at least the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information and a property <code>value</code>.</p>
<p>The value of the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information MUST be the URL of the metadata document, without any fragment part.</p>
<p>The value of the <code>value</code> property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of <code>true</code> for the attribute <code>IncludeInServiceDocument</code> and each singleton exposed by the service, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
<p>Each element MUST be a JSON object with at least two name/value pairs, one with name <code>name</code> containing the name of the entity set, function import, or singleton, and one with name <code>url</code> containing the URL of the entity set, which may be an absolute or a <a href="#RelativeURLs">relative URL</a>. It MAY contain a name/value pair with name <code>title</code> containing a human-readable, language-dependent title for the object.</p>
<p>JSON objects representing an entity set MAY contain an additional name/value pair with name <code>kind</code> and a value of <code>EntitySet</code>. If the <code>kind</code> name/value pair is not present, the object MUST represent an entity set.</p>
<p>JSON objects representing a function import MUST contain the <code>kind</code> name/value pair with a value of <code>FunctionImport</code>.</p>
<p>JSON objects representing a singleton MUST contain the <code>kind</code> name/value pair with a value of <code>Singleton</code>.</p>
<p>JSON objects representing a related service document MUST contain the <code>kind</code> name/value pair with a value of <code>ServiceDocument</code>.</p>
<p>Clients that encounter unknown values of the <code>kind</code> name/value pair not defined in this version of the specification MUST NOT stop processing and MUST NOT signal an error.</p>
<p>Service documents MAY contain <a href="#InstanceAnnotations">annotations</a> in any of its JSON objects. Services MUST NOT produce name/value pairs other than the ones explicitly defined in this section, and clients MUST ignore unknown name/value pairs.</p>
<div class="example">
<p>Example 9:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata"</span><span class="fu">,</span></span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"value"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"name"</span><span class="fu">:</span> <span class="st">"Orders"</span><span class="fu">,</span></span>
<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"kind"</span><span class="fu">:</span> <span class="st">"EntitySet"</span><span class="fu">,</span></span>
<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"url"</span><span class="fu">:</span> <span class="st">"Orders"</span></span>
<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"name"</span><span class="fu">:</span> <span class="st">"OrderItems"</span><span class="fu">,</span></span>
<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Order Details"</span><span class="fu">,</span></span>
<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"url"</span><span class="fu">:</span> <span class="st">"OrderItems"</span></span>
<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb11-14"><a href="#cb11-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb11-15"><a href="#cb11-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"name"</span><span class="fu">:</span> <span class="st">"TopProducts"</span><span class="fu">,</span></span>
<span id="cb11-16"><a href="#cb11-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Best-Selling Products"</span><span class="fu">,</span></span>
<span id="cb11-17"><a href="#cb11-17" aria-hidden="true" tabindex="-1"></a> <span class="dt">"kind"</span><span class="fu">:</span> <span class="st">"FunctionImport"</span><span class="fu">,</span></span>
<span id="cb11-18"><a href="#cb11-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">"url"</span><span class="fu">:</span> <span class="st">"TopProducts"</span></span>
<span id="cb11-19"><a href="#cb11-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb11-20"><a href="#cb11-20" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb11-21"><a href="#cb11-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">"name"</span><span class="fu">:</span> <span class="st">"MainSupplier"</span><span class="fu">,</span></span>
<span id="cb11-22"><a href="#cb11-22" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Main Supplier"</span><span class="fu">,</span></span>
<span id="cb11-23"><a href="#cb11-23" aria-hidden="true" tabindex="-1"></a> <span class="dt">"kind"</span><span class="fu">:</span> <span class="st">"Singleton"</span><span class="fu">,</span></span>
<span id="cb11-24"><a href="#cb11-24" aria-hidden="true" tabindex="-1"></a> <span class="dt">"url"</span><span class="fu">:</span> <span class="st">"MainSupplier"</span></span>
<span id="cb11-25"><a href="#cb11-25" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb11-26"><a href="#cb11-26" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb11-27"><a href="#cb11-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">"name"</span><span class="fu">:</span> <span class="st">"Human Resources"</span><span class="fu">,</span></span>
<span id="cb11-28"><a href="#cb11-28" aria-hidden="true" tabindex="-1"></a> <span class="dt">"kind"</span><span class="fu">:</span> <span class="st">"ServiceDocument"</span><span class="fu">,</span></span>
<span id="cb11-29"><a href="#cb11-29" aria-hidden="true" tabindex="-1"></a> <span class="dt">"url"</span><span class="fu">:</span> <span class="st">"http://host/HR/"</span></span>
<span id="cb11-30"><a href="#cb11-30" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb11-31"><a href="#cb11-31" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb11-32"><a href="#cb11-32" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<hr />
<h1 id="6-entity"><a name="Entity" href="#Entity">6 Entity</a></h1>
<p>An entity is serialized as a JSON object. It MAY contain <a href="#ControlInformationcontextodatacontext"><code>context</code></a>, <a href="#ControlInformationtypeodatatype"><code>type</code></a>, or <a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a> control information.</p>
<p>Each <a href="#StructuralProperty">property</a> to be transmitted is represented as a name/value pair within the object. The order properties appear within the object is considered insignificant.</p>
<p>An entity in a payload may be a complete entity, a projected entity (see <em>System Query Option</em> <code>$select</code> in <a href="#ODataProtocol">OData-Protocol</a>), or a partial entity update (see <em>Update an Entity</em> in <a href="#ODataProtocol">OData-Protocol</a>).</p>
<p>An entity representation can be (modified and) round-tripped to the service directly. The <a href="#ControlInformationcontextodatacontext">context URL</a> is used in requests only as a base for <a href="#RelativeURLs">relative URLs</a>.</p>
<div class="example">
<p>Example 10: entity with <code>metadata=minimal</code></p>
<div class="sourceCode" id="cb12"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ContactName"</span><span class="fu">:</span> <span class="st">"Maria Anders"</span><span class="fu">,</span></span>
<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ContactTitle"</span><span class="fu">:</span> <span class="st">"Sales Representative"</span><span class="fu">,</span></span>
<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Phone"</span><span class="fu">:</span> <span class="st">"030-0074321"</span><span class="fu">,</span></span>
<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Fax"</span><span class="fu">:</span> <span class="st">"030-0076545"</span><span class="fu">,</span></span>
<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Address"</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Street"</span><span class="fu">:</span> <span class="st">"Obere Str. 57"</span><span class="fu">,</span></span>
<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"City"</span><span class="fu">:</span> <span class="st">"Berlin"</span><span class="fu">,</span></span>
<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Region"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"PostalCode"</span><span class="fu">:</span> <span class="st">"D-12209"</span></span>
<span id="cb12-14"><a href="#cb12-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb12-15"><a href="#cb12-15" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<p>Example 11: entity with <code>metadata=full</code></p>
<div class="sourceCode" id="cb13"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')"</span><span class="fu">,</span></span>
<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@etag"</span><span class="fu">:</span> <span class="st">"W/</span><span class="ch">\"</span><span class="st">MjAxMy0wNS0yN1QxMTo1OFo=</span><span class="ch">\"</span><span class="st">"</span><span class="fu">,</span></span>
<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@editLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')"</span><span class="fu">,</span></span>
<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ContactName"</span><span class="fu">:</span> <span class="st">"Maria Anders"</span><span class="fu">,</span></span>
<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ContactTitle"</span><span class="fu">:</span> <span class="st">"Sales Representative"</span><span class="fu">,</span></span>
<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Phone"</span><span class="fu">:</span> <span class="st">"030-0074321"</span><span class="fu">,</span></span>
<span id="cb13-11"><a href="#cb13-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Fax"</span><span class="fu">:</span> <span class="st">"030-0076545"</span><span class="fu">,</span></span>
<span id="cb13-12"><a href="#cb13-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Address"</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb13-13"><a href="#cb13-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Street"</span><span class="fu">:</span> <span class="st">"Obere Str. 57"</span><span class="fu">,</span></span>
<span id="cb13-14"><a href="#cb13-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"City"</span><span class="fu">:</span> <span class="st">"Berlin"</span><span class="fu">,</span></span>
<span id="cb13-15"><a href="#cb13-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Region"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
<span id="cb13-16"><a href="#cb13-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">"PostalCode"</span><span class="fu">:</span> <span class="st">"D-12209"</span><span class="fu">,</span></span>
<span id="cb13-17"><a href="#cb13-17" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Country@associationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Address/Country/$ref"</span><span class="fu">,</span></span>
<span id="cb13-18"><a href="#cb13-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Country@navigationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Address/Country"</span></span>
<span id="cb13-19"><a href="#cb13-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
<span id="cb13-20"><a href="#cb13-20" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@associationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Orders/$ref"</span><span class="fu">,</span></span>
<span id="cb13-21"><a href="#cb13-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@navigationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Orders"</span></span>
<span id="cb13-22"><a href="#cb13-22" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<hr />
<h1 id="7-structural-property"><a name="StructuralProperty" href="#StructuralProperty">7 Structural Property</a></h1>
<p>A property within an entity or complex type instance is represented as a name/value pair. The name MUST be the name of the property; a non-null value is represented depending on its type as a <a href="#PrimitiveValue">primitive value</a>, a <a href="#ComplexValue">complex value</a>, a <a href="#CollectionofPrimitiveValues">collection of primitive values</a>, or a <a href="#CollectionofComplexValues">collection of complex values</a>.</p>
<p>Null values are represented as the JSON literal <code>null</code>.</p>
<h2 id="71-primitive-value"><a name="PrimitiveValue" href="#PrimitiveValue">7.1 Primitive Value</a></h2>
<p>Primitive values are represented following the rules of <a href="#rfc8259">RFC8259</a>.</p>
<p>Values of type <code>Edm.Boolean</code> are represented as the JSON literals <code>true</code> and <code>false</code></p>
<p>Values of types <code>Edm.Byte</code>, <code>Edm.SByte</code>, <code>Edm.Int16</code>, <code>Edm.Int32</code>, <code>Edm.Int64</code>, <code>Edm.Single</code>, <code>Edm.Double</code>, and <code>Edm.Decimal</code> are represented as JSON numbers, except for <code>-INF</code>, <code>INF</code>, and <code>NaN</code> which are represented as strings.</p>
<p>Values of type <code>Edm.String</code> are represented as JSON strings, using the JSON string escaping rules.</p>
<p>Values of type <code>Edm.Binary</code>, <code>Edm.Date</code>, <code>Edm.DateTimeOffset</code>, <code>Edm.Duration</code>, <code>Edm.Guid</code>, and <code>Edm.TimeOfDay</code> are represented as JSON strings whose content satisfies the rules <code>binaryValue</code>, <code>dateValue</code>, <code>dateTimeOffsetValue</code>, <code>durationValue</code>, <code>guidValue</code>, and <code>timeOfDayValue</code> respectively, in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>Primitive values that cannot be represented, for example due to server conversion issues or IEEE754 limitations on the size of an <code>Edm.Int64</code> or <code>Edm.Decimal</code> value, are annotated with the <code>Core.ValueException</code> term. In this case, the payload MAY include an approximation of the value and MAY specify a string representation of the exact value in the <code>value</code> property of the annotation.</p>
<p>Enumeration values are represented as JSON strings whose content satisfies the rule <code>enumValue</code> in <a href="#ODataABNF">OData-ABNF</a>. The preferred representation is the <code>enumerationMember</code>. If no <code>enumerationMember</code> (or combination of named enumeration members) is available, the <code>enumMemberValue</code> representation may be used.</p>
<p>Geography and geometry values are represented as geometry types as defined in <a href="#rfc7946">RFC7946</a>, with the following modifications:</p>
<ul>
<li>Keys SHOULD be ordered with type first, then coordinates, then any other keys</li>
<li>If the optional <a href="http://geojson.org/geojson-spec.html#named-crs">CRS object</a> is present, it MUST be of type <code>name</code>, where the value of the <code>name</code> member of the contained <code>properties</code> object is an EPSG SRID legacy identifier, see [<a href="#GeoJSON-2008">GeoJSON-2008</a>].</li>
</ul>
<p>Geography and geometry types have the same representation in a JSON payload. Whether the value represents a geography type or geometry type is inferred from its usage or specified using the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information.</p>
<div class="example">
<p>Example 12:</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"NullValue"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"TrueValue"</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></span>
<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FalseValue"</span><span class="fu">:</span> <span class="kw">false</span><span class="fu">,</span></span>
<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"BinaryValue"</span><span class="fu">:</span> <span class="st">"T0RhdGE"</span><span class="fu">,</span></span>
<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"IntegerValue"</span><span class="fu">:</span> <span class="dv">-128</span><span class="fu">,</span></span>
<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DoubleValue"</span><span class="fu">:</span> <span class="fl">3.1415926535897931</span><span class="fu">,</span></span>
<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"SingleValue"</span><span class="fu">:</span> <span class="st">"INF"</span><span class="fu">,</span></span>
<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DecimalValue"</span><span class="fu">:</span> <span class="fl">34.95</span><span class="fu">,</span></span>
<span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"StringValue"</span><span class="fu">:</span> <span class="st">"Say </span><span class="ch">\"</span><span class="st">Hello</span><span class="ch">\"</span><span class="st">,</span><span class="ch">\n</span><span class="st">then go"</span><span class="fu">,</span></span>
<span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DateValue"</span><span class="fu">:</span> <span class="st">"2012-12-03"</span><span class="fu">,</span></span>
<span id="cb14-12"><a href="#cb14-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DateTimeOffsetValue"</span><span class="fu">:</span> <span class="st">"2012-12-03T07:16:23Z"</span><span class="fu">,</span></span>
<span id="cb14-13"><a href="#cb14-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DurationValue"</span><span class="fu">:</span> <span class="st">"P12DT23H59M59.999999999999S"</span><span class="fu">,</span></span>
<span id="cb14-14"><a href="#cb14-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"TimeOfDayValue"</span><span class="fu">:</span> <span class="st">"07:59:59.999"</span><span class="fu">,</span></span>
<span id="cb14-15"><a href="#cb14-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"GuidValue"</span><span class="fu">:</span> <span class="st">"01234567-89ab-cdef-0123-456789abcdef"</span><span class="fu">,</span></span>
<span id="cb14-16"><a href="#cb14-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Int64Value"</span><span class="fu">:</span> <span class="dv">0</span><span class="fu">,</span></span>
<span id="cb14-17"><a href="#cb14-17" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ColorEnumValue"</span><span class="fu">:</span> <span class="st">"Yellow"</span><span class="fu">,</span></span>
<span id="cb14-18"><a href="#cb14-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">"GeographyPoint"</span><span class="fu">:</span> <span class="fu">{</span><span class="dt">"type"</span><span class="fu">:</span> <span class="st">"Point"</span><span class="fu">,</span> <span class="dt">"coordinates"</span><span class="fu">:</span> <span class="ot">[</span><span class="fl">142.1</span><span class="ot">,</span><span class="fl">64.1</span><span class="ot">]</span><span class="fu">}</span></span>
<span id="cb14-19"><a href="#cb14-19" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="72-complex-value"><a name="ComplexValue" href="#ComplexValue">7.2 Complex Value</a></h2>
<p>A complex value is represented as a single JSON object containing one name/value pair for each property that makes up the complex type. Each property value is formatted as appropriate for the type of the property.</p>
<p>It MAY have name/value pairs for <a href="#InstanceAnnotations">instance annotations</a> and control information.</p>
<div class="example">
<p>Example 13:</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Address"</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Street"</span><span class="fu">:</span> <span class="st">"Obere Str. 57"</span><span class="fu">,</span></span>
<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"City"</span><span class="fu">:</span> <span class="st">"Berlin"</span><span class="fu">,</span></span>
<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Region"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"PostalCode"</span><span class="fu">:</span> <span class="st">"D-12209"</span></span>
<span id="cb15-9"><a href="#cb15-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb15-10"><a href="#cb15-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>A complex value with no selected properties, or no defined properties (such as an empty open complex type or complex type with no structural properties) is represented as an empty JSON object.</p>
<h2 id="73-collection-of-primitive-values"><a name="CollectionofPrimitiveValues" href="#CollectionofPrimitiveValues">7.3 Collection of Primitive Values</a></h2>
<p>A collection of primitive values is represented as a JSON array; each element in the array is the representation of a <a href="#PrimitiveValue">primitive value</a>. A JSON literal <code>null</code> represents a null value within the collection. An empty collection is represented as an empty array.</p>
<div class="example">
<p>Example 14: partial collection of strings with next link</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"EmailAddresses"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a> <span class="st">"Julie@Swansworth.com"</span><span class="ot">,</span></span>
<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a> <span class="st">"Julie.Swansworth@work.com"</span></span>
<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb16-8"><a href="#cb16-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"EmailAddresses@nextLink"</span><span class="fu">:</span> <span class="st">"..."</span></span>
<span id="cb16-9"><a href="#cb16-9" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="74-collection-of-complex-values"><a name="CollectionofComplexValues" href="#CollectionofComplexValues">7.4 Collection of Complex Values</a></h2>
<p>A collection of complex values is represented as a JSON array; each element in the array is the representation of a <a href="#ComplexValue">complex value</a>. A JSON literal <code>null</code> represents a null value within the collection. An empty collection is represented as an empty array.</p>
<div class="example">
<p>Example 15: partial collection of complex values with next link</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"PhoneNumbers"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Number"</span><span class="fu">:</span> <span class="st">"425-555-1212"</span><span class="fu">,</span></span>
<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Type"</span><span class="fu">:</span> <span class="st">"Home"</span></span>
<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb17-7"><a href="#cb17-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb17-8"><a href="#cb17-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Model.CellPhoneNumber"</span><span class="fu">,</span></span>
<span id="cb17-9"><a href="#cb17-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Number"</span><span class="fu">:</span> <span class="st">"425-555-0178"</span><span class="fu">,</span></span>
<span id="cb17-10"><a href="#cb17-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Type"</span><span class="fu">:</span> <span class="st">"Cell"</span><span class="fu">,</span></span>
<span id="cb17-11"><a href="#cb17-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Carrier"</span><span class="fu">:</span> <span class="st">"Sprint"</span></span>
<span id="cb17-12"><a href="#cb17-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb17-13"><a href="#cb17-13" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb17-14"><a href="#cb17-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"PhoneNumbers@nextLink"</span><span class="fu">:</span> <span class="st">"..."</span></span>
<span id="cb17-15"><a href="#cb17-15" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="75-untyped-value"><a name="UntypedValue" href="#UntypedValue">7.5 Untyped Value</a></h2>
<p>OData 4.01 adds the built-in abstract types <code>Edm.Untyped</code> and <code>Collection(Edm.Untyped)</code>that services can use to advertise in metadata that there is a property of a particular name present, but there is no type to describe the structure of the property's values.</p>
<p>The value of an <code>Edm.Untyped</code> property MAY be a primitive value, a structural value, or a collection. If a collection, it may contain any combination of primitive values, structural values, and collections.</p>
<p>The value of a property of type <code>Collection(Edm.Untyped)</code>MUST be a collection, and it MAY contain any combination of primitive values, structural values, and collections.</p>
<p>Untyped values are the only place where a collection can directly contain a collection, or a collection can contain a mix of primitive values, structural values, and collections.</p>
<p>All children of an untyped property are assumed to be untyped unless they are annotated with the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information, in which case they MUST conform to the type described by the control information.</p>
<hr />
<h1 id="8-navigation-property"><a name="NavigationProperty" href="#NavigationProperty">8 Navigation Property</a></h1>
<p>A navigation property is a reference from a source entity to zero or more related entities.</p>
<h2 id="81-navigation-link"><a name="NavigationLink" href="#NavigationLink">8.1 Navigation Link</a></h2>
<p>The navigation link for a navigation property is represented as a <a href="#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink"><code>navigationLink</code></a> control information on the navigation property. Its value is an absolute or <a href="#RelativeURLs">relative URL</a> that allows retrieving the related entity or collection of entities.</p>
<p>The navigation link for a navigation property is only represented if the client requests <code>metadata=full</code> or the navigation link cannot be computed, e.g. if it is within a collection of complex type instances. If it is represented it MUST immediately precede the expanded navigation property if the latter is represented.</p>
<div class="example">
<p>Example 16:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@navigationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Orders"</span><span class="fu">,</span></span>
<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="82-association-link"><a name="AssociationLink" href="#AssociationLink">8.2 Association Link</a></h2>
<p>The association link for a navigation property is represented as an <a href="#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink"><code>associationLink</code></a> control information on the navigation property. Its value is an absolute or <a href="#RelativeURLs">relative URL</a> that can be used to retrieve the reference or collection of references to the related entity or entities.</p>
<p>The association link for a navigation property is only represented if the client requests <code>metadata=full</code> or the association link cannot be computed by appending <code>/$ref</code> to the navigation link. If it is represented, it MUST immediately precede the navigation link if the latter is represented, otherwise it MUST immediately precede the expanded navigation property if it is represented.</p>
<div class="example">
<p>Example 17:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@associationLink"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/Orders/$ref"</span><span class="fu">,</span></span>
<span id="cb19-5"><a href="#cb19-5" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb19-6"><a href="#cb19-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="83-expanded-navigation-property"><a name="ExpandedNavigationProperty" href="#ExpandedNavigationProperty">8.3 Expanded Navigation Property</a></h2>
<p>An expanded navigation property is represented as a name/value pair where the name is the name of the navigation property, and the value is the representation of the related entity or collection of entities.</p>
<p>If at most one entity can be related, the value is the representation of the related entity, or <code>null</code> if no entity is currently related.</p>
<p>If a collection of entities can be related, it is represented as a JSON array. Each element is the <a href="#Entity">representation of an entity</a> or the <a href="#EntityReference">representation of an entity reference</a>. An empty collection of entities (one that contains no entities) is represented as an empty JSON array. The navigation property MAY include <a href="#ControlInformationcontextodatacontext"><code>context</code></a>, <a href="#ControlInformationtypeodatatype"><code>type</code></a>, <a href="#ControlInformationcountodatacount"><code>count</code></a>, or <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> control information. If a navigation property is expanded with the suffix <code>/$count</code>, only the <a href="#ControlInformationcountodatacount"><code>count</code></a> control information is represented.</p>
<div class="example">
<p>Example 18:</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Customers/$entity"</span><span class="fu">,</span></span>
<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@count"</span><span class="fu">:</span> <span class="dv">42</span><span class="fu">,</span></span>
<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders"</span><span class="fu">:</span> <span class="ot">[</span> <span class="er">...</span> <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Orders@nextLink"</span><span class="fu">:</span> <span class="st">"..."</span><span class="fu">,</span></span>
<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="84-deep-insert"><a name="DeepInsert" href="#DeepInsert">8.4 Deep Insert</a></h2>
<p>When inserting a new entity with a <code>POST</code> request, related new entities MAY be specified using the same representation as for an <a href="#ExpandedNavigationProperty">expanded navigation property</a>.</p>
<p>Deep inserts are not allowed in update operations using <code>PUT</code> or <code>PATCH</code> requests.</p>
<div class="example">
<p>Example 19: inserting a new order for a new customer with order items related to existing products:</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">11643</span><span class="fu">,</span></span>
<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Amount"</span><span class="fu">:</span> <span class="dv">100</span><span class="fu">,</span></span>
<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span><span class="fu">,</span></span>
<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Customer"</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"ANEWONE"</span><span class="fu">,</span></span>
<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Items"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Product"</span><span class="fu">:</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(28)"</span> <span class="fu">},</span></span>
<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Quantity"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Product"</span><span class="fu">:</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(39)"</span> <span class="fu">},</span></span>
<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Quantity"</span><span class="fu">:</span> <span class="dv">5</span><span class="fu">,</span></span>
<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb21-19"><a href="#cb21-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb21-20"><a href="#cb21-20" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb21-21"><a href="#cb21-21" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<h2 id="85-bind-operation"><a name="BindOperation" href="#BindOperation">8.5 Bind Operation</a></h2>
<p>When inserting or updating an entity, relationships of navigation properties MAY be inserted or updated via bind operations.</p>
<p>For requests containing an <code>OData-Version</code> header with a value of <code>4.0</code>, a bind operation is encoded as a property control information <code>odata.bind</code> on the navigation property it belongs to and has a single value for single-valued navigation properties or an array of values for collection navigation properties. For nullable single-valued navigation properties the value <code>null</code> may be used to remove the relationship.</p>
<div class="example">
<p>Example 20: assign an existing product to an existing category with a partial update request against the product</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">http://host/service/Products(42)</span> <span class="er">HTTP/1.1</span></span>
<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb22-5"><a href="#cb22-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Category@odata.bind"</span><span class="fu">:</span> <span class="st">"Categories(6)"</span></span>
<span id="cb22-6"><a href="#cb22-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>The values are the <a href="#ControlInformationidodataid">ids</a> of the related entities. They MAY be absolute or <a href="#RelativeURLs">relative URLs</a>.</p>
<p>For requests containing an <code>OData-Version</code> header with a value of <code>4.01</code>, a relationship is bound to an existing entity using the same representation as for an <a href="#EntityReference">expanded entity reference</a>.</p>
<div class="example">
<p>Example 21: assign an existing product to an existing category with a partial update request against the product</p>
<div class="sourceCode" id="cb23"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">http://host/service/Products(42)</span> <span class="er">HTTP/1.1</span></span>
<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb23-4"><a href="#cb23-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb23-5"><a href="#cb23-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Category"</span><span class="fu">:</span> <span class="fu">{</span><span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Categories(6)"</span><span class="fu">}</span></span>
<span id="cb23-6"><a href="#cb23-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<div class="example">
<p>Example 22: submit a partial update request to:</p>
<ul>
<li>modify the name of an existing category</li>
<li>assign an existing product with the id 42 to the category</li>
<li>assign an existing product 57 to the category and update its name</li>
<li>create a new product named "Wedges" and assign it to the category</li>
</ul>
<p>At the end of the request, the updated category contains exactly the three specified products.</p>
<div class="sourceCode" id="cb24"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">http://host/service/Categories(6)</span> <span class="er">HTTP/1.1</span></span>
<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb24-4"><a href="#cb24-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb24-5"><a href="#cb24-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
<span id="cb24-6"><a href="#cb24-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb24-7"><a href="#cb24-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb24-8"><a href="#cb24-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(42)"</span></span>
<span id="cb24-9"><a href="#cb24-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb24-10"><a href="#cb24-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb24-11"><a href="#cb24-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span><span class="fu">,</span></span>
<span id="cb24-12"><a href="#cb24-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Widgets"</span></span>
<span id="cb24-13"><a href="#cb24-13" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb24-14"><a href="#cb24-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
<span id="cb24-15"><a href="#cb24-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Wedges"</span></span>
<span id="cb24-16"><a href="#cb24-16" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb24-17"><a href="#cb24-17" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb24-18"><a href="#cb24-18" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>OData 4.01 services MUST support both the OData 4.0 representation, for requests containing an <code>OData-Version</code> header with a value of <code>4.0</code>, and the OData 4.01 representation, for requests containing an <code>OData-Version</code> header with a value of <code>4.01</code>. Clients MUST NOT use <code>@odata.bind</code> in requests with an <code>OData-Version</code> header with a value of <code>4.01</code>.</p>
<p>For insert operations collection navigation property bind operations and deep insert operations can be combined. For OData 4.0 requests, the bind operations MUST appear before the deep insert operations in the payload.</p>
<p>For update operations a bind operation on a collection navigation property adds additional relationships, it does not replace existing relationships, while bind operations on an entity navigation property update the relationship.</p>
<h2 id="86-collection-etag"><a name="CollectionETag" href="#CollectionETag">8.6 Collection ETag</a></h2>
<p>The ETag for a collection of related entities is represented as <a href="#ControlInformationetagodataetag"><code>etag</code></a> control information on the navigation property. Its value is an opaque string that can be used in a subsequent request to determine if the collection has changed.</p>
<p>Services MAY include this control information as appropriate.</p>
<div class="example">
<p>Example 23: ETag for a collection of related entities</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Orders/$entity"</span><span class="fu">,</span></span>
<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Orders(1234)"</span><span class="fu">,</span></span>
<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@etag"</span><span class="fu">:</span> <span class="st">"W/</span><span class="ch">\"</span><span class="st">MjAxMy0wNS0yN1QxMTo1OFo=</span><span class="ch">\"</span><span class="st">"</span><span class="fu">,</span></span>
<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1234</span><span class="fu">,</span></span>
<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Items@etag"</span><span class="fu">:</span> <span class="st">"W/</span><span class="ch">\"</span><span class="st">MjAxOS0wMy0xMlQxMDoyMlo=</span><span class="ch">\"</span><span class="st">"</span></span>
<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>Note: the collection ETag for a navigation property may or may not be identical to the ETag of the containing entity, the example shows a different ETag for the <code>Items</code> collection.</p>
<hr />
<h1 id="9-stream-property"><a name="StreamProperty" href="#StreamProperty">9 Stream Property</a></h1>
<p>An entity or complex type instance can have one or more stream properties.</p>
<p>The actual stream data is not usually contained in the representation. Instead stream property data is generally read and edited via URLs.</p>
<ul>
<li>Stream properties requested with <code>$select</code> or included in the default selection are represented by <a href="#ControlInformationmediaodatamedia"><code>media*</code></a> control information.</li>
<li>Stream properties requested with <code>$expand</code> or implicitly expanded are represented as a property with its value.</li>
</ul>
<p>See <a href="#ODataProtocol">OData-Protocol</a> for details on the system query options <code>$select</code> and <code>$expand</code>.</p>
<p>Depending on the <a href="#ControllingtheAmountofControlInformationinResponses">metadata level</a>, the stream property MAY be annotated to provide the read link, edit link, media type, and ETag of the media stream through their <code>media*</code> control information.</p>
<p>If the actual stream data is included inline, the control information <a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a> MUST be present to indicate how the included stream property value is represented. Stream property values of media type <code>application/json</code> or one of its subtypes, optionally with format parameters, are represented as native JSON. Values of top-level type <code>text</code> with an explicit or default <code>charset</code> of <code>utf-8</code> or <code>us-ascii</code>, for example <code>text/plain</code>, are represented as a string, with JSON string escaping rules applied. Included stream data of other media types is represented as a base64url-encoded string value, see <a href="#rfc4648">RFC4648</a>, section 5.</p>
<p>If the included stream property has no value, the non-existing stream data is represented as <code>null</code> and the control information <a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a> is not necessary.</p>
<div class="example">
<p>Example 24:</p>
<div class="sourceCode" id="cb26"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Products/$entity"</span><span class="fu">,</span></span>
<span id="cb26-3"><a href="#cb26-3" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb26-4"><a href="#cb26-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaReadLink"</span><span class="fu">:</span> <span class="st">"http://server/Thumbnail546.jpg"</span><span class="fu">,</span></span>
<span id="cb26-5"><a href="#cb26-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEditLink"</span><span class="fu">:</span> <span class="st">"http://server/uploads/Thumbnail546.jpg"</span><span class="fu">,</span></span>
<span id="cb26-6"><a href="#cb26-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaContentType"</span><span class="fu">:</span> <span class="st">"image/jpeg"</span><span class="fu">,</span></span>
<span id="cb26-7"><a href="#cb26-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEtag"</span><span class="fu">:</span> <span class="st">"W/</span><span class="ch">\"</span><span class="st">####</span><span class="ch">\"</span><span class="st">"</span><span class="fu">,</span></span>
<span id="cb26-8"><a href="#cb26-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail"</span><span class="fu">:</span> <span class="st">"...base64url encoded value..."</span><span class="fu">,</span></span>
<span id="cb26-9"><a href="#cb26-9" aria-hidden="true" tabindex="-1"></a> <span class="er">...</span></span>
<span id="cb26-10"><a href="#cb26-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<hr />
<h1 id="10-media-entity"><a name="MediaEntity" href="#MediaEntity">10 Media Entity</a></h1>
<p>Media entities are entities that describe a media resource, for example a photo. They are represented as entities that contain additional <a href="#ControlInformationmediaodatamedia"><code>media*</code></a> control information. If the actual stream data for the media entity is included, it is represented as property named <code>$value</code> whose string value is the base64url-encoded value of the media stream, see <a href="rfc4648">RFC4648</a>.</p>
<div class="example">
<p>Example 25:</p>
<div class="sourceCode" id="cb27"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Employees/$entity"</span><span class="fu">,</span></span>
<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@mediaReadLink"</span><span class="fu">:</span> <span class="st">"Employees(1)/$value"</span><span class="fu">,</span></span>
<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@mediaContentType"</span><span class="fu">:</span> <span class="st">"image/jpeg"</span><span class="fu">,</span></span>