From d3b93bc670ffcb852e97d0968e20e27f84691198 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 24 Jul 2023 17:32:58 +0200 Subject: [PATCH] Chapters 7 to 9 --- docs/odata-json-format/odata-json-format.html | 151 ++++++- docs/odata-json-format/odata-json-format.md | 282 +++++++++++++ odata-json-format/10 Media Entity.md | 20 + .../{8 to 22 TODO.md => 15 to 22 TODO.md} | 40 -- odata-json-format/7 Structural Property.md | 302 ++++++++++++++ .../temp/odata-json-format-v4.01-os.md | 377 ++---------------- 6 files changed, 781 insertions(+), 391 deletions(-) create mode 100644 odata-json-format/10 Media Entity.md rename odata-json-format/{8 to 22 TODO.md => 15 to 22 TODO.md} (68%) diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 46cda470d..0bec8f671 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -801,6 +801,7 @@

], "EmailAddresses@nextLink": "..." } +

7.4 Collection of Complex Values

A collection of complex values is represented as a JSON array; each element in the array is the representation of a complex value. A JSON literal null represents a null value within the collection. An empty collection is represented as an empty array.

@@ -820,6 +821,7 @@

], "PhoneNumbers@nextLink": "..." }

+

7.5 Untyped Value

OData 4.01 adds the built-in abstract types Edm.Untyped and Collection(Edm.Untyped)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.

The value of an Edm.Untyped 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.

@@ -828,14 +830,161 @@

7.5 Untype

All children of an untyped property are assumed to be untyped unless they are annotated with the type control information, in which case they MUST conform to the type described by the control information.

8 Navigation Property

+

A navigation property is a reference from a source entity to zero or more related entities.

+

The navigation link for a navigation property is represented as a navigationLink control information on the navigation property. Its value is an absolute or relative URL that allows retrieving the related entity or collection of entities.

+

The navigation link for a navigation property is only represented if the client requests metadata=full 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.

+
+

Example 16:

+
{
+  "@context": "http://host/service/$metadata#Customers/$entity",
+  ...
+  "Orders@navigationLink": "Customers('ALFKI')/Orders",
+  ...
+}
+
+

The association link for a navigation property is represented as an associationLink control information on the navigation property. Its value is an absolute or relative URL that can be used to retrieve the reference or collection of references to the related entity or entities.

+

The association link for a navigation property is only represented if the client requests metadata=full or the association link cannot be computed by appending /$ref 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.

+
+

Example 17:

+
{
+  "@context": "http://host/service/$metadata#Customers/$entity",
+  ...
+  "Orders@associationLink": "Customers('ALFKI')/Orders/$ref",
+  ...
+}
+

8.3 Expanded Navigation Property

+

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.

+

If at most one entity can be related, the value is the representation of the related entity, or null if no entity is currently related.

+

If a collection of entities can be related, it is represented as a JSON array. Each element is the representation of an entity or the representation of an entity reference. An empty collection of entities (one that contains no entities) is represented as an empty JSON array. The navigation property MAY include context, type, count, or nextLink control information. If a navigation property is expanded with the suffix /$count, only the count control information is represented.

+
+

Example 18:

+
{
+  "@context": "http://host/service/$metadata#Customers/$entity",
+  "Orders@count": 42,
+  "Orders": [ ... ],
+  "Orders@nextLink": "...",
+  ...
+}
+

8.4 Deep Insert

+

When inserting a new entity with a POST request, related new entities MAY be specified using the same representation as for an expanded navigation property.

+

Deep inserts are not allowed in update operations using PUT or PATCH requests.

+
+

Example 19: inserting a new order for a new customer with order items related to existing products:

+
{
+  "ID": 11643,
+  "Amount": 100,
+  ...,
+  "Customer": {
+    "ID": "ANEWONE",
+    ...
+  },
+  "Items": [
+    {
+      "Product": { "@id": "Products(28)" },
+      "Quantity": 1,
+      ...
+    },
+    {
+      "Product": { "@id": "Products(39)" },
+      "Quantity": 5,
+      ...
+    }
+  ]
+}
+

8.5 Bind Operation

+

When inserting or updating an entity, relationships of navigation properties MAY be inserted or updated via bind operations.

+

For requests containing an OData-Version header with a value of 4.0, a bind operation is encoded as a property control information odata.bind 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 null may be used to remove the relationship.

+
+

Example 20: assign an existing product to an existing category with a partial update request against the product

+
PATCH http://host/service/Products(42) HTTP/1.1
+Content-Type: application/json
+
+{
+  "Category@odata.bind": "Categories(6)"
+}
+
+

The values are the ids of the related entities. They MAY be absolute or relative URLs.

+

For requests containing an OData-Version header with a value of 4.01, a relationship is bound to an existing entity using the same representation as for an expanded entity reference.

+
+

Example 21: assign an existing product to an existing category with a partial update request against the product

+
PATCH http://host/service/Products(42) HTTP/1.1
+Content-Type: application/json
+
+{
+  "Category": {"@id": "Categories(6)"}
+}
+
+
+

Example 22: submit a partial update request to:

+ +

At the end of the request, the updated category contains exactly the three specified products.

+
PATCH http://host/service/Categories(6) HTTP/1.1
+Content-Type: application/json
+
+{
+  "Name": "UpdatedCategory",
+  "Products": [
+    {
+      "@id": "Products(42)"
+    },
+    {
+      "@id": "Products(57)",
+      "Name": "Widgets"
+    },
+    {
+      "Name": "Wedges"
+    }
+  ]
+}
+
+

OData 4.01 services MUST support both the OData 4.0 representation, for requests containing an OData-Version header with a value of 4.0, and the OData 4.01 representation, for requests containing an OData-Version header with a value of 4.01. Clients MUST NOT use @odata.bind in requests with an OData-Version header with a value of 4.01.

+

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.

+

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.

8.6 Collection ETag

+

The ETag for a collection of related entities is represented as etag 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.

+

Services MAY include this control information as appropriate.

+
+

Example 23: ETag for a collection of related entities

+
{
+  "@context": "http://host/service/$metadata#Orders/$entity",
+  "@id": "Orders(1234)",
+  "@etag": "W/\"MjAxMy0wNS0yN1QxMTo1OFo=\"",
+  "ID": 1234,
+  "Items@etag": "W/\"MjAxOS0wMy0xMlQxMDoyMlo=\""
+  ...
+}
+
+

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 Items collection.

9 Stream Property

+

An entity or complex type instance can have one or more stream properties.

+

The actual stream data is not usually contained in the representation. Instead stream property data is generally read and edited via URLs.

+

Depending on the metadata level, the stream property MAY be annotated to provide the read link, edit link, media type, and ETag of the media stream through a set of media* control information.

+

If the actual stream data is included inline, the control information mediaContentType MUST be present to indicate how the included stream property value is represented. Stream property values of media type application/json or one of its subtypes, optionally with format parameters, are represented as native JSON. Values of top-level type text, for example text/plain, 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 RFC4648, section 5.

+

If the included stream property has no value, the non-existing stream data is represented as null and the control information mediaContentType is not necessary.

+
+

Example 24:

+
{
+  "@context": "http://host/service/$metadata#Products/$entity",
+  ...
+  "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
+  "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
+  "Thumbnail@mediaContentType": "image/jpeg",
+  "Thumbnail@mediaEtag": "W/\"####\"",
+  "Thumbnail": "...base64url encoded value...",
+  ...
+}
+

10 Media Entity

@@ -1136,7 +1285,5 @@

Appendix E. Notice

[OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this OASIS Standards Final Deliverable. OASIS may include such claims on its website, but disclaims any obligation to do so.]

[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this OASIS Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Standards Final Deliverable, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark/ for above guidance.

- - diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index cd7ee612e..45116c534 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -1479,6 +1479,7 @@ Example 14: partial collection of strings with next link "EmailAddresses@nextLink": "..." } ``` +::: ## 7.4 Collection of Complex Values @@ -1505,6 +1506,7 @@ Example 15: partial collection of complex values with next link "PhoneNumbers@nextLink": "..." } ``` +::: ## 7.5 Untyped Value @@ -1536,22 +1538,301 @@ described by the control information. # 8 Navigation Property +A navigation property is a reference from a source entity to zero or +more related entities. + ## 8.1 Navigation Link +The navigation link for a navigation property is represented as a +[`navigationLink`](#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink) +control information on the navigation property. Its value is an absolute +or [relative URL](#RelativeURLs) that allows retrieving the related +entity or collection of entities. + +The navigation link for a navigation property is only represented if the +client requests `metadata=full` 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. + +::: example +Example 16: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + ... + "Orders@navigationLink": "Customers('ALFKI')/Orders", + ... +} +``` +::: + ## 8.2 Association Link +The association link for a navigation property is represented as an +[`associationLink`](#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink) +control information on the navigation property. Its value is an absolute +or [relative URL](#RelativeURLs) that can be used to retrieve the +reference or collection of references to the related entity or entities. + +The association link for a navigation property is only represented if +the client requests `metadata=full` or the association link +cannot be computed by appending `/$ref` 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. + +::: example +Example 17: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + ... + "Orders@associationLink": "Customers('ALFKI')/Orders/$ref", + ... +} +``` +::: + ## 8.3 Expanded Navigation Property +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. + +If at most one entity can be related, the value is the representation of +the related entity, or `null` if no entity is currently +related. + +If a collection of entities can be related, it is represented as a JSON +array. Each element is the [representation of an entity](#Entity) or +the [representation of an entity reference](#EntityReference). An +empty collection of entities (one that contains no entities) is +represented as an empty JSON array. The navigation property MAY include +[`context`](#ControlInformationcontextodatacontext), +[`type`](#ControlInformationtypeodatatype), +[`count`](#ControlInformationcountodatacount), or +[`nextLink`](#ControlInformationnextLinkodatanextLink) control information. If a navigation property is +expanded with the suffix `/$count`, only the +[`count`](#ControlInformationcountodatacount) control information is represented. + +::: example +Example 18: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + "Orders@count": 42, + "Orders": [ ... ], + "Orders@nextLink": "...", + ... +} +``` +::: + ## 8.4 Deep Insert +When inserting a new entity with a `POST` request, related +new entities MAY be specified using the same representation as for an +[expanded navigation property](#ExpandedNavigationProperty). + +Deep inserts are not allowed in update operations using `PUT` +or `PATCH` requests. + +::: example +Example 19: inserting a new order for a new customer with order items +related to existing products: +```json +{ + "ID": 11643, + "Amount": 100, + ..., + "Customer": { + "ID": "ANEWONE", + ... + }, + "Items": [ + { + "Product": { "@id": "Products(28)" }, + "Quantity": 1, + ... + }, + { + "Product": { "@id": "Products(39)" }, + "Quantity": 5, + ... + } + ] +} +``` +::: + ## 8.5 Bind Operation +When inserting or updating an entity, relationships of navigation +properties MAY be inserted or updated via bind operations. + +For requests containing an `OData-Version` header with a value +of `4.0`, a bind operation +is encoded as a property control information `odata.bind` 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 `null` may be used to remove the relationship. + +::: example +Example 20: assign an existing product to an existing category with a +partial update request against the product +```json +PATCH http://host/service/Products(42) HTTP/1.1 +Content-Type: application/json + +{ + "Category@odata.bind": "Categories(6)" +} +``` +::: + +The values are the [ids](#ControlInformationidodataid) of the +related entities. They MAY be absolute or [relative URLs](#RelativeURLs). + +For requests containing an `OData-Version` header with a value +of `4.01`, a relationship is bound to an existing entity +using the same representation as for an [expanded entity +reference](#EntityReference). + +::: example +Example 21: assign an existing product to an existing category with a +partial update request against the product +```json +PATCH http://host/service/Products(42) HTTP/1.1 +Content-Type: application/json + +{ + "Category": {"@id": "Categories(6)"} +} +``` +::: + +::: example +Example 22: submit a partial update request to: +- modify the name of an existing category +- assign an existing product with the id 42 to the category +- assign an existing product 57 to the category and update its name +- create a new product named "Wedges" and assign it to the category + +At the end of the request, the updated category contains exactly the +three specified products. +```json +PATCH http://host/service/Categories(6) HTTP/1.1 +Content-Type: application/json + +{ + "Name": "UpdatedCategory", + "Products": [ + { + "@id": "Products(42)" + }, + { + "@id": "Products(57)", + "Name": "Widgets" + }, + { + "Name": "Wedges" + } + ] +} +``` +::: + +OData 4.01 services MUST support both the OData 4.0 representation, for +requests containing an `OData-Version` header with a value of +`4.0`, and the OData 4.01 representation, for requests +containing an `OData-Version` header with a value of `4.01`. Clients MUST NOT use `@odata.bind` in requests with an +`OData-Version` header with a value of `4.01`. + +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. + +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. + ## 8.6 Collection ETag +The ETag for a collection of related entities is represented as +[`etag`](#ControlInformationetagodataetag) 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. + +Services MAY include this control information as appropriate. + +::: example +Example 23: ETag for a collection of related entities +```json +{ + "@context": "http://host/service/$metadata#Orders/$entity", + "@id": "Orders(1234)", + "@etag": "W/\"MjAxMy0wNS0yN1QxMTo1OFo=\"", + "ID": 1234, + "Items@etag": "W/\"MjAxOS0wMy0xMlQxMDoyMlo=\"" + ... +} +``` +::: + +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 `Items` collection. + ------- # 9 Stream Property +An entity or complex type instance can have one or more stream properties. + +The actual stream data is not usually contained in the representation. +Instead stream property data is generally read and edited via URLs. + +Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), +the stream property MAY be annotated to provide the read link, edit +link, media type, and ETag of the media stream through a set of +[`media*`](#ControlInformationmediaodatamedia) control information. + +If the actual stream data is included inline, the control information +[`mediaContentType`](#ControlInformationmediaodatamedia) +MUST be present to indicate how the included stream property value is +represented. Stream property values of media type `application/json` or +one of its subtypes, optionally with format parameters, are represented +as native JSON. Values of top-level type `text`, for example +`text/plain`, 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 +[RFC4648](#rfc4648), section 5. + +If the included stream property has no value, the non-existing stream +data is represented as `null` and the control information +[`mediaContentType`](#ControlInformationmediaodatamedia) +is not necessary. + +::: example +Example 24: +```json +{ + "@context": "http://host/service/$metadata#Products/$entity", + ... + "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg", + "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg", + "Thumbnail@mediaContentType": "image/jpeg", + "Thumbnail@mediaEtag": "W/\"####\"", + "Thumbnail": "...base64url encoded value...", + ... +} +``` +::: + ------- # 10 Media Entity @@ -1572,6 +1853,7 @@ described by the control information. # 14 Entity Reference + ------- # 15 Delta Payload diff --git a/odata-json-format/10 Media Entity.md b/odata-json-format/10 Media Entity.md new file mode 100644 index 000000000..d984d656e --- /dev/null +++ b/odata-json-format/10 Media Entity.md @@ -0,0 +1,20 @@ +------- + +# ##sec Media Entity + +------- + +# ##sec Individual Property or Operation Response + +------- + +# ##sec Collection of Operation Responses + +------- + +# ##sec Collection of Entities + +------- + +# ##sec Entity Reference + diff --git a/odata-json-format/8 to 22 TODO.md b/odata-json-format/15 to 22 TODO.md similarity index 68% rename from odata-json-format/8 to 22 TODO.md rename to odata-json-format/15 to 22 TODO.md index 121f84033..5a317e781 100644 --- a/odata-json-format/8 to 22 TODO.md +++ b/odata-json-format/15 to 22 TODO.md @@ -1,45 +1,5 @@ ------- -# ##sec Navigation Property - -## ##subsec Navigation Link - -## ##subsec Association Link - -## ##subsec Expanded Navigation Property - -## ##subsec Deep Insert - -## ##subsec Bind Operation - -## ##subsec Collection ETag - -------- - -# ##sec Stream Property - -------- - -# ##sec Media Entity - -------- - -# ##sec Individual Property or Operation Response - -------- - -# ##sec Collection of Operation Responses - -------- - -# ##sec Collection of Entities - -------- - -# ##sec Entity Reference - -------- - # ##sec Delta Payload ## ##subsec Delta Responses diff --git a/odata-json-format/7 Structural Property.md b/odata-json-format/7 Structural Property.md index 511290900..6e0635d30 100644 --- a/odata-json-format/7 Structural Property.md +++ b/odata-json-format/7 Structural Property.md @@ -143,6 +143,7 @@ Example ##ex: partial collection of strings with next link "EmailAddresses@nextLink": "..." } ``` +::: ## ##subsec Collection of Complex Values @@ -169,6 +170,7 @@ Example ##ex: partial collection of complex values with next link "PhoneNumbers@nextLink": "..." } ``` +::: ## ##subsec Untyped Value @@ -195,3 +197,303 @@ they are annotated with the [`type`](#ControlInformationtypeodatatype) control information, in which case they MUST conform to the type described by the control information. + +------- + +# ##sec Navigation Property + +A navigation property is a reference from a source entity to zero or +more related entities. + +## ##subsec Navigation Link + +The navigation link for a navigation property is represented as a +[`navigationLink`](#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink) +control information on the navigation property. Its value is an absolute +or [relative URL](#RelativeURLs) that allows retrieving the related +entity or collection of entities. + +The navigation link for a navigation property is only represented if the +client requests `metadata=full` 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. + +::: example +Example ##ex: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + ... + "Orders@navigationLink": "Customers('ALFKI')/Orders", + ... +} +``` +::: + +## ##subsec Association Link + +The association link for a navigation property is represented as an +[`associationLink`](#ControlInformationnavigationLinkandassociationLinkodatanavigationLinkandodataassociationLink) +control information on the navigation property. Its value is an absolute +or [relative URL](#RelativeURLs) that can be used to retrieve the +reference or collection of references to the related entity or entities. + +The association link for a navigation property is only represented if +the client requests `metadata=full` or the association link +cannot be computed by appending `/$ref` 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. + +::: example +Example ##ex: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + ... + "Orders@associationLink": "Customers('ALFKI')/Orders/$ref", + ... +} +``` +::: + +## ##subsec Expanded Navigation Property + +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. + +If at most one entity can be related, the value is the representation of +the related entity, or `null` if no entity is currently +related. + +If a collection of entities can be related, it is represented as a JSON +array. Each element is the [representation of an entity](#Entity) or +the [representation of an entity reference](#EntityReference). An +empty collection of entities (one that contains no entities) is +represented as an empty JSON array. The navigation property MAY include +[`context`](#ControlInformationcontextodatacontext), +[`type`](#ControlInformationtypeodatatype), +[`count`](#ControlInformationcountodatacount), or +[`nextLink`](#ControlInformationnextLinkodatanextLink) control information. If a navigation property is +expanded with the suffix `/$count`, only the +[`count`](#ControlInformationcountodatacount) control information is represented. + +::: example +Example ##ex: +```json +{ + "@context": "http://host/service/$metadata#Customers/$entity", + "Orders@count": 42, + "Orders": [ ... ], + "Orders@nextLink": "...", + ... +} +``` +::: + +## ##subsec Deep Insert + +When inserting a new entity with a `POST` request, related +new entities MAY be specified using the same representation as for an +[expanded navigation property](#ExpandedNavigationProperty). + +Deep inserts are not allowed in update operations using `PUT` +or `PATCH` requests. + +::: example +Example ##ex: inserting a new order for a new customer with order items +related to existing products: +```json +{ + "ID": 11643, + "Amount": 100, + ..., + "Customer": { + "ID": "ANEWONE", + ... + }, + "Items": [ + { + "Product": { "@id": "Products(28)" }, + "Quantity": 1, + ... + }, + { + "Product": { "@id": "Products(39)" }, + "Quantity": 5, + ... + } + ] +} +``` +::: + +## ##subsec Bind Operation + +When inserting or updating an entity, relationships of navigation +properties MAY be inserted or updated via bind operations. + +For requests containing an `OData-Version` header with a value +of `4.0`, a bind operation +is encoded as a property control information `odata.bind` 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 `null` may be used to remove the relationship. + +::: example +Example ##ex: assign an existing product to an existing category with a +partial update request against the product +```json +PATCH http://host/service/Products(42) HTTP/1.1 +Content-Type: application/json + +{ + "Category@odata.bind": "Categories(6)" +} +``` +::: + +The values are the [ids](#ControlInformationidodataid) of the +related entities. They MAY be absolute or [relative URLs](#RelativeURLs). + +For requests containing an `OData-Version` header with a value +of `4.01`, a relationship is bound to an existing entity +using the same representation as for an [expanded entity +reference](#EntityReference). + +::: example +Example ##ex: assign an existing product to an existing category with a +partial update request against the product +```json +PATCH http://host/service/Products(42) HTTP/1.1 +Content-Type: application/json + +{ + "Category": {"@id": "Categories(6)"} +} +``` +::: + +::: example +Example ##ex: submit a partial update request to: +- modify the name of an existing category +- assign an existing product with the id 42 to the category +- assign an existing product 57 to the category and update its name +- create a new product named "Wedges" and assign it to the category + +At the end of the request, the updated category contains exactly the +three specified products. +```json +PATCH http://host/service/Categories(6) HTTP/1.1 +Content-Type: application/json + +{ + "Name": "UpdatedCategory", + "Products": [ + { + "@id": "Products(42)" + }, + { + "@id": "Products(57)", + "Name": "Widgets" + }, + { + "Name": "Wedges" + } + ] +} +``` +::: + +OData 4.01 services MUST support both the OData 4.0 representation, for +requests containing an `OData-Version` header with a value of +`4.0`, and the OData 4.01 representation, for requests +containing an `OData-Version` header with a value of `4.01`. +Clients MUST NOT use `@odata.bind` in requests with an +`OData-Version` header with a value of `4.01`. + +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. + +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. + +## ##subsec Collection ETag + +The ETag for a collection of related entities is represented as +[`etag`](#ControlInformationetagodataetag) 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. + +Services MAY include this control information as appropriate. + +::: example +Example ##ex: ETag for a collection of related entities +```json +{ + "@context": "http://host/service/$metadata#Orders/$entity", + "@id": "Orders(1234)", + "@etag": "W/\"MjAxMy0wNS0yN1QxMTo1OFo=\"", + "ID": 1234, + "Items@etag": "W/\"MjAxOS0wMy0xMlQxMDoyMlo=\"" + ... +} +``` +::: + +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 `Items` collection. + +------- + +# ##sec Stream Property + +An entity or complex type instance can have one or more stream properties. + +The actual stream data is not usually contained in the representation. +Instead stream property data is generally read and edited via URLs. + +Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), +the stream property MAY be annotated to provide the read link, edit +link, media type, and ETag of the media stream through a set of +[`media*`](#ControlInformationmediaodatamedia) control information. + +If the actual stream data is included inline, the control information +[`mediaContentType`](#ControlInformationmediaodatamedia) +MUST be present to indicate how the included stream property value is +represented. Stream property values of media type `application/json` or +one of its subtypes, optionally with format parameters, are represented +as native JSON. Values of top-level type `text`, for example +`text/plain`, 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 +[RFC4648](#rfc4648), section 5. + +If the included stream property has no value, the non-existing stream +data is represented as `null` and the control information +[`mediaContentType`](#ControlInformationmediaodatamedia) +is not necessary. + +::: example +Example ##ex: +```json +{ + "@context": "http://host/service/$metadata#Products/$entity", + ... + "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg", + "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg", + "Thumbnail@mediaContentType": "image/jpeg", + "Thumbnail@mediaEtag": "W/\"####\"", + "Thumbnail": "...base64url encoded value...", + ... +} +``` +::: diff --git a/odata-json-format/temp/odata-json-format-v4.01-os.md b/odata-json-format/temp/odata-json-format-v4.01-os.md index 3b32f3c67..a6037f5b3 100644 --- a/odata-json-format/temp/odata-json-format-v4.01-os.md +++ b/odata-json-format/temp/odata-json-format-v4.01-os.md @@ -1,345 +1,3 @@ -# {#sec_NavigationProperty}[8[ ]{style="font:7.0pt "Times New Roman""}][Navigation Property](#NavigationProperty) {#navigation-property style="margin-left:19.85pt;text-indent:-19.85pt"} - -::: - -A navigation property is a reference from a source entity to zero or -more related entities. - -## {#sec_NavigationLink}{#\_Representing_a_Deferred}8.1 [Navigation Link](#NavigationLink) - -The navigation link for a navigation property is represented as a -[`navigationLink`](#ControlInformationnavigationLinkanda) -control information on the navigation property. Its value is an absolute -or [relative URL](#RelativeURLs) that allows retrieving the related -entity or collection of entities. - -The navigation link for a navigation property is only represented if the -client requests `metadata=full` 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. - -::: example -Example ##ex: -```json -{ - "@context": -"http://host/service/$metadata#Customers/$entity", - ... - "Orders@navigationLink": -"Customers('ALFKI')/Orders", - ... -} -``` - -## {#sec_AssociationLink}[8.2] [Association Link](#AssociationLink) - -The association link for a navigation property is represented as an -[`associationLink`](#ControlInformationnavigationLinkanda) -control information on the navigation property. Its value is an absolute -or [relative URL](#RelativeURLs) that can be used to retrieve the -reference or collection of references to the related entity or entities. - -The association link for a navigation property is only represented if -the client requests `metadata=full` or the association link -cannot be computed by appending `/$ref` 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. - -::: example -Example ##ex: -```json -{ - "@context": -"http://host/service/$metadata#Customers/$entity", - ... - "Orders@associationLink": -"Customers('ALFKI')/Orders/$ref", - ... -} -``` - -## {#sec_ExpandedNavigationProperty}{#\_Expanded_Navigation_Property}8.3 [Expanded Navigation Property](#ExpandedNavigationProperty) - -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. - -If at most one entity can be related, the value is the representation of -the related entity, or `null` if no entity is currently -related. - -If a collection of entities can be related, it is represented as a JSON -array. Each element is the [representation of an entity](#Entity) or -the [representation of an entity reference](#EntityReference). An -empty collection of entities (one that contains no entities) is -represented as an empty JSON array. The navigation property MAY be -include -[`context`](#ControlInformationcontextodatacontext), -[`type`](#ControlInformationtypeodatatype), -[`count`](#ControlInformationcountodatacount),[ -]{.MsoHyperlink}or[ -]{.MsoHyperlink}[`nextLink`](#ControlInformationnextLinkodatanextL)[ -]{.MsoHyperlink}control information. If a navigation property is -expanded with the suffix `/$count`, only the -[`count`](#ControlInformationcountodatacount)[ -]{.MsoHyperlink}control information is represented. - -::: example -Example ##ex: -```json -{ - "@context": -"http://host/service/$metadata#Customers/$entity", - ][...]{lang="NL" style="color:black"} - - "Orders@count": 42,]{lang="NL" style="color:black"} - - "Orders": \[ ... \],]{lang="NL" style="color:black"} - - "Orders@nextLink": "...",]{lang="NL" style="color:black"} - - ]{lang="NL" style="color:black"}[... -} -``` - -## {#sec_DeepInsert}[8.4] [Deep Insert](#DeepInsert) - -When inserting a new entity with a `POST` request, related -new entities MAY be specified using the same representation as for an -[expanded navigation property](#ExpandedNavigationProperty). - -Deep inserts are not allowed in update operations using `PUT` -or `PATCH` requests. - -::: example -Example ##ex: inserting a new order for a new customer with order items -related to existing products: -```json -{ - "ID": 11643, - "Amount": 100, - ..., - "Customer": { - "ID": "ANEWONE", - ... - }, - "Items": \[ - { - "Product": { "@id": "Products(28)" }, - "Quantity": 1, - ... - }, - { - "Product": { "@id": "Products(39)" }, - "Quantity": 5, - ... - } - \] -} -``` - -## {#sec_BindOperation}{#\_Bind_Operation}8.5 [Bind Operation](#BindOperation) - -When inserting or updating an entity, relationships of navigation -properties MAY be inserted or updated via bind operations. - -For requests containing an `OData-Version` header with a value -of `4.0`[[, -]{style="font-family:"Arial",sans-serif"}]{.Datatype}a bind operation -is encoded as a property control information `odata.bind` 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 `null` may be used to remove the relationship. - -::: example -Example ##ex: assign an existing product to an existing category with a -partial update request against the product -```json -PATCH http://host/service/Products(42) HTTP/1.1 - - -[{ - "Category@odata.bind": "Categories(6)" -} -``` - -The values are the [ids](#ControlInformationidodataid) of the -related entities. They MAY be absolute or [relative -URLs](#RelativeURLs). - -For requests containing an `OData-Version` header with a value -of `4.01`, a relationship is bound to an existing entity -using the same representation as for an [expanded entity -reference](#EntityReference). - -::: example -Example ##ex: assign an existing product to an existing category with a -partial update request against the product -```json -PATCH http://host/service/Products(42) HTTP/1.1 - - -[{ - "Category": {"@id": "Categories(6)"} -} -``` - - - -::: example -Example ##ex: submit a partial update request to: - -]{style="font:7.0pt "Times New Roman""}]{style="font-family:Symbol;font-style:normal"}modify -the name of an existing category - -]{style="font:7.0pt "Times New Roman""}]{style="font-family:Symbol;font-style:normal"}assign -an existing product with the id 42 to the category - -]{style="font:7.0pt "Times New Roman""}]{style="font-family:Symbol;font-style:normal"}assign -an existing product 57 to the category and update its name - -]{style="font:7.0pt "Times New Roman""}]{style="font-family:Symbol;font-style:normal"}create -a new product named "Wedges" and assign it to the category - -_[at the end of the request, the updated category contains exactly the -three specified products.]{style="font-size:9.0pt"}_ -```json -PATCH http://host/service/Categories(6) HTTP/1.1 - - -[{ - "Name": "UpdatedCategory", - "Products": \[ - { - "@id": "Products(42)" - }, - { - "@id": "Products(57)", - "Name": "Widgets" - }, - { - "Name": "Wedges" - } - \] -} -``` - -OData 4.01 services MUST support both the OData 4.0 representation, for -requests containing an `OData-Version` header with a value of -`4.0`, and the OData 4.01 representation, for requests -containing an `OData-Version` header with a value of -`4.01`[[.]{style="font-family:"Arial",sans-serif"}]{.Datatype} -Clients MUST NOT use `\@odata.bind` in requests with an -`OData-Version` header with a value of -`4.01`[[.]{style="font-family:"Arial",sans-serif"}]{.Datatype} - -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. - -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. - -## {#sec_CollectionETag}[8.6] [Collection ETag](#CollectionETag) - -The ETag for a collection of related entities is represented as -[[etag]{style="font-family: -"Courier New""}](#ControlInformationetagodataetag) 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. - -Services MAY include this control information as appropriate. - -::: example -Example ##ex: ETag for a collection of related entities -```json -{ - "@context": -"http://host/service/$metadata#Orders/$entity", - "@id": "Orders(1234)", - "@etag": -"W/\\"MjAxMy0wNS0yN1QxMTo1OFo=\\"", - "ID": 1234, - "Items@etag": -"W/\\"MjAxOS0wMy0xMlQxMDoyMlo=\\"" - ... -} -``` - -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 `Items` collection. - -::: {style="border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in"} - -# {#sec_StreamProperty}{#\_Stream_Property}9[ ]{style="font:7.0pt "Times New Roman""}[Stream Property](#StreamProperty) {#stream-property style="margin-left:19.85pt;text-indent:-19.85pt"} - -::: - -[An entity or complex type instance can have one or more stream -properties. ]{style="color:black;background:white"} - -[The actual stream data is not usually contained in the representation. -Instead stream property data is generally read and edited via URLs. -]{style="color:black;background:white"} - -Depending on the [[metadata -level]{style="background:white"}](#ControllingtheAmountofControlInforma)[, -the stream property MAY be annotated to provide the read link, edit -link, media type, and ETag of the media -stream]{style="color:black;background:white"} through a set of -[`media\*`](#ControlInformationmediaodatamedia) -control information. - -[If the actual stream data is included inline, the control information -]{style="color:black;background:white"}[`mediaContentType`](#ControlInformationmediaodatamedia)[ -MUST be present to indicate how the included stream property value is -represented. Stream property values of media type -]{style="color:black;background:white"}`application/json`[ or -one of its subtypes, optionally with format parameters, are represented -as native JSON. Values of ]{style="color: -black;background:white"}top-level type `text`, for example -`text/plain`, 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 -**]{style="color:black;background:white"}\*\*RFC4648\]\*\*[, -section 5.]{style="color:black;background:white"} - -If the included stream property has no value, the non-existing stream -data is represented as `null` and the control information -[`mediaContentType`](#ControlInformationmediaodatamedia)[[ -is not necessary]{style="font-family:"Arial",sans-serif"}]{.Datatype}. - -::: example -Example ##ex: -```json -{ - "@context": -"http://host/service/$metadata#Products/$entity", - ... - "Thumbnail@mediaReadLink": -"http://server/Thumbnail546.jpg", - "Thumbnail@mediaEditLink": -"http://server/uploads/Thumbnail546.jpg", - ]["Thumbnail@mediaContentType": -"image/jpeg",]{lang="DE" style="color:black"} - - "Thumbnail@mediaEtag": "W/\\"####\\"",]{lang="DE" -style="color:black"} - - ]{lang="DE" style="color:black"}["Thumbnail": "...base64url -encoded value...", - ... -} -``` -::: {style="border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in"} - # {#sec_MediaEntity}{#\_Media_Entity}10[ ]{style="font:7.0pt "Times New Roman""}[Media Entity](#MediaEntity) {#media-entity style="margin-left:19.85pt;text-indent:-19.85pt"} ::: @@ -407,6 +65,7 @@ Example ##ex: primitive value "value": "Pilar Ackerman" } ``` +::: ::: example Example ##ex: collection of primitive values @@ -418,6 +77,7 @@ Example ##ex: collection of primitive values large"\] } ``` +::: ::: example Example ##ex: empty collection of primitive values @@ -428,6 +88,7 @@ Example ##ex: empty collection of primitive values "value": \[\] } ``` +::: ::: example Example ##ex: complex value @@ -441,6 +102,7 @@ Example ##ex: complex value "Country@navigationLink": "Countries('US')" } ``` +::: ::: example Example ##ex: empty collection of complex values @@ -451,6 +113,7 @@ Example ##ex: empty collection of complex values "value": \[\] } ``` +::: Note: the context URL is optional in requests. @@ -587,6 +250,7 @@ Example ##ex: entity reference to order 10643 "@id": "Orders(10643)" } ``` +::: ::: example Example ##ex: collection of entity references @@ -1219,6 +883,7 @@ path in the initial request, unless either of the following is true: 0in"} The deleted-link object MUST include the following properties, regardless of the specified metadata value, and MAY include annotations: ``` +::: - [`context`](#ControlInformationcontextodatacontext) -- the context URL fragment MUST be @@ -1454,6 +1119,7 @@ applicable ... } ``` +::: ::: example Example ##ex: full representation of a specific overload with parameter @@ -1470,6 +1136,7 @@ alias for the [[Year]{style="font-size:10.0pt"}]{.Keyword} parameter ... } ``` +::: ::: example Example ##ex: full representation in a collection @@ -1485,6 +1152,7 @@ Example ##ex: full representation in a collection "value": \[ ... \] } ``` +::: {#\_Bound_Action}Example 41: full representation in a nested collection @@ -1563,6 +1231,7 @@ Example ##ex: minimal representation in an entity ... } ``` +::: ::: example Example ##ex: full representation in an entity: @@ -1577,6 +1246,7 @@ Example ##ex: full representation in an entity: ... } ``` +::: ::: example Example ##ex: full representation in a collection @@ -1592,6 +1262,7 @@ Example ##ex: full representation in a collection "value": \[ ... \] } ``` +::: [Example] 45: full representation in a nested collection @@ -1650,6 +1321,7 @@ Example 46: "param4": null } ``` +::: @@ -1863,6 +1535,7 @@ entity\> \] } ``` +::: ## {#sec_ReferencingNewEntities}[[19.2 ]{style="color:#0000EE"}][Referencing New Entities](#ReferencingNewEntities) @@ -1906,6 +1579,7 @@ Order\> \] } ``` +::: ## {#sec_ReferencinganETag}[[19.3 ]{style="color:#0000EE"}][Referencing an ETag](#ReferencinganETag) @@ -1952,6 +1626,7 @@ Content-Length: \###\ \] } ``` +::: ## {#sec_ProcessingaBatchRequest}19.4 [Processing a Batch Request](#ProcessingaBatchRequest) @@ -2099,6 +1774,7 @@ entity\> \] } ``` +::: ## {#sec_AsynchronousBatchRequests}{#\_Ref358207547}{#\_Instance_Annotations}19.6 [Asynchronous Batch Requests](#AsynchronousBatchRequests) @@ -2309,6 +1985,7 @@ Example ##ex: \] } ``` +::: ## {#sec_AnnotateaJSONObject}[20.1] [Annotate a JSON Object](#AnnotateaJSONObject) @@ -2436,6 +2113,7 @@ supported" } } ``` +::: ## {#\_Ref356829963}{#sec_InStreamError}{#\_The_Content-Type_Header}{#\_Payload_Ordering_Constraints}21.2 [In-Stream Error](#InStreamError) @@ -2461,7 +2139,7 @@ header-appropriate way: - Control characters (`00` to `1F` and `7F`) and Unicode characters beyond `00FF` within JSON strings are - encoded as `\\uXXXX` or `\\uXXXX\\uXXXX` (see + encoded as `\uXXXX` or `\uXXXX\uXXXX` (see [RFC8259](#rfc8259), section 7) ::: example @@ -2526,7 +2204,7 @@ members are not available. ::: Implementations can add [instance annotations](#InstanceAnnotations) -of the form `\@namespace.termname` or +of the form `@namespace.termname` or `property@namespace.termname` to any JSON object, where `property` MAY or MAY NOT match the name of a name/value pair within the JSON object. However, the namespace MUST NOT start with @@ -2616,12 +2294,12 @@ odata.]{style="font-family:"Courier New""} prefix, where defined, on b.[ ]{style="font:7.0pt "Times New Roman""}MUST accept the [\# ]{style="font-family:"Courier New""}prefix in -[`\@odata.type`](#ControlInformationtypeodatatype) +[`@odata.type`](#ControlInformationtypeodatatype) values c.[ ]{style="font:7.0pt "Times New Roman""}MUST be prepared to handle binding through the use of the -[`\@odata.bind`](#BindOperation) +[`@odata.bind`](#BindOperation) property in payloads to a `PATCH`, `PUT`, or [POST]{style="font-family: @@ -2652,7 +2330,7 @@ interpret [control information](#ControlInformation) with or without the `odata.` prefix b.[ ]{style="font:7.0pt "Times New Roman""}MUST be prepared for -[`\@odata.type`](#ControlInformationtypeodatatype) +[`@odata.type`](#ControlInformationtypeodatatype) primitive values with or without the `\#` prefix @@ -2701,7 +2379,7 @@ information](#ControlInformation) b.[ ]{style="font:7.0pt "Times New Roman""}MUST NOT omit the `\#` prefix from -[`\@odata.type`](#ControlInformationtypeodatatype)[ +[`@odata.type`](#ControlInformationtypeodatatype)[ ]{style="font-family:"Courier New""}values c.[ ]{style="font:7.0pt "Times New Roman""}MUST NOT include @@ -2747,7 +2425,7 @@ control information](#ControlInformation) c.[ ]{style="font:7.0pt "Times New Roman""}SHOULD omit the `\#` prefix from -[`\@type`](#ControlInformationtypeodatatype) +[`@type`](#ControlInformationtypeodatatype) primitive values d.[ ]{style="font:7.0pt "Times New Roman""}MAY include inline @@ -2963,3 +2641,4 @@ B.[ ]{style="font:7.0pt "Times New Roman""}][Revision History](#RevisionHistory ::: ``` +:::