From d6793e40332b6c2db9bcfc9aaa6ce0f7e5457051 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 29 Oct 2024 14:25:59 +0100 Subject: [PATCH 1/5] Add Node 22 (#2020) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Node 22 is now current, Node 20 is active LTS, see https://github.com/nodejs/release?tab=readme-ov-file#release-schedule --------- Co-authored-by: Heiko Theißen --- .github/workflows/nodejs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 20d0fa87e..17c6e6e06 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -8,7 +8,7 @@ jobs: strategy: matrix: - node-version: [20.x] + node-version: [20.x, 22.x] steps: - uses: actions/checkout@v4 From f4ad5e1e4665e1a69f63c357d5a082f6edccbb3d Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 29 Oct 2024 17:29:13 +0100 Subject: [PATCH 2/5] Only Node 22 (#2022) --- .github/workflows/nodejs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 17c6e6e06..ab9be05db 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -8,7 +8,7 @@ jobs: strategy: matrix: - node-version: [20.x, 22.x] + node-version: [22.x] steps: - uses: actions/checkout@v4 From d3177e0b009ab58818d56a4ed3912eaf0ea6f67e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 6 Nov 2024 18:30:07 +0100 Subject: [PATCH 3/5] Allow nulls in returned collections of entities (#2023) Fixes #1983 --- docs/odata-csdl-json/odata-csdl-json.html | 16 ++++++++++------ docs/odata-csdl-json/odata-csdl-json.md | 6 ++---- docs/odata-csdl-xml/odata-csdl-xml.html | 16 ++++++++++------ docs/odata-csdl-xml/odata-csdl-xml.md | 6 ++---- odata-csdl/1 Introduction.md | 1 + odata-csdl/12 Action and Function.md | 10 ++-------- 6 files changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index e05c7694f..ae26a1757 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -464,26 +464,31 @@

348 +Section 12.8 +Returned collections of entities may contain null values +1983 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -2011,8 +2016,7 @@

$Type and $Nullable

The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.

-

If the return type is a collection of entity types, the $Nullable member has no meaning and MUST NOT be specified.

-

For other collection-valued return types the result will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

+

For collection-valued return types the result will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

Annotation Core.IsDelta

diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index a4cf256b0..d4a614514 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -268,6 +268,7 @@ Section | Feature / Change | Issue [Section 3.4.5](#SRID)| SRID value `variable` is deprecated| [1935](https://github.com/oasis-tcs/odata-specs/issues/1935) [Section 4](#CSDLJSONDocument) | Additional `$Version` value `4.02` | [Section 12](#ActionandFunction) | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section 12.8](#ReturnType) | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) @@ -2895,10 +2896,7 @@ Absence of the `$Type` member means the type is `Edm.String`. The value of `$Nullable` is one of the Boolean literals `true` or `false`. Absence of the member means `false`. -If the return type is a collection of entity types, the `$Nullable` -member has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case `$Nullable` applies to items of the collection and specifies whether the collection MAY contain `null` values. diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index 14978ace2..e934cf6bc 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -468,26 +468,31 @@

348 +Section 12.8 +Returned collections of entities may contain null values +1983 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -1897,8 +1902,7 @@

Attribute TypeFor collection-valued return types the value of Type is the character sequence Collection( followed by the qualified name of the return item type, followed by a closing parenthesis ).

Attribute Nullable

The value of Nullable is one of the Boolean literals true or false. Absence of the attribute means true.

-

If the return type is a collection of entity types, the Nullable attribute has no meaning and MUST NOT be specified.

-

For other collection-valued return types the result will always be a collection that MAY be empty. In this case the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.

+

For collection-valued return types the result will always be a collection that MAY be empty. In this case the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.

For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

Annotation Core.IsDelta

diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index 1e4fa24a0..12d4e497d 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -269,6 +269,7 @@ Section | Feature / Change | Issue [Section 4](#CSDLXMLDocument) | Additional `Version` value `4.02` | [Section 13](#EntityContainer)| All children of `edm:EntityContainer` are optional| [464](https://github.com/oasis-tcs/odata-specs/issues/464) [Section 12](#ActionandFunction) | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section 12.8](#ReturnType) | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) @@ -2772,10 +2773,7 @@ type, followed by a closing parenthesis `)`. The value of `Nullable` is one of the Boolean literals `true` or `false`. Absence of the attribute means `true`. -If the return type is a collection of entity types, the `Nullable` -attribute has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case the `Nullable` attribute applies to items of the collection and specifies whether the collection MAY contain `null` values. diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md index 9bdb14810..3aa65bc79 100644 --- a/odata-csdl/1 Introduction.md +++ b/odata-csdl/1 Introduction.md @@ -47,6 +47,7 @@ All children of `edm:EntityContainer` are optional| [464](https://github.com/oasis-tcs/odata-specs/issues/464) : [Section ##ActionandFunction] | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section ##ReturnType] | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section ##GeoValues] | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section ##StreamValues] | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section ##PathEvaluation]| diff --git a/odata-csdl/12 Action and Function.md b/odata-csdl/12 Action and Function.md index deea8a82c..23358fb3a 100644 --- a/odata-csdl/12 Action and Function.md +++ b/odata-csdl/12 Action and Function.md @@ -276,10 +276,7 @@ Absence of the `$Type` member means the type is `Edm.String`. The value of `$Nullable` is one of the Boolean literals `true` or `false`. Absence of the member means `false`. -If the return type is a collection of entity types, the `$Nullable` -member has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case `$Nullable` applies to items of the collection and specifies whether the collection MAY contain `null` values. @@ -314,10 +311,7 @@ type, followed by a closing parenthesis `)`. The value of `Nullable` is one of the Boolean literals `true` or `false`. Absence of the attribute means `true`. -If the return type is a collection of entity types, the `Nullable` -attribute has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case the `Nullable` attribute applies to items of the collection and specifies whether the collection MAY contain `null` values. From 5096493c2808de6042b8d0edf0f56b25ef727670 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Wed, 6 Nov 2024 18:35:34 +0100 Subject: [PATCH 4/5] Use deep links in cross-spec references (#2014) The [OData-Protocol] spec references the two [OData-CSDL] specs (JSON and XML format) as two entries with separate hyperlinks. This is useful for text like https://github.com/oasis-tcs/odata-specs/blob/9439daa138217848097520383d302985ac47666c/odata-protocol/1%20Introduction.md?plain=1#L16-L20 All other specs reference the two [OData-CSDL] specs as one, see https://github.com/oasis-tcs/odata-specs/compare/HEAD..9439daa138217848097520383d302985ac47666c#diff-db5ad1be4d39d16383ddb159ad2e1168888539f3a62b9bdd79b7e72189e446bb. --------- Co-authored-by: Ralf Handl --- docs/odata-csdl-json/odata-csdl-json.html | 44 +++++----- docs/odata-csdl-json/odata-csdl-json.md | 50 ++++++----- docs/odata-csdl-xml/odata-csdl-xml.html | 28 +++--- docs/odata-csdl-xml/odata-csdl-xml.md | 32 +++---- .../odata-data-aggregation-ext.html | 6 +- .../odata-data-aggregation-ext.md | 6 +- docs/odata-json-format/odata-json-format.html | 63 ++++++------- docs/odata-json-format/odata-json-format.md | 70 +++++++-------- docs/odata-protocol/odata-protocol.html | 85 +++++++++--------- docs/odata-protocol/odata-protocol.md | 88 ++++++++++--------- .../odata-temporal-ext.html | 12 +-- docs/odata-temporal-ext/odata-temporal-ext.md | 12 +-- .../odata-url-conventions.html | 40 ++++----- .../odata-url-conventions.md | 50 +++++------ odata-csdl/1 Introduction.md | 2 +- odata-csdl/14 Vocabulary and Annotation.md | 26 +++--- odata-csdl/4 CSDL Document.md | 4 +- odata-csdl/5 Schema.md | 6 +- odata-csdl/7 Structural Property.md | 4 +- odata-csdl/9 Complex Type.md | 2 +- odata-csdl/Appendix.md | 6 +- .../4 Cross-Joins and Aggregation.md | 2 +- .../5 Vocabulary for Data Aggregation.md | 2 +- odata-data-aggregation-ext/8 Conformance.md | 2 +- odata-json-format/10 Media Entity.md | 4 +- odata-json-format/15 Delta Payload.md | 4 +- odata-json-format/16 Bound Function.md | 6 +- .../19 Batch Requests and Responses.md | 10 +-- odata-json-format/20 Instance Annotations.md | 4 +- odata-json-format/23 Conformance.md | 2 +- odata-json-format/4 Common Characteristics.md | 28 +++--- odata-json-format/5 Service Document.md | 7 +- odata-json-format/7 Structural Property.md | 3 +- odata-json-format/Appendix.md | 2 +- odata-protocol/1 Introduction.md | 8 +- odata-protocol/10 Context URL.md | 4 +- odata-protocol/11 Data Service Requests.md | 16 ++-- odata-protocol/11.4 Data Modification.md | 11 +-- odata-protocol/11.5 Operations.md | 10 +-- odata-protocol/11.7 Batch Requests.md | 2 +- odata-protocol/12 Conformance.md | 30 +++---- odata-protocol/8 Header Fields.md | 4 +- odata-protocol/Appendix.md | 3 +- .../4.3 Modifying Temporal Data.md | 10 +-- odata-temporal-ext/Appendix.md | 2 +- odata-url-conventions/1 Introduction.md | 2 +- odata-url-conventions/4 Resource Path.md | 20 ++--- odata-url-conventions/5 Query Options.md | 28 +++--- odata-vocabularies/Appendix.md | 2 +- 49 files changed, 432 insertions(+), 432 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index ae26a1757..e4dfd831c 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -818,7 +818,7 @@

3.4.1 MaxLengthType Facet Members

$MaxLength

The value of $MaxLength is a positive integer.

-

Note: OData-CSDL-XML defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.

+

Note: OData-CSDLXML, section 3.4.1 defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.

@@ -1014,7 +1014,7 @@

4.1 Reference

A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.

A reference MUST specify a URI that uniquely identifies the referenced document, so two references MUST NOT specify the same URI. The URI SHOULD be a URL that locates the referenced document. If the URI is not dereferencable it SHOULD identify a well-known schema. The URI MAY be absolute or relative URI; relative URLs are relative to the URL of the document containing the reference, or relative to a base URL specified in a format-specific way.

A reference MAY be annotated.

-

The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined OData-Protocol, SHOULD be used when retrieving the referenced schema document.

+

The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined in OData-Protocol, section 11.2.12, SHOULD be used when retrieving the referenced schema document.

$Reference

The value of $Reference is an object that contains one member per referenced CSDL document. The name of the pair is a URI for the referenced document. The URI MAY be relative to the document containing the $Reference. The value of each member is a reference object.

@@ -1295,7 +1295,7 @@

6.3 O

An entity type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

An entity type derived from an open entity type MUST indicate that it is also open.

-

Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol.

+

Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

$OpenType

The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.

@@ -1304,7 +1304,7 @@

$OpenType

6.4 Media Entity Type

 -

An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol.

+

An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol, section 11.2.3.

An entity type derived from a media entity type MUST indicate that it is also a media entity type.

Media entity types MAY specify a list of acceptable media types using an annotation with term Core.AcceptableMediaTypes, see OData-VocCore.

@@ -1335,7 +1335,7 @@

6.5 Key

  • Edm.String
  • Edm.TimeOfDay
    • -

    Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol) MUST be language independent.

    +

    Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol, section 4.1) MUST be language independent.

    A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable single-valued complex properties, recursively.

    In OData 4.01 the key properties of a directly related entity type MAY also be part of the key if the navigation property is single-valued and not nullable. This includes navigation properties of non-nullable single-valued complex properties (recursively) of the entity type. If a key property of a related entity type is part of the key, all key properties of the related entity type MUST also be part of the key.

    If the key property is a property of a complex property (recursively) or of a directly related entity type, the key MUST specify an alias for that property that MUST be a simple identifier and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.

    @@ -1490,7 +1490,7 @@

    7.3 Default

    If no value is specified, the client SHOULD NOT assume a default value.

    $DefaultValue

    -

    The value of $DefaultValue is the type-specific JSON representation of the default value of the property, see OData-JSON. For properties of type Edm.Decimal and Edm.Int64 the representation depends on the media type parameter IEEE754Compatible.

    +

    The value of $DefaultValue is the type-specific JSON representation of the default value of the property, see OData-JSON, section 7.1. For properties of type Edm.Decimal and Edm.Int64 the representation depends on the media type parameter IEEE754Compatible.

    @@ -1583,7 +1583,7 @@

    OData-URL.

    +

    Instances of the structured type that declares the navigation property, either directly or indirectly via a property of complex type, contain the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see OData-URL, section 4.3.2.

    Entity types used in collection-valued containment navigation properties MUST have a key defined.

    For items of an ordered collection of complex types (those annotated with the Core.Ordered term defined in OData-VocCore the canonical URL of the item is the canonical URL of the collection appended with a segment containing the zero-based ordinal of the item. Items within in an unordered collection of complex types do not have a canonical URL. Services that support unordered collections of complex types declaring a containment navigation property, either directly or indirectly via a property of complex type, MUST specify the URL for the navigation link within a payload representing that item, according to format-specific rules.

    OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.

    @@ -1751,7 +1751,7 @@

    9.

    A complex type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

    A complex type derived from an open complex type MUST indicate that it is also open.

    -

    Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData‑Protocol.

    +

    Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

    $OpenType

    The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.

    @@ -2335,7 +2335,7 @@

    annotation applies a term to a model element and defines how to calculate a value for the applied term.

    Metadata annotations are terms applied to model elements. Behaviors or constraints described by a metadata annotation must be consistent with the annotated model element. Such annotations define additional behaviors or constraints on the model element, such as a service, entity type, property, function, action, or parameter. For example, a metadata annotation may define ranges of valid values for a particular property. Metadata annotations are applied in CSDL documents describing or referencing an entity model.

    -

    Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

    +

    Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON, section 20. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

    A vocabulary is a schema containing a set of terms where each term is a named metadata extension. Anyone can define a vocabulary (a set of terms) that is scenario-specific or company-specific; more commonly used terms can be published as shared vocabularies such as the OData Core vocabulary OData-VocCore.

    A term can be used to:

      @@ -2408,8 +2408,8 @@

      $Nullable

      For single-valued terms the value true means that annotations may have the null value.

      For collection-valued terms the annotation value will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

      $DefaultValue

      -

      The value of $DefaultValue is the type-specific JSON representation of the default value of the term, see OData-JSON.

      -

      Note: the $DefaultValue member is purely for documentation and isomorphy to OData-CSDLXML. Annotations in CSDL JSON documents MUST always specify an explicit value.

      +

      The value of $DefaultValue is the type-specific JSON representation of the default value of the term, see OData-JSON, section 7.1.

      +

      Note: the $DefaultValue member is purely for documentation and isomorphy to OData-CSDLXML, section 7.3. Annotations in CSDL JSON documents MUST always specify an explicit value.

      14.1.1 Specialized Term

      @@ -2935,7 +2935,7 @@

      14.3.12 Time of D

      14.3.13 Geo Values
      -

      Values are represented as GeoJSON, see OData-JSON.

      +

      Values are represented as GeoJSON, see RFC7946.

      Example 58:

      @@ -2946,7 +2946,7 @@

      14.3.13 Geo Values

      14.3.14 Stream Values

      -

      Constant values of type Edm.Stream are represented according to OData-JSON and MUST be accompanied by the mediaContentType control information to indicate how the stream value is to be interpreted.

      +

      Constant values of type Edm.Stream are represented according to OData-JSON, section 9 and MUST be accompanied by the mediaContentType control information to indicate how the stream value is to be interpreted.

      The annotation (property) being assigned a stream value MUST be annotated with term Core.MediaType and the media type of the stream as its value.

      @@ -2977,7 +2977,7 @@

      1

      14.4.1.1 Path Syntax

       -

      Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL.

      +

      Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL, section 5.1.1.15.

      A path MUST be composed of zero or more path segments joined together by forward slashes (/).

      Paths starting with a forward slash (/) are absolute paths, and the first path segment MUST be the qualified name of a model element, e.g. an entity container. The remaining path after the second forward slash is interpreted relative to that model element.

      @@ -3024,7 +3024,7 @@

      14.4.1.1 Path S 
      …/Items@Core.Description
      …/Items/@Core.Description

      -

      An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

      +

      An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL, section 4.3.1. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

      Example 67: instance path with entity set and key predicate

      /self.container/SettingsCollection('FeatureXxx')/IsAvailable
      @@ -3237,7 +3237,7 @@

      OData-URL.

      +

      The And and Or operators require two operand expressions that evaluate to Boolean values. The Not operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see OData-URL, section 5.1.1.1.

      The other comparison operators require two operand expressions that evaluate to comparable values.

      $And and $Or

      @@ -3349,7 +3349,7 @@

      $Eq, 14.4.3 Arithmetic Operators

      -

      Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL.

      +

      Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL, section 5.1.1.2.

      @@ -3479,7 +3479,7 @@

      $Apply and 14.4.4.1 Canonical Functions

      -

      All canonical functions defined in OData-URL can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL.

      +

      All canonical functions defined in OData-URL, section 5.1.1.4 can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL, section 5.1.1.4.

      For example, the odata.concat client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type Edm.String that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than Edm.String are represented according to the appropriate alternative in the primitiveValue rule of OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.

      Example 77:

      @@ -3602,7 +3602,7 @@

      14.4.5 Cast

      -

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL.

      +

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL, section 5.1.1.10.1.

      $Cast

      Cast expressions are represented as an object with a member $Cast whose value is an annotation expression, a member $Type whose value is a string containing the qualified type name, and optionally a member $Collection with a value of true.

      @@ -3790,7 +3790,7 @@

      14.4.12 Record

      For collection-valued properties the absence of a property value expression is equivalent to specifying an empty collection as its value.

      Record expressions are represented as objects with one member per property value expression. The member name is the property name, and the member value is the property value expression.

      -

      The type of a record expression is represented as the type control information, see OData-JSON.

      +

      The type of a record expression is represented as the type control information, see OData-JSON, section 4.6.3.

      It MAY contain annotations for itself and its members. Annotations for record members are prefixed with the member name.

      @@ -4283,6 +4283,8 @@
      RFC6570
      RFC7493

      The I-JSON Message Format“, RFC 7493, DOI 10.17487/RFC7493, March 2015.
      https://www.rfc-editor.org/info/rfc7493.

      +
      RFC7946
      +

      Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, “The GeoJSON Format”, RFC 7946, DOI 10.17487/RFC7946, August 2016. https://www.rfc-editor.org/info/rfc7946.

      RFC8174

      Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
      https://www.rfc-editor.org/info/rfc8174.

      @@ -4482,7 +4484,7 @@

      C.1 Speci
    • Jens Ittel (SAP SE)
    • Patric Ksinsik (SAP SE)
      • -

      The contributions of the OASIS OData Technical Committee members, enumerated in ODataProtocol, are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      C.2 Participants

      diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index d4a614514..6acf08453 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -673,7 +673,7 @@ length. The value of `$MaxLength` is a positive integer. -Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic +Note: [OData-CSDLXML, section 3.4.1](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#MaxLength) defines a symbolic value `max` that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the @@ -993,8 +993,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the referenced schema document. ::: {.varjson .rep} @@ -1500,7 +1500,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varjson .rep} ### `$OpenType` @@ -1521,7 +1521,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue). An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -1582,7 +1582,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable @@ -1865,7 +1865,7 @@ If no value is specified, the client SHOULD NOT assume a default value. The value of `$DefaultValue` is the type-specific JSON representation of the default value of the property, see -[OData-JSON](#ODataJSON). For properties of type +[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). For properties of type `Edm.Decimal` and `Edm.Int64` the representation depends on the media type parameter [`IEEE754Compatible`](#ControllingtheRepresentationofNumbers). @@ -2072,7 +2072,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities). Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. @@ -2394,7 +2394,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varjson .rep} ### `$OpenType` @@ -3541,7 +3541,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -3683,10 +3683,10 @@ of the collection and specifies whether the collection MAY contain The value of `$DefaultValue` is the type-specific JSON representation of the default value of the term, see -[OData-JSON](#ODataJSON). +[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). Note: the `$DefaultValue` member is purely for documentation and -isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in +isomorphy to [OData-CSDLXML, section 7.3](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#DefaultValue). Annotations in CSDL JSON documents MUST always specify an explicit value. ::: @@ -4203,7 +4203,7 @@ Example 57: ### 14.3.13 Geo Values ::: {.varjson .rep} -Values are represented as GeoJSON, see [OData-JSON](#ODataJSON). +Values are represented as GeoJSON, see [RFC7946](#rfc7946). ::: ::: {.varjson .example} @@ -4218,7 +4218,7 @@ Example 58: ### 14.3.14 Stream Values ::: {.varjson .rep} -Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. +Constant values of type `Edm.Stream` are represented according to [OData-JSON, section 9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#StreamProperty) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. ::: @@ -4266,7 +4266,7 @@ than the `Edm.*Path` types. #### 14.4.1.1 Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions). A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -4402,7 +4402,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -4774,7 +4774,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators). The other comparison operators require two operand expressions that evaluate to comparable values. @@ -4912,7 +4912,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators). Operator|Description --------|----------- @@ -5045,10 +5045,10 @@ specification and its future versions. #### 14.4.4.1 Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions). For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -5230,7 +5230,7 @@ Example 80: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast). ::: {.varjson .rep} ### `$Cast` @@ -5558,7 +5558,7 @@ property value expression. The member name is the property name, and the member value is the property value expression. The type of a record expression is represented as the `type` control -information, see [OData-JSON](#ODataJSON). +information, see [OData-JSON, section 4.6.3](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationtypeodatatype). It MAY contain [annotations](#Annotation) for itself and its members. Annotations for record members are prefixed with the member name. @@ -6153,6 +6153,10 @@ https://www.rfc-editor.org/info/rfc6570. _The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_. https://www.rfc-editor.org/info/rfc7493. +###### [RFC7946]{id=rfc7946} +_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_. +https://www.rfc-editor.org/info/rfc7946. + ###### [RFC8174]{id=rfc8174} _Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. https://www.rfc-editor.org/info/rfc8174. @@ -6314,7 +6318,7 @@ especially the contributions of - Patric Ksinsik (SAP SE) The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index e934cf6bc..3c57b6db0 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -994,7 +994,7 @@

      4.1 Reference

      A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.

      A reference MUST specify a URI that uniquely identifies the referenced document, so two references MUST NOT specify the same URI. The URI SHOULD be a URL that locates the referenced document. If the URI is not dereferencable it SHOULD identify a well-known schema. The URI MAY be absolute or relative URI; relative URLs are relative to the URL of the document containing the reference, or relative to a base URL specified in a format-specific way.

      A reference MAY be annotated.

      -

      The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined OData-Protocol, SHOULD be used when retrieving the referenced schema document.

      +

      The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined in OData-Protocol, section 11.2.12, SHOULD be used when retrieving the referenced schema document.

      Element edmx:Reference

      The edmx:Reference element specifies external CSDL documents referenced by the referencing document. The child elements edmx:Include and edmx:IncludeAnnotations specify which parts of the referenced document are available for use in the referencing document.

      @@ -1238,7 +1238,7 @@

      6.3 O

      An entity type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

      An entity type derived from an open entity type MUST indicate that it is also open.

      -

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol.

      +

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

      Attribute OpenType

      The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.

      @@ -1247,7 +1247,7 @@

      Attribute

      6.4 Media Entity Type

       -

      An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol.

      +

      An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol, section 11.2.3.

      An entity type derived from a media entity type MUST indicate that it is also a media entity type.

      Media entity types MAY specify a list of acceptable media types using an annotation with term Core.AcceptableMediaTypes, see OData-VocCore.

      @@ -1278,7 +1278,7 @@

      6.5 Key

    • Edm.String
    • Edm.TimeOfDay
      • -

      Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol) MUST be language independent.

      +

      Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol, section 4.1) MUST be language independent.

      A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable single-valued complex properties, recursively.

      In OData 4.01 the key properties of a directly related entity type MAY also be part of the key if the navigation property is single-valued and not nullable. This includes navigation properties of non-nullable single-valued complex properties (recursively) of the entity type. If a key property of a related entity type is part of the key, all key properties of the related entity type MUST also be part of the key.

      If the key property is a property of a complex property (recursively) or of a directly related entity type, the key MUST specify an alias for that property that MUST be a simple identifier and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.

      @@ -1486,7 +1486,7 @@

      OData-URL.

      +

      Instances of the structured type that declares the navigation property, either directly or indirectly via a property of complex type, contain the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see OData-URL, section 4.3.2.

      Entity types used in collection-valued containment navigation properties MUST have a key defined.

      For items of an ordered collection of complex types (those annotated with the Core.Ordered term defined in OData-VocCore the canonical URL of the item is the canonical URL of the collection appended with a segment containing the zero-based ordinal of the item. Items within in an unordered collection of complex types do not have a canonical URL. Services that support unordered collections of complex types declaring a containment navigation property, either directly or indirectly via a property of complex type, MUST specify the URL for the navigation link within a payload representing that item, according to format-specific rules.

      OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.

      @@ -1637,7 +1637,7 @@

      9.

      A complex type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

      A complex type derived from an open complex type MUST indicate that it is also open.

      -

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData‑Protocol.

      +

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

      Attribute OpenType

      The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.

      @@ -2163,7 +2163,7 @@

      annotation applies a term to a model element and defines how to calculate a value for the applied term.

      Metadata annotations are terms applied to model elements. Behaviors or constraints described by a metadata annotation must be consistent with the annotated model element. Such annotations define additional behaviors or constraints on the model element, such as a service, entity type, property, function, action, or parameter. For example, a metadata annotation may define ranges of valid values for a particular property. Metadata annotations are applied in CSDL documents describing or referencing an entity model.

      -

      Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

      +

      Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON, section 20. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

      A vocabulary is a schema containing a set of terms where each term is a named metadata extension. Anyone can define a vocabulary (a set of terms) that is scenario-specific or company-specific; more commonly used terms can be published as shared vocabularies such as the OData Core vocabulary OData-VocCore.

      A term can be used to:

        @@ -2870,7 +2870,7 @@

        1

        14.4.1.1 Path Syntax

         -

        Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL.

        +

        Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL, section 5.1.1.15.

        A path MUST be composed of zero or more path segments joined together by forward slashes (/).

        Paths starting with a forward slash (/) are absolute paths, and the first path segment MUST be the qualified name of a model element, e.g. an entity container. The remaining path after the second forward slash is interpreted relative to that model element.

        @@ -2917,7 +2917,7 @@

        14.4.1.1 Path S 
        …/Items@Core.Description
        …/Items/@Core.Description

        -

        An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

        +

        An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL, section 4.3.1. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

        Example 67: instance path with entity set and key predicate

        /self.container/SettingsCollection('FeatureXxx')/IsAvailable
        @@ -3132,7 +3132,7 @@

        OData-URL.

        +

        The And and Or operators require two operand expressions that evaluate to Boolean values. The Not operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see OData-URL, section 5.1.1.1.

        The other comparison operators require two operand expressions that evaluate to comparable values.

        Expressions edm:And and edm:Or

        @@ -3198,7 +3198,7 @@

        Expressions ed

        14.4.3 Arithmetic Operators

         -

        Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL.

        +

        Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL, section 5.1.1.2.

      @@ -3292,7 +3292,7 @@

      Attribute

      14.4.4.1 Canonical Functions

       -

      All canonical functions defined in OData-URL can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL.

      +

      All canonical functions defined in OData-URL, section 5.1.1.4 can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL, section 5.1.1.4.

      For example, the odata.concat client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type Edm.String that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than Edm.String are represented according to the appropriate alternative in the primitiveValue rule of OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.

      Example 77:

      @@ -3371,7 +3371,7 @@

      14.4.5 Cast

      -

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL.

      +

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL, section 5.1.1.10.1.

      Expression edm:Cast

      The edm:Cast element MUST contain the Type attribute and MUST contain exactly one expression.

      @@ -4194,7 +4194,7 @@

      C.1 Special Thanks

      -

      The contributions of the OASIS OData Technical Committee members, enumerated in ODataProtocol, are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      C.2 Participants

      diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index 12d4e497d..a8a554ecf 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -928,8 +928,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the referenced schema document. @@ -1418,7 +1418,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varxml .rep} @@ -1439,7 +1439,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue). An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -1500,7 +1500,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable @@ -1956,7 +1956,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities). Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. @@ -2272,7 +2272,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varxml .rep} @@ -3347,7 +3347,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -4197,7 +4197,7 @@ than the `Edm.*Path` types. #### 14.4.1.1 Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions). A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -4333,7 +4333,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -4712,7 +4712,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators). The other comparison operators require two operand expressions that evaluate to comparable values. @@ -4801,7 +4801,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators). Operator|Description --------|----------- @@ -4897,10 +4897,10 @@ specification and its future versions. #### 14.4.4.1 Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions). For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -5038,7 +5038,7 @@ Example 80: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast). @@ -6042,7 +6042,7 @@ https://www.ogc.org/standard/sfa/. The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html index bf4590bc3..a84c280a3 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html @@ -2628,7 +2628,7 @@

      4 Cross-Joins and Aggregation

      OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships.

      -

      In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource $crossjoin instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See OData-URL for details.

      +

      In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource $crossjoin instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See OData-URL, section 4.15 for details.

      Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions.

      Example 47: if Sale had a string property ProductID instead of the navigation property Product, a “join” between Sales and Products could be accessed via the $crossjoin resource

      @@ -2674,7 +2674,7 @@

      5.1 Aggregation Capabilities

       -

      The term ApplySupported can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see example 50). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of $apply even if they do not specify the OpenType attribute, see OData-CSDL. The term has a complex type with the following properties:

      +

      The term ApplySupported can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see example 50). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of $apply even if they do not specify the OpenType attribute, see OData-CSDL, section 6.3. The term has a complex type with the following properties:

      • The Transformations collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If Transformations is omitted the server supports all transformations defined by this specification.
      • The CustomAggregationMethods collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported.
        • @@ -4922,7 +4922,7 @@

        B.1 Special Thanks

        -

        The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, are gratefully acknowledged.

        +

        The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      B.2 Participants

      diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md index 773993b50..8f691ab1c 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md @@ -2234,7 +2234,7 @@ The normative ABNF construction rules for this specification are defined in [ODa OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships. -In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL](#ODataURL) for details. +In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets) for details. Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions. @@ -2293,7 +2293,7 @@ The following terms are defined in the vocabulary for data aggregation [OData-Vo ## 5.1 Aggregation Capabilities -The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example 50](#containerrooted)). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL](#ODataCSDL). The term has a complex type with the following properties: +The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example 50](#containerrooted)). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL, section 6.3](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#OpenEntityType). The term has a complex type with the following properties: - The `Transformations` collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If `Transformations` is omitted the server supports all transformations defined by this specification. - The `CustomAggregationMethods` collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported. - `Rollup` specifies whether the service supports no rollup, only a single rollup hierarchy, or multiple rollup hierarchies in a [`groupby`](#Transformationgroupby) transformation. If omitted, multiple rollup hierarchies are supported. @@ -5012,7 +5012,7 @@ https://www.rfc-editor.org/info/rfc8174. ## B.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## B.2 Participants diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 66603c796..243ac6f87 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -578,7 +578,7 @@

      4.2 Message Bod

      4.3 URLs in Message Bodies

       -

      URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules as defined in OData-URL.

      +

      URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules as defined in OData-URL, section 2.1.

      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 (?), need not be percent-encoded.

      @@ -654,10 +654,10 @@

      4.6.1 Control Information: context (odata.context)

       -

      The context control information returns the context URL (see OData-Protocol) for the payload. This URL can be absolute or relative. The fragment portion of the context URL MUST NOT be percent-encoded.

      +

      The context control information returns the context URL (see OData-Protocol, section 10) for the payload. This URL can be absolute or relative. The fragment portion of the context URL MUST NOT be percent-encoded.

      The context control information is not returned if metadata=none is requested. Otherwise it MUST be the first property of any JSON response that allows this control information (this excludes for example error responses).

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

      -

      For more information on the format of the context URL, see OData-Protocol.

      +

      For more information on the format of the context URL, see OData-Protocol, section 10.

      Request payloads MAY include a context URL as a base URL for relative URLs in the request payload.

      Example 4:

      @@ -672,14 +672,14 @@

      4.6.2 Control Information: metadataEtag (odata.metadataEtag)

      The metadataEtag 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 metadataEtag control information to the metadata document’s ETag in all responses when using metadata=minimal or metadata=full. If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the metadataEtag control information in any responses.

      -

      For details on how ETags are used, see OData-Protocol.

      +

      For details on how ETags are used, see OData-Protocol, section 11.4.1.1.

      4.6.3 Control Information: type (odata.type)

      The type 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 OData-Version header with a value of 4.0, this name MUST be prefixed with the hash symbol (#); 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 type of the containing object. The root type may be absolute or relative to the root context URL.

      -

      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 $schemaversion system query option defined in OData-Protocol.

      -

      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 Collection. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML.

      +

      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 $schemaversion system query option defined in OData-Protocol, section 11.2.12.

      +

      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 Collection. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL.

      The type control information MUST appear in requests and in responses with minimal or full metadata, if the type cannot be heuristically determined, as described below, and one of the following is true:

      • The type is derived from the type specified for the (collection of) entities or (collection of) complex type instances, or
        • @@ -694,7 +694,7 @@

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

      The type control information can be absent in properties nested in an instance of type Edm.Untyped. In particular, individual primitive values within a collection cannot have type control information.

      -

      For more information on namespace- and alias-qualified names, see OData-CSDLJSON or OData-CSDLXML.

      +

      For more information on namespace- and alias-qualified names, see OData-CSDL.

      Example 5: entity of type Model.VipCustomer defined in the metadata document of the same service with a dynamic property of type Edm.Date

      {
@@ -740,7 +740,7 @@ 
 
-
      The id control information contains the entity-id, see OData-Protocol. By convention the entity-id is identical to the canonical URL of the entity, as defined in OData-URL.
      
+
      The id control information contains the entity-id, see OData-Protocol, section 4.1. By convention the entity-id is identical to the canonical URL of the entity, as defined in OData-URL, section 4.3.1.
      
 
      The id control information MUST appear in responses if metadata=full is requested, or if metadata=minimal is requested and any of a non-transient entity’s key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity after
      
 
 
      Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the id MUST be included if it does not match convention for the localized key values. If the id is represented, it MAY be a relative URL.
      
-
      If the entity is transient (see OData-Protocol), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 or greater payloads transient entities need not have the id control information, and clients receiving such payloads MUST treat entities with neither id control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the id control information with a non-null URI value, for example to allow solving a circular dependency by injecting an entity reference instead of repeating the transient entity. The URI value SHOULD follow the pattern odata:transient:{some-generated-identifier-unique-within-the-response}, and if the transient entity cannot be re-read its readLink control information SHOULD have the null value.
      
+
      If the entity is transient (see OData-Protocol, section 4.3), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 or greater payloads transient entities need not have the id control information, and clients receiving such payloads MUST treat entities with neither id control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the id control information with a non-null URI value, for example to allow solving a circular dependency by injecting an entity reference instead of repeating the transient entity. The URI value SHOULD follow the pattern odata:transient:{some-generated-identifier-unique-within-the-response}, and if the transient entity cannot be re-read its readLink control information SHOULD have the null value.
      
 
      The id control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.
      -

      The editLink control information contains the edit URL of the entity; see OData-Protocol.

      -

      The readLink control information contains the read URL of the entity or collection; see OData-Protocol.

      +

      The editLink control information contains the edit URL of the entity; see OData-Protocol, section 4.2.

      +

      The readLink control information contains the read URL of the entity or collection; see OData-Protocol, section 4.2.

      The editLink and readLink control information is ignored in request payloads and not written in responses if metadata=none is requested.

      The default value of both the edit URL and read URL is the entity’s entity-id 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 editLink nor the readLink control information is present in an entity, the client uses this default value for the edit URL.

      For updatable entities:

      @@ -778,7 +778,7 @@

      4.6.10 Control Information: etag (odata.etag)

      The etag control information MAY be applied to an entity 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.

      -

      For details on how ETags are used, see OData-Protocol.

      +

      For details on how ETags are used, see OData-Protocol, section 11.4.1.1.

      The etag control information is ignored in request payloads for single entities and not written in responses if metadata=none is requested.

      @@ -854,7 +854,7 @@

      5 Se

      A service document in JSON is represented as a single JSON object with at least the context control information and a property value.

      The value of the context control information MUST be the URL of the metadata document, without any fragment part.

      -

      The value of the value property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of true for the attribute IncludeInServiceDocument and each singleton exposed by the service, see OData-CSDLJSON or OData-CSDLXML.

      +

      The value of the value property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of true for the attribute IncludeInServiceDocument and each singleton exposed by the service, see OData-CSDL.

      Each element MUST be a JSON object with at least two name/value pairs, one with name name containing the name of the entity set, function import, or singleton, and one with name url containing the URL of the entity set, which may be an absolute or a relative URL. It MAY contain a name/value pair with name title containing a human-readable, language-dependent title for the object.

      JSON objects representing an entity set MAY contain an additional name/value pair with name kind and a value of EntitySet. If the kind name/value pair is not present, the object MUST represent an entity set.

      JSON objects representing a function import MUST contain the kind name/value pair with a value of FunctionImport.

      @@ -904,7 +904,7 @@

      6 Entity

      An entity is serialized as a JSON object. It MAY contain context, type, or deltaLink control information.

      Each property to be transmitted is represented as a name/value pair within the object. The order properties appear within the object is considered insignificant.

      -

      An entity in a payload may be a complete entity, a projected entity (see System Query Option $select in OData-Protocol), or a partial entity update (see Update an Entity in OData-Protocol).

      +

      An entity in a payload may be a complete entity, a projected entity (see OData-Protocol, section 11.2.5.1), or a partial entity update (see OData-Protocol, section 11.4.3).

      An entity representation can be (modified and) round-tripped to the service directly. The context URL is used in requests only as a base for relative URLs.

      Example 10: entity with metadata=minimal

      @@ -1058,9 +1058,10 @@

      7.5 Untyped

      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.

      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.

      A primitive value within an untyped collection is interpreted as an Edm.Boolean, Edm.String, or Edm.Decimal value, depending on the JavaScript type.

      -

      Collections directly contained within an untyped collection are themselves untyped.

      +

      Collections directly contained within an untyped collection are themselves untyped.

      +

      8 Navigation Property

       @@ -1228,7 +1229,7 @@

      9 Strea
    • Stream properties requested with $select or included in the default selection are represented by media* control information.
    • Stream properties requested with $expand or implicitly expanded are represented as a property with its value.
      • -

      See OData-Protocol for details on the system query options $select and $expand.

      +

      See OData-Protocol, section 11.2.5.1 for details on the system query options $select and $expand.

      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 their 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 with an explicit or default charset of utf-8 or us-ascii, 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.

      @@ -1269,7 +1270,7 @@

      10 Media Entity

      11 Individual Property or Operation Response

      An individual property or operation response is represented as a JSON object.

      -

      A single-valued property or operation response that has the null value does not have a representation; see OData-Protocol.

      +

      A single-valued property or operation response that has the null value does not have a representation; see OData-Protocol, section 9.1.4.

      A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is value and whose value is a primitive value.

      A property or operation response that is of complex type is represented as a complex value.

      A property or operation response that is of a collection type is represented as an object with a single name/value pair whose name is value. Its value is the JSON representation of a collection of complex type values or collection of primitive values.

      @@ -1351,7 +1352,7 @@

      14 Entity Reference

      -

      An entity reference (see OData-Protocol) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the id of the referenced entity and MAY contain the type control information and instance annotations, but no additional properties or control information.

      +

      An entity reference (see OData-Protocol, section 4.1) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the id of the referenced entity and MAY contain the type control information and instance annotations, but no additional properties or control information.

      A collection of entity references is represented as a collection of entities, with entity reference representations instead of entity representations as items in the array value of the value name/value pair.

      The outermost JSON object in a response MUST contain a context control information and MAY contain count, nextLink, or deltaLink control information.

      @@ -1447,7 +1448,7 @@

      15.1

      15.2 Added/Changed Entity

      Added or changed entities within a delta payload are represented as entities. All entities within a delta response payload MUST include the control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity.

      -

      When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      +

      When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      Any entity in an update request that has neither the id control information, nor the primary or alternate key values of an existing entity, are treated as an added entity.

      Added entities MUST include all available selected properties and MAY include additional, unselected properties. Collection-valued properties are treated as atomic values; any collection-valued properties returned from a delta request MUST contain all current values for that collection.

      Changed entities MUST include all available selected properties that have changed, and MAY include additional properties.

      @@ -1479,7 +1480,7 @@

      15.3 Del

      In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value. For ordered payloads, this control information MUST follow the payload ordering constraints.

      • Control information removed, whose value is an object that MAY contain a property named reason. If present, the value of reason MUST be either deleted if the entity was deleted (destroyed), or changed if the entity was removed from membership in the result either due to change in value such that the entity no longer matches the defining query or because the entity was removed from the collection. The object MAY include annotations, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification.

        • -

      • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

        • +

      • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      For full metadata the context control information MUST be included. It also MUST be included if the entity set of the deleted entity cannot be determined from the surrounding context.

      The deleted-entity object MAY include additional properties of the entity, as well as annotations, and MAY include related entities, related deleted entities, or a delta or full representation of a related collection of entities, to represent related entities that have been modified or deleted.

      @@ -1911,7 +1912,7 @@

      16 Bound Function

       -

      A bound function is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule qualifiedFunctionName in OData-ABNF.

      +

      A bound function is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL. A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule qualifiedFunctionName in OData-ABNF.

      A function that is bound to a single structured type MAY be advertised within the JSON object representing that structured type.

      Functions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the function advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the function advertisement is prepended with the name of the collection-valued property and is placed next to the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise functions prefixed with property names.

      If the function is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the function with the value null.

      @@ -1967,7 +1968,7 @@

      16 Bound

      17 Bound Action

       -

      A bound action is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML

      +

      A bound action is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL.

      An action that is bound to a single structured type is advertised within the JSON object representing that structured type.

      Actions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the action advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the action advertisement is prepended with the name of the collection-valued property and is placed next to the name/value pair representing the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise actions prefixed with property names.

      If the action is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the action with the value null.

      @@ -2113,16 +2114,16 @@

      19.1 Batch

      A JSON batch request body consists of a single JSON object that MUST contain the name/value pair requests and MAY contain annotations. It does not contain the context control information.

      The value of requests is an array of request objects, each representing an individual request. Note: an individual request MUST NOT itself be a batch request.

      A request object MUST contain the name/value pairs id, method and url, and it MAY contain the name/value pairs atomicityGroup, dependsOn, if, headers, and body.

      -

      The value of id is a string containing the request identifier of the individual request, see OData-Protocol. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.

      -

      Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol.

      +

      The value of id is a string containing the request identifier of the individual request, see OData-Protocol, section 11.7.3. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.

      +

      Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

      The value of method is a string that MUST contain one of the literals delete, get, patch, post, or put. These literals are case-insensitive.

      The value of url is a string containing the individual request URL. The URL MAY be an absolute path (starting with a forward slash /) which is appended to scheme, host, and port of the batch request URL, or a relative path (not starting with a forward slash /).

      If the first segment of a relative path starts with a $ character and is not identical to the name of a top-level system resource ($batch, $crossjoin, $all, $entity, $root, $id, $metadata, or other system resources defined according to the OData-Version of the protocol specified in the request), then this first segment is replaced with the URL of the entity created by or returned from a preceding request whose id value is identical to the value of the first segment with the leading $ character removed. The id of this request MUST be specified in the dependsOn name/value pair.

      Otherwise, the relative path is resolved relative to the batch request URL (i.e. relative to the service root).

      The value of atomicityGroup is a string whose content MUST NOT be identical to any value of id within the batch request, and which MUST satisfy the rule request-id in OData-ABNF. All request objects with the same value for atomicityGroup MUST be adjacent in the requests array. These requests are processed as an atomic operation and MUST either all succeed, or all fail.

      -

      Note: the atomicity group is a generalization of the change set in the multipart batch format specified in OData-Protocol.

      +

      Note: the atomicity group is a generalization of the change set in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

      The value of dependsOn is an array of strings whose values MUST be values of either id or atomicityGroup of preceding request objects; forward references are not allowed. If a request depends on another request that is part of a different atomicity group, the atomicity group MUST be listed in dependsOn. In the absence of the optional if member a request that depends on other requests or atomicity groups is only executed if those requests were executed successfully, i.e. with a 2xx response code. If one of the requests it depends on has failed, the dependent request is not executed and a response with status code of 424 Failed Dependency is returned for it as part of the batch response.

      -

      The if member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see OData-URL) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows

      +

      The if member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see OData-URL, section 5.1.1) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows

      • $<content-id>/$succeeded to check if the referenced request has succeeded
      • $<content-id> to reference the response body of the referenced request
        • @@ -2316,7 +2317,7 @@

        19.6 Bat

        A JSON batch response body consists of a single JSON object that MUST contain the name/value pair responses and MAY contain annotations. It does not contain the context control information.

        The value of responses is an array of response objects, each representing an individual response.

        A JSON batch response MAY be a partial result containing the nextLink control information. This allows services to chunk results into manageable pieces, or to return results for already processed requests and continue processing the remaining individual requests while waiting for the client to fire a GET request to the next link.

        -

        In a response to a batch request using the multipart format defined in OData-Protocol the response objects MUST appear in the same order as required for multipart batch responses because the Content-ID header is not required outside of change sets. Response objects corresponding to requests that specify a Content-ID header MUST contain the id name/value pair, and the value of id MUST be the value of the Content-ID header of the corresponding request. This is necessarily the case for requests contained within a change set. Responses to requests within a change set MUST contain the atomicityGroup name/value pair with a value common within a change set and unique across change sets.

        +

        In a response to a batch request using the multipart format defined in OData-Protocol, section 11.7.7 the response objects MUST appear in the same order as required for multipart batch responses because the Content-ID header is not required outside of change sets. Response objects corresponding to requests that specify a Content-ID header MUST contain the id name/value pair, and the value of id MUST be the value of the Content-ID header of the corresponding request. This is necessarily the case for requests contained within a change set. Responses to requests within a change set MUST contain the atomicityGroup name/value pair with a value common within a change set and unique across change sets.

        In a response to a batch request using the JSON batch request format specified in the preceding section the response objects MAY appear in any order, and each response object MUST contain the id name/value pair with the same value as in the corresponding request object. If the corresponding request object contains the atomicityGroup name/value pair, it MUST also be present in the response object with the same value.

        If any response within an atomicity group returns a failure code, all requests within that atomicity group are considered failed, regardless of their individual returned status code. The service MAY return 424 Failed Dependency for statements within an atomicity group that fail or are not attempted due to other failures within the same atomicity group.

        A response object MUST contain the name/value pair status whose value is a number representing the HTTP status code of the response to the individual request.

        @@ -2450,7 +2451,7 @@

        20 Instance Annotations

        Annotations are an extensibility mechanism that allows services and clients to include information other than the raw data in the request or response.

        -

        Annotations are name/value pairs that have an at (@) and a dot (.) as part of the name. The part after the “at” sign (@) is the annotation identifier. It consists of the namespace or alias of the schema that defines the term, followed by a dot (.), followed by the name of the term, optionally followed by a hash (#) and a qualifier. The namespace or alias MUST be defined in the metadata document, see OData-CSDLJSON or OData-CSDLXML

        +

        Annotations are name/value pairs that have an at (@) and a dot (.) as part of the name. The part after the “at” sign (@) is the annotation identifier. It consists of the namespace or alias of the schema that defines the term, followed by a dot (.), followed by the name of the term, optionally followed by a hash (#) and a qualifier. The namespace or alias MUST be defined in the metadata document, see OData-CSDL.

        The annotation identifier odata is reserved for future extensions of the protocol and format. Instance annotations MUST have a namespace or alias that is different from odata.

        Annotations can be applied to any name/value pair in a JSON payload that represents a value of any type from the entity data model. Clients should never error due to an unexpected annotation in a JSON payload.

        Annotations are always expressed as name/value pairs. For entity data model constructs represented as JSON objects the annotation name/value pairs are placed within the object; for constructs represented as JSON arrays or primitives, including null, they are placed next to the annotated model construct and have the name of the annotated property before the @. An annotation in the latter format can also take the place of an absent property. When annotating a payload that represents a single primitive or collection value, the annotations for the value appear next to the value property and are not prefixed with a property name.

        @@ -2534,7 +2535,7 @@

        21.1 Err

        21.2 In-Stream Error

        In the case that a service encounters an error after sending a success status to the client, the service MUST leave the response malformed. This can be achieved by immediately stopping response serialization and thus omitting (among others) the end-object character of the top-level JSON object in the response.

        -

        Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see OData-Protocol.

        +

        Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see OData-Protocol, section 8.3.5.

        The value of the OData-Error trailing header is an OData error object as defined in the preceding chapter, represented in a header-appropriate way:

      C.2 Participants

      diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 231c32917..e91a3a14e 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -600,7 +600,7 @@ order of objects within an array in JSON responses. ## 4.3 URLs in Message Bodies URLs represented as a string within a JSON payload, including [batch -requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL](#ODataURL). +requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL, section 2.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLParsing). For [relative URLs](#RelativeURLs) this means that colons (`:`) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the @@ -760,7 +760,7 @@ stop processing and MUST NOT signal an error. ### 4.6.1 Control Information: `context` (`odata.context`) The `context` control information -returns the context URL (see [OData-Protocol](#ODataProtocol)) for the +returns the context URL (see [OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL)) for the payload. This URL can be absolute or [relative](#RelativeURLs). The fragment portion of the context URL MUST NOT be percent-encoded. @@ -774,7 +774,7 @@ entity set cannot be determined from the context URL of the collection. For more information on the format of the context URL, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL). Request payloads MAY include a context URL as a base URL for [relative URLs](#RelativeURLs) in the request payload. @@ -805,7 +805,7 @@ If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the `metadataEtag` control information in any responses. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [OData-Protocol, section 11.4.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts). ### 4.6.3 Control Information: `type` (`odata.type`) @@ -826,7 +826,7 @@ The root `type` may be absolute or relative to the root 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 `$schemaversion` system query option -defined in [OData-Protocol](#ODataProtocol). +defined in [OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion). For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI @@ -835,8 +835,7 @@ fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with `Collection`. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). The `type` control information MUST appear in requests and in responses with [minimal](#metadataminimalodatametadataminimal) or @@ -878,8 +877,7 @@ The `type` control information can be absent in properties nested in an instance In particular, individual primitive values within a collection cannot have `type` control information. For more information on namespace- and alias-qualified names, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). ::: example Example 5: entity of type @@ -950,9 +948,9 @@ control information. ### 4.6.8 Control Information: `id` (`odata.id`) The `id` control information contains the entity-id, see -[OData-Protocol](#ODataProtocol). By convention the entity-id is +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences). By convention the entity-id is identical to the canonical URL of the entity, as defined in -[OData-URL](#ODataURL). +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The `id` control information MUST appear in responses if [`metadata=full`](#metadatafullodatametadatafull) @@ -972,7 +970,7 @@ if it does not match convention for the localized key values. If the `id` is represented, it MAY be a [relative URL](#RelativeURLs). -If the entity is transient (see [OData-Protocol](#ODataProtocol)), the +If the entity is transient (see [OData-Protocol, section 4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#TransientEntities)), the `id` control information MUST appear in OData 4.0 payloads and have the `null` value. In 4.01 or greater payloads transient entities need not have the `id` control information, and @@ -991,10 +989,10 @@ of this specification. ### 4.6.9 Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains -the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol](#ODataProtocol). +the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol, section 4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs). The `readLink` control information contains the read URL of -the entity or collection; see [OData-Protocol](#ODataProtocol). +the entity or collection; see [OData-Protocol, section 4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs). The `editLink` and `readLink` control information is ignored in request payloads and not written in responses if @@ -1048,7 +1046,7 @@ 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. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [OData-Protocol, section 11.4.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts). The `etag` control information is ignored in request payloads for single entities and not written in responses if @@ -1211,7 +1209,7 @@ The value of the `value` property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of `true` for the attribute `IncludeInServiceDocument` and each singleton exposed by the -service, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +service, see [OData-CSDL](#ODataCSDL). Each element MUST be a JSON object with at least two name/value pairs, one with name `name` containing the name of the entity set, @@ -1300,9 +1298,8 @@ represented as a name/value pair within the object. The order properties appear within the object is considered insignificant. An entity in a payload may be a complete entity, a projected entity (see -_System Query Option_ `$select` in -[OData-Protocol](#ODataProtocol)), or a partial entity update (see -_Update an Entity_ in [OData-Protocol](#ODataProtocol)). +[OData-Protocol, section 11.2.5.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect)), or a partial entity update (see +[OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity)). An entity representation can be (modified and) round-tripped to the service directly. The [context @@ -1557,6 +1554,7 @@ A primitive value within an untyped collection is interpreted as an `Edm.Boolean depending on the JavaScript type. Collections directly contained within an untyped collection are themselves untyped. + ------- # 8 Navigation Property @@ -1823,7 +1821,7 @@ Instead stream property data is generally read and edited via URLs. [`media*`](#ControlInformationmediaodatamedia) control information. - Stream properties requested with `$expand` or implicitly expanded are represented as a property with its value. -See [OData-Protocol](#ODataProtocol) for details on the system query options `$select` and `$expand`. +See [OData-Protocol, section 11.2.5.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect) for details on the system query options `$select` and `$expand`. Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), the stream property MAY be annotated to provide the read link, edit @@ -1898,7 +1896,7 @@ object. A single-valued property or operation response that has the `null` value does not have a representation; see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 9.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ResponseCode204NoContent). A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is @@ -2058,7 +2056,7 @@ Example 31: # 14 Entity Reference -An entity reference (see [OData-Protocol](#ODataProtocol)) MAY take the +An entity reference (see [OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the [id](#ControlInformationidodataid) of the referenced entity and MAY contain the [`type`](#ControlInformationtypeodatatype) @@ -2203,7 +2201,7 @@ Added or changed entities within a delta payload are represented as the control information [`id`](#ControlInformationidodataid) or all of the entity's primary key fields. The `id` control information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical URL of the entity. -When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) +When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [OData-URL, section 4.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys)) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. @@ -2295,7 +2293,7 @@ For ordered payloads, this control information MUST follow the [payload ordering or all of the entity's primary key fields. The `id` control information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical - URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) + URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [OData-URL, section 4.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys)) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. @@ -2829,8 +2827,7 @@ A bound function is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) A +service, see [OData-CSDL](#ODataCSDL). A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule @@ -2947,8 +2944,7 @@ A bound action is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) +service, see [OData-CSDL](#ODataCSDL). An action that is bound to a single structured type is advertised within the JSON object representing that structured type. @@ -3203,13 +3199,13 @@ name/value pairs `atomicityGroup`, `dependsOn`, `if`, `headers`, and `body`. The value of `id` is a string containing the request identifier of the individual request, see -[OData-Protocol](#ODataProtocol). It MUST NOT be identical to the value +[OData-Protocol, section 11.7.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#IdentifyingIndividualRequests). It MUST NOT be identical to the value of any other request identifier nor any `atomicityGroup` within the batch request. Note: the `id` name/value pair corresponds to the `Content-ID` header in the multipart batch format specified -in [OData-Protocol](#ODataProtocol). +in [OData-Protocol, section 11.7.7.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody). The value of `method` is a string that MUST contain one of the literals `delete`, `get`, `patch`, `post`, or `put`. @@ -3244,7 +3240,7 @@ request, and which MUST satisfy the rule `request-id` in operation and MUST either all succeed, or all fail. Note: the atomicity group is a generalization of the change set in the -multipart batch format specified in [OData-Protocol](#ODataProtocol). +multipart batch format specified in [OData-Protocol, section 11.7.7.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody). The value of `dependsOn` is an array of strings whose values MUST be values of either `id` or `atomicityGroup` @@ -3260,7 +3256,7 @@ dependent request is not executed and a response with status code of The `if` member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see -[OData-URL](#ODataURL)) that evaluates to a Boolean value. +[OData-URL, section 5.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CommonExpressionSyntax)) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows - `$/$succeeded` @@ -3531,7 +3527,7 @@ processing the remaining individual requests while waiting for the client to fire a `GET` request to the next link. In a response to a batch request using the multipart format defined in -[OData-Protocol](#ODataProtocol) the response objects +[OData-Protocol, section 11.7.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchFormat) the response objects MUST appear in the same order as required for multipart batch responses because the `Content-ID` header is not required outside of change sets. Response objects corresponding to requests that specify a `Content-ID` header MUST contain the @@ -3768,7 +3764,7 @@ dot (`.`) as part of the name. The part after the "at" sign namespace or alias of the schema that defines the term, followed by a dot (`.`), followed by the name of the term, optionally followed by a hash (`#`) and a qualifier. The namespace or alias MUST be defined in the -metadata document, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) +metadata document, see [OData-CSDL](#ODataCSDL). The annotation identifier `odata` is reserved for future extensions of the protocol and format. Instance annotations MUST have a @@ -3934,7 +3930,7 @@ JSON object in the response. Services MAY include the header `OData-Error` as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 8.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#HeaderODataError). The value of the `OData-Error` trailing header is an OData error object as defined in the preceding chapter, represented in a @@ -4073,7 +4069,7 @@ In order to be a conforming producer of the OData JSON format, a client or servi In addition, in order to conform to the OData JSON format, a service: -11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) +11. MUST comply with one of the conformance levels defined in [OData-Protocol, section 12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance) 12. MUST support the `application/json` media type in the `Accept` header ([section 3](#RequestingtheJSONFormat)) 13. MUST return well-formed JSON payloads 14. MUST support `odata.metadata=full` ([section 3.1.2](#metadatafullodatametadatafull)) @@ -4194,7 +4190,7 @@ For JSON-relevant security implications please cf. at least the relevant subsect ## C.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 83fc639c6..35d02a8b8 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -549,7 +549,7 @@

      1 Introduction

      The Open Data Protocol (OData) enables the creation of REST-based data services which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines the core semantics and the behavioral aspects of the protocol.

      The OData-URL specification defines a set of rules for constructing URLs to identify the data and metadata exposed by an OData service as well as a set of reserved URL query options.

      The OData-CSDLJSON specification defines a JSON representation of the entity data model exposed by an OData service.

      -

      The OData-CSDLXML specification defines an XML representation of the entity data model exposed by an OData service.

      +

      The OData-CSDLXML specification defines an XML representation of the entity data model exposed by an OData service.

      The OData-JSON document specifies the JSON format of the resource representations that are exchanged using OData.

      1.1 Changes from Earlier Versions

      @@ -704,7 +704,7 @@

      3 Data Model

      Operations allow the execution of custom logic on parts of a data model. Functions are operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action. Actions are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior. Actions and functions are either bound to a type, enabling them to be called as members of an instance of that type, or unbound, in which case they are called as static operations. Action imports and function imports enable unbound actions and functions to be called from the service root.

      Singletons are named entities which can be accessed as direct children of the entity container. A singleton may also be a member of an entity set.

      An OData resource is anything in the model that can be addressed (an entity set, entity, property, or operation).

      -

      Refer to OData-CSDLJSON or OData-CSDLXML for more information on the OData entity data model.

      +

      Refer to OData-CSDLJSON or OData-CSDLXML for more information on the OData entity data model.

      3.1 Annotations

       @@ -729,7 +729,7 @@

      4 Service Mod

      4.1 Entity-Ids and Entity References

      Whereas entities within an entity set are uniquely identified by their key values, entities are also uniquely identified by a durable, opaque, globally unique entity-id. The entity-id MUST be an IRI as defined in RFC3987 and MAY be expressed in payloads, headers, and URLs as a relative reference as appropriate. While the client MUST be prepared to accept any IRI, services MUST use valid URIs in this version of the specification since there is currently no lossless representation of an IRI in the EntityId header.

      -

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the Core.DereferenceableIDs term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource $entity provides a general mechanism for resolving an entity-id into an entity representation.

      +

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL, section 4.3.1 as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the Core.DereferenceableIDs term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource $entity provides a general mechanism for resolving an entity-id into an entity representation.

      Services that use the standard URL conventions for entity-ids annotate their entity container with the term Core.ConventionalIDs, see OData-VocCore.

      Entity references refer to an entity using the entity’s entity-id.

      @@ -739,7 +739,7 @@

      OData-URL for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.

      +

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL, section 4.3.1 for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.

      4.3 Transient Entities

      @@ -868,7 +868,7 @@

      media entity or stream property, in which case the Content-Type header SHOULD be present.

      The specified format MAY include format parameters. Clients MUST be prepared for the service to return custom format parameters not defined in OData and SHOULD NOT expect that such format parameters can be ignored. Custom format parameters MUST NOT start with odata and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload.

      -

      See OData-JSON for format-specific details about format parameters within the Content-Type header.

      +

      See OData-JSON, section 4.1 for format-specific details about format parameters within the Content-Type header.

      8.1.2 Header Content-Encoding

      @@ -1158,7 +1158,7 @@

      8.3.5 Header OData-Error

      A response with an in-stream error MAY include an OData-Error trailing header if the transport protocol supports trailing headers (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).

      -

      The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. OData-JSON.

      +

      The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. OData-JSON, section 21.2.

      8.3.6 Header Preference-Applied

      @@ -1593,14 +1593,14 @@

      10.19 $

      Context URL template:

      {context-url}#Collection(Edm.EntityType)
      -

      Responses to requests to the virtual collection $all (see OData-URL) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton.

      +

      Responses to requests to the virtual collection $all (see OData-URL, section 4.16) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton.

      10.20 $crossjoin Response

      Context URL template:

      {context-url}#Collection(Edm.ComplexType)
      -

      Responses to requests to the virtual collections $crossjoin(…) (see OData-URL) use the built-in abstract complex type. Single instances in these responses do not have a context URL.

      +

      Responses to requests to the virtual collections $crossjoin(…) (see OData-URL, section 4.15) use the built-in abstract complex type. Single instances in these responses do not have a context URL.

      @@ -1661,7 +1661,7 @@

      data model that describes the data and operations exposed by an OData service.

      OData-CSDLJSON describes a JSON representation for OData metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is application/json.

      -

      OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

      +

      OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

      OData services can expose a metadata document that describes the data model exposed by the service. The metadata document URL MUST be the root URL of the service with $metadata appended. To retrieve this document the client issues a GET request to the metadata document URL.

      If a request for metadata does not specify a format preference (via Accept header or $format) then the XML representation MUST be returned.

      @@ -1704,7 +1704,7 @@

      11.2.2 Requesting Individual Entities

      To retrieve an individual entity, the client makes a GET request to a URL that identifies the entity, e.g. its read URL.

      -

      The read URL can be obtained from a response payload containing that instance, for example as a readLink or editLink in an OData-JSON payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in OData-URL.

      +

      The read URL can be obtained from a response payload containing that instance, for example as a readLink or editLink in an OData-JSON, section 4.6.9 payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in OData-URL, section 4.3.1.

      The set of structural or navigation properties to return may be specified through $select or $expand system query options.

      Clients MUST be prepared to receive additional properties in an entity or complex type instance that are not advertised in metadata, even for types not marked as open.

      Properties that are not available are not returned. If their unavailability is due to permissions, the Core.Permissions annotation, defined in OData-VocCore MUST be returned for the property with a value of None. If the omit-values preference is applied, Core.Permissions or another specific annotation that explains the reason MUST be returned for every unavailable property.

      @@ -1724,7 +1724,7 @@

      OData-URL for details.

      +

      See OData-URL, section 4.6 for details.

      If the property is single-valued and has the null value, the service responds with 204 No Content.

      If the property is not available, for example due to permissions, the service responds with 404 Not Found.

      @@ -1740,7 +1740,7 @@

      11.2.4.2 Requesting a Raw Value using $value

       -

      To retrieve the raw value of a primitive property or operation result, the client sends a GET request to the raw value URL. See the OData-URL document for details.

      +

      To retrieve the raw value of a primitive property or operation result, the client sends a GET request to the raw value URL. See OData-URL, section 4.7 for details.

      The Content-Type of the response is determined using the Accept header and the $format system query option.

      The default format for Edm.Binary is the format specified by the Core.MediaType annotation (see OData-VocCore) if this annotation is present. If not annotated, the format cannot be predicted by the client.

      The default format for Edm.Geo types is text/plain using the WKT (well-known text) format, see rules fullCollectionLiteral, fullLineStringLiteral, fullMultiPointLiteral, fullMultiLineStringLiteral, fullMultiPolygonLiteral, fullPointLiteral, and fullPolygonLiteral in OData-ABNF.

      @@ -1812,7 +1812,7 @@

      11.2.5.2.1 Expand Options

      -

      The set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see OData-URL.

      +

      The set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see OData-URL, section 5.1.3.

      Allowed system query options are $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.

      Example 41: for each customer entity within the Customers entity set, the value of those related Orders whose Amount is greater than 100 will be represented inline

      @@ -2200,12 +2200,12 @@

      OData-JSON.

      +

      is equivalent to a request with an Accept header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in OData-JSON, section 3.1.2.

      Example 75: the request

      GET http://host/service/Orders?$format=json
      -

      is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON.

      +

      is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON, section 3.1.1.

      In metadata document requests, the values application/xml and application/json, along with their subtypes and parameterized variants, as well as the format-specific abbreviations xml and json, are reserved for this specification.

      @@ -2569,7 +2569,7 @@

      11.

      11.4.6 Modifying Relationships between Entities

       -

      Relationships between entities are represented by navigation properties as described in Data Model. URL conventions for navigation properties are described in OData-URL.

      +

      Relationships between entities are represented by navigation properties as described in Data Model. URL conventions for navigation properties are described in OData-URL, section 4.3.3.

      11.4.6.1 Add a Reference to a Collection-Valued Navigation Property

       @@ -2581,7 +2581,7 @@

      11.4.6.2 Remove a Reference to an Entity

      A successful DELETE request to the URL that represents a reference to a related entity removes the relationship to that entity.

      -

      In OData 4.0, the entity reference to be removed within a collection-valued navigation property is the URL that represents the collection of related references, with the reference to be removed identified by the $id query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as described in OData-URL.

      +

      In OData 4.0, the entity reference to be removed within a collection-valued navigation property is the URL that represents the collection of related references, with the reference to be removed identified by the $id query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as described in OData-URL, section 4.4.

      For single-valued navigation properties, the $id query option MUST NOT be specified.

      The DELETE request MUST NOT violate any integrity constraints in the data model.

      On successful completion, the response MUST be 204 No Content and contain an empty body.

      @@ -2591,7 +2591,7 @@

      A successful PUT request to a single-valued navigation property’s reference resource changes the related entity. The request body MUST contain a single entity reference that identifies the existing entity to be related. See the appropriate format document for details.

      On successful completion, the response MUST be 204 No Content and contain an empty body.

      -

      Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see OData-JSON for details.

      +

      Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see OData-JSON, section 15.4 for details.

      If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with 405 Method Not Allowed or an other appropriate error.

      @@ -2680,7 +2680,7 @@

      11.4.9 Managing Values and Properties Directly

       -

      Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows properties to be individually modified. See OData-URL for details on addressing individual properties.

      +

      Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows properties to be individually modified. See OData-URL, section 4.6 for details on addressing individual properties.

      11.4.9.1 Update a Primitive Property

       @@ -2790,7 +2790,7 @@

      11.4.14 Update Members of a Collection

      Members of a collection can be updated by submitting a PATCH request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the request body describes an update to each member of the collection, not an update to the collection itself.

      -

      The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL.

      +

      The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL, section 4.11 and OData-URL, section 4.12.

      For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is updated to the specified primitive value.

      For collections of structured type, the body of the request MUST be a full or partial representation of an instance of the collection’s structured type. Each member of the potentially filtered collection is updated using PATCH semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in Update a Collection of Entities applies.

      @@ -2825,7 +2825,7 @@

      11.5 Operations

       -

      Custom operations (Actions and Functions) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See Action, ActionImport, Function, and FunctionImport in OData-CSDLJSON or OData-CSDLXML.

      +

      Custom operations (Actions and Functions) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See Action, ActionImport, Function, and FunctionImport in OData-CSDLJSON or OData-CSDLXML.

      11.5.1 Binding an Operation to a Resource

       @@ -2884,7 +2884,7 @@

      … }

      -

      An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL.

      +

      An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL, section 4.5.

      Services can advertise that a function or action is not available for a particular instance by setting its value to null.

      Example 93: the SampleEntities.MostRecentOrder function is not available for customer ALFKI

      @@ -2922,7 +2922,7 @@

      204 No Content.

      If a single-valued function with a non-nullable return type has no result, the service returns 4xx. For functions that return a single entity 404 Not Found is the appropriate response code.

      For a composable function the processing is stopped when the function result requires a 4xx response, and continues otherwise.

      -

      Function imports preceded by the $root literal MAY be used in the $filter or $orderby system query options, see OData-URL.

      +

      Function imports preceded by the $root literal MAY be used in the $filter or $orderby system query options, see OData-URL, section 5.1.2 and OData-URL, section 5.1.5.

      11.5.4.1.1 Inline Parameter Syntax
       @@ -2955,7 +2955,7 @@

      The same function name may be used multiple times within a schema, each with a different set of parameters. For unbound overloads the combination of the function name and the unordered set of parameter names MUST identify a particular function overload. For bound overloads the combination of the function name, the binding parameter type, and the unordered set of names of the non-binding parameters MUST identify a particular function overload.

      All unbound overloads MUST have the same return type. Also, all bound overloads with a given binding parameter type MUST have the same return type.

      -

      If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the hierarchy, see OData-URL.

      +

      If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the hierarchy, see OData-URL, section 4.11.

      Non-binding parameters MAY be marked as optional by annotating them with the term Core.OptionalParameter defined in OData-VocCore. All parameters marked as optional MUST come after any parameters not marked as optional.

      A function overload is selected if

        @@ -3002,7 +3002,7 @@

        11.5.5.2 Action Overload Resolution

        The same action name may be used multiple times within a schema provided there is at most one unbound overload, and each bound overload specifies a different binding parameter type.

        -

        If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, see OData-URL.

        +

        If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, see OData-URL, section 4.11.

      @@ -3027,7 +3027,7 @@

      11.7 Bat

      Batch requests allow grouping multiple individual requests into a single HTTP request payload. An individual request in the context of a batch request is a Metadata Request, Data Request, Data Modification Request, Action invocation request, or Function invocation request.

      Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service, located at the URL $batch relative to the service root.

      Individual requests within a batch request are evaluated according to the same semantics used when the request appears outside the context of a batch request.

      -

      A batch request is represented using either the multipart batch format defined in this document or the JSON batch format defined in OData-JSON.

      +

      A batch request is represented using either the multipart batch format defined in this document or the JSON batch format defined in OData-JSON, section 19.

      If the set of request headers of a batch request are valid the service MUST return a 200 OK HTTP response code to indicate that the batch request was accepted for processing, even if the processing is yet to be completed. The individual requests within the body of the batch request may be processed as soon as they are received, this enables clients to stream batch requests, and batch implementations to stream the results.

      If the service receives a batch request with an invalid set of headers it MUST return a 4xx response code and perform no further processing of the batch request.

      @@ -3516,12 +3516,12 @@

      section 6 and all subsections)
    • MUST successfully parse the request according to OData-ABNF for any supported system query options and follow the specification or fail the request
      • -
    • MUST expose only data types defined in OData-CSDLXML
      • +
    • MUST expose only data types defined in OData-CSDLXML
    • MUST NOT require clients to understand any metadata or instance annotations (section 6.4), custom headers (section 6.5), or custom content (section 6.2) in the payload in order to correctly consume the service
    • MUST NOT violate any OData update semantics (section 11.4 and all subsections)
    • MUST NOT violate any other OData-defined semantics
    • SHOULD support $expand (section 11.2.5.2)
      • -
    • SHOULD publish metadata at $metadata according to OData-CSDLXML and MAY publish metadata according to OData-CSDLJSON (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to OData-CSDLXML and MAY publish metadata according to OData-CSDLJSON (section 11.1.2)
    • MUST support prefixed variants of supported headers and preference values
    • MUST support enumeration and duration literals in URLs with the type prefix
      • @@ -3532,7 +3532,7 @@

      -
    • MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to OData-JSON
      • +
    • MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to OData-JSON, section 4.6.9
    • MUST support POST of new entities to insertable entity sets (section 11.4.1.5)
    • MUST support POST of new related entities to updatable navigation properties (section 11.4.2)
    • MUST support POST to $ref to add an existing entity to an updatable related collection (section 11.4.6.1)
      • @@ -3558,7 +3558,7 @@

      OData 4.0 Minimal Conformance Level
    • MUST successfully parse the request according to OData-ABNF and follow the specification or fail the request
    • MUST support $select (section 11.2.5.1)
      • -
    • MUST support casting to a derived type according to OData-URL if derived types are present in the model
      • +
    • MUST support casting to a derived type according to OData-URL, section 4.11 if derived types are present in the model
    • MUST support $top (section 11.2.6.3)
    • MUST support /$value on media entities (section 11.1.2) and individual properties (section 11.2.4.2)
    • MUST support $filter (section 11.2.6.1) @@ -3569,7 +3569,7 @@

      section 11.2.6.1.2) and MUST fail the request for any unsupported canonical functions

    • SHOULD support $filter on expanded entities (section 11.2.5.2.1)
      • -
    • SHOULD publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
    • SHOULD support the OData-JSON format
    • SHOULD consider supporting basic authentication as defined in RFC7617 over HTTPS for the highest level of interoperability with generic clients
    • SHOULD support the $search system query option (section 11.2.6.6)
      • @@ -3587,7 +3587,7 @@

    • MUST conform to at least the OData 4.0 Intermediate Conformance Level
      • -
    • MUST publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
      • +
    • MUST publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
    • MUST support the OData-JSON format
    • MUST support the /$count segment on navigation and collection properties (section 11.2.10)
    • MUST support the lambda operators any and all on navigation- and and collection-valued properties (OData-URL, section 5.1.1.13)
      • @@ -3607,11 +3607,11 @@

      section 11.2.6.6) -
    • MUST support batch requests according to the multipart format (section 11.7 and all subsections) and MAY support batch requests according to the JSON Batch format defined in OData-JSON
      • -
    • MUST support the resource path conventions defined in OData-URL
      • +
    • MUST support batch requests according to the multipart format (section 11.7 and all subsections) and MAY support batch requests according to the JSON Batch format defined in OData-JSON, section 19
      • +
    • MUST support the resource path conventions defined in OData-URL, section 4
    • SHOULD support asynchronous requests (section 11.6)
    • SHOULD support Delta change tracking (section 11.3)
      • -
    • SHOULD support cross-join queries defined in OData-URL
      • +
    • SHOULD support cross-join queries defined in OData-URL, section 4.15
    • MAY support the $compute system query option (section 11.2.5.3)

      • @@ -3648,12 +3648,12 @@

      -
    • MUST also support canonical URL conventions (described in OData-URL) or include URLs in payload
      • +
    • MUST also support canonical URL conventions (described in OData-URL, section 4.3.1) or include URLs in payload
    • MAY support the count of a filtered collection in a common expression
    • MAY support equal and non-equal structural comparison
      • -
    • SHOULD publish metadata at $metadata according to both OData-CSDLXML and OData-CSDLJSON (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to both OData-CSDLXML and OData-CSDLJSON (section 11.1.2)
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
    • SHOULD return the Core.ODataVersions annotation
    • SHOULD report capabilities through the Capabilities vocabulary
      • @@ -3712,7 +3712,7 @@

      OData-CSDLJSON (section 11.1.2) -
    • MUST support batch requests according both to the multipart format (section 11.7 and all subsections) and the JSON Batch format defined in OData-JSON
      • +
    • MUST support batch requests according both to the multipart format (section 11.7 and all subsections) and the JSON Batch format defined in OData-JSON, section 19
    • SHOULD support filtering a collection using a /$filter path segment
    • SHOULD support nested parameter alias assignments in $select and $expand
    • MAY support case-insensitive comparison of identifiers in URLs and request payloads if no exact match is found, using the same lookup sequence as for default namespaces with a case-insensitive comparison
      • @@ -3727,7 +3727,7 @@

    • MUST specify the OData-MaxVersion header in requests (section 8.2.7)
    • MUST specify OData-Version (section 8.1.5) and Content-Type (section 8.1.1) in any request with a payload
      • -
    • MUST be a conforming consumer of OData as defined in OData-JSON
      • +
    • MUST be a conforming consumer of OData as defined in OData-JSON, section 23
    • MUST follow redirects (section 9.1.5)
    • MUST correctly handle next links (section 11.2.6.7)
    • MUST support instances returning properties and navigation properties not specified in metadata (section 11.2)
      • @@ -3739,8 +3739,8 @@

      MAY request entity references in place of entities previously returned in the response (section 11.2.8)
    • MAY support deleted entities, link entities, deleted link entities in a delta response (section 11.3)
    • MAY support asynchronous responses (section 11.6)
      • -
    • MAY support metadata=minimal in a JSON response (see OData-JSON)
      • -
    • MAY support streaming in a JSON response (see OData-JSON)
      • +
    • MAY support metadata=minimal in a JSON response (see OData-JSON, section 3.1.1)
      • +
    • MAY support streaming in a JSON response (see OData-JSON, section 4.5)

      • In addition, interoperable OData 4.01 clients

        @@ -3768,9 +3768,10 @@
        OData-ABNF
        OData-Aggregation

        OData Extension for Data Aggregation Version 4.02.
        See link in “Related work” section on cover page.

        -
        OData-CSDL
        +
        OData-CSDLJSON

        OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.
        See link in “Related work” section on cover page.

        +
        OData-CSDLXML

        OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.
        See link in “Related work” section on cover page.

        OData-JSON
        diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 049d318e4..88e7ac8d8 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -344,7 +344,7 @@ service as well as a set of reserved URL query options. The [OData-CSDLJSON](#ODataCSDL) specification defines a JSON representation of the entity data model exposed by an OData service. -The [OData-CSDLXML](#ODataCSDL) specification defines an XML +The [OData-CSDLXML](#ODataCSDLXML) specification defines an XML representation of the entity data model exposed by an OData service. The [OData-JSON](#ODataJSON) document specifies the JSON format of the @@ -526,7 +526,7 @@ set. An OData *resource* is anything in the model that can be addressed (an entity set, entity, property, or operation). -Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) for +Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML) for more information on the OData entity data model. ## 3.1 Annotations @@ -585,7 +585,7 @@ of the specification since there is currently no lossless representation of an IRI in the [`EntityId`](#HeaderODataEntityId) header. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) as its entity-id, but clients cannot assume +as defined in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL) as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the [`Core.DereferenceableIDs`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs) term is applied to the entity container, nor can the client assume any @@ -612,7 +612,7 @@ The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) for both the read URL and the edit URL of an +as defined in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL) for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention @@ -923,7 +923,7 @@ ignored. Custom format parameters MUST NOT start with `odata` and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload. -See [OData-JSON](#ODataJSON) for format-specific details about format +See [OData-JSON, section 4.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#HeaderContentType) for format-specific details about format parameters within the `Content-Type` header. ### 8.1.2 Header `Content-Encoding` @@ -1734,7 +1734,7 @@ HTTP/2). The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport -in a header, see e.g. [OData-JSON](#ODataJSON). +in a header, see e.g. [OData-JSON, section 21.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InStreamError). ### 8.3.6 Header `Preference-Applied` @@ -2546,7 +2546,7 @@ Context URL template: {context-url}#Collection(Edm.EntityType) Responses to requests to the virtual collection `$all` (see -[OData-URL](#ODataURL)) use the built-in abstract entity type. Each +[OData-URL, section 4.16](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingAllEntitiesinaService)) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton. @@ -2557,7 +2557,7 @@ Context URL template: {context-url}#Collection(Edm.ComplexType) Responses to requests to the virtual collections `$crossjoin(…)` (see -[OData-URL](#ODataURL)) use the built-in abstract complex type. Single +[OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets)) use the built-in abstract complex type. Single instances in these responses do not have a context URL. @@ -2629,7 +2629,7 @@ metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is `application/json`. -[OData-CSDLXML](#ODataCSDL) describes an XML representation for OData +[OData-CSDLXML](#ODataCSDLXML) describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is `application/xml`. @@ -2713,9 +2713,9 @@ URL that identifies the entity, e.g. its read URL. The read URL can be obtained from a response payload containing that instance, for example as a `readLink` or `editLink` in an -[OData-JSON](#ODataJSON) payload. In addition, services +[OData-JSON, section 4.6.9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink) payload. In addition, services MAY support conventions for constructing a read URL using the entity's -key value(s), as described in [OData-URL](#ODataURL). +key value(s), as described in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The set of structural or navigation properties to return may be specified through [`$select`](#SystemQueryOptionselect) or @@ -2775,7 +2775,7 @@ the property name appended. For complex typed properties, the path can be further extended with the name of an individual property of the complex type. -See [OData-URL](#ODataURL) for details. +See [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty) for details. If the property is single-valued and has the `null` value, the service responds with [`204 No Content`](#ResponseCode204NoContent). @@ -2805,7 +2805,7 @@ system query option. #### 11.2.4.2 Requesting a Raw Value using `$value` To retrieve the raw value of a primitive property or operation result, the client sends -a `GET` request to the raw value URL. See the [OData-URL](#ODataURL) document for details. +a `GET` request to the raw value URL. See [OData-URL, section 4.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaRawValue) for details. The `Content-Type` of the response is determined using the `Accept` header and the [`$format`](#SystemQueryOptionformat) system query @@ -3004,7 +3004,7 @@ GET http://host/service.svc/Customers?$expand=Photo The set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see -[OData-URL](#ODataURL). +[OData-URL, section 5.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand). Allowed system query options are [`$compute`](#SystemQueryOptioncompute), @@ -3794,7 +3794,7 @@ GET http://host/service/Orders?$format=application/json;metadata=full is equivalent to a request with an `Accept` header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in -[OData-JSON](#ODataJSON). +[OData-JSON, section 3.1.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull). ::: example Example 75: the request @@ -3806,7 +3806,7 @@ GET http://host/service/Orders?$format=json is equivalent to a request with the `Accept` header set to `application/json`; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in -[OData-JSON](#ODataJSON). +[OData-JSON, section 3.1.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal). In [metadata document requests](#MetadataDocumentRequest), the values `application/xml` and `application/json`, along with their subtypes and @@ -4737,7 +4737,7 @@ deleted, the dependent entity is also deleted. Relationships between entities are represented by navigation properties as described in [Data Model](#DataModel). URL conventions for navigation -properties are described in [OData-URL](#ODataURL). +properties are described in [OData-URL, section 4.3.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLsforRelatedEntitieswithReferentialConstraints). #### 11.4.6.1 Add a Reference to a Collection-Valued Navigation Property @@ -4763,7 +4763,7 @@ collection of related references, with the reference to be removed identified by the [`$id`](#ResolvinganEntityId) query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as -described in [OData-URL](#ODataURL). +described in [OData-URL, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingReferencesbetweenEntities). For single-valued navigation properties, the [`$id`](#ResolvinganEntityId) query option MUST NOT be specified. @@ -4787,7 +4787,7 @@ On successful completion, the response MUST be Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see -[OData-JSON](#ODataJSON) for details. +[OData-JSON, section 15.4](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#RelatedEntities) for details. If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with @@ -4980,7 +4980,7 @@ Attempting to request a stream property whose value is null results in Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows -properties to be individually modified. See [OData-URL](#ODataURL) for +properties to be individually modified. See [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty) for details on addressing individual properties. #### 11.4.9.1 Update a Primitive Property @@ -5265,7 +5265,8 @@ describes an update to each member of the collection, not an update to the collection itself. The resource path of the collection MAY contain type-cast or filter -segments to subset the collection, see [OData-URL](#ODataURL). +segments to subset the collection, see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes) and +[OData-URL, section 4.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaSubsetofaCollection). For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is @@ -5362,7 +5363,7 @@ Custom operations ([Actions](#Actions) and [Functions](#Functions)) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See `Action`, `ActionImport`, `Function`, and `FunctionImport` in -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML). ### 11.5.1 Binding an Operation to a Resource @@ -5481,7 +5482,7 @@ bound to the entity An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in -[OData-URL](#ODataURL). +[OData-URL, section 4.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingOperations). Services can advertise that a function or action is not available for a particular instance by setting its value to null. @@ -5608,7 +5609,7 @@ result requires a `4xx` response, and continues otherwise. Function imports preceded by the `$root` literal MAY be used in the [`$filter`](#SystemQueryOptionfilter) or [`$orderby`](#SystemQueryOptionorderby) system query options, see -[OData-URL](#ODataURL). +[OData-URL, section 5.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionfilter) and [OData-URL, section 5.1.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionorderby). ##### 11.5.4.1.1 Inline Parameter Syntax @@ -5696,7 +5697,7 @@ If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the -hierarchy, see [OData-URL](#ODataURL). +hierarchy, see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes). Non-binding parameters MAY be marked as optional by annotating them with the term @@ -5832,7 +5833,7 @@ If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, -see [OData-URL](#ODataURL). +see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes). ## 11.6 Asynchronous Requests @@ -5927,7 +5928,7 @@ a batch request. A batch request is represented using either the [multipart batch format](#MultipartBatchFormat) defined in this document or the JSON -batch format defined in [OData-JSON](#ODataJSON). +batch format defined in [OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses). If the set of request headers of a batch request are valid the service MUST return a [`200 OK`](#ResponseCode200OK) HTTP response code to @@ -6686,7 +6687,7 @@ request 7. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) for any supported system query options and follow the specification or fail the request -8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL) +8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDLXML) 9. MUST NOT require clients to understand any metadata or instance annotations ([section 6.4](#VocabularyExtensibility)), custom headers ([section 6.5](#HeaderFieldExtensibility)), or custom content ([section 6.2](#PayloadExtensibility)) in the payload in order to correctly consume the @@ -6696,7 +6697,7 @@ service 11. MUST NOT violate any other OData-defined semantics 12. SHOULD support `$expand` ([section 11.2.5.2](#SystemQueryOptionexpand)) 13. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) and MAY publish metadata according to +[OData-CSDLXML](#ODataCSDLXML) and MAY publish metadata according to [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 14. MUST support prefixed variants of supported headers and preference values @@ -6714,7 +6715,7 @@ final response to an asynchronous request To be considered an *Updatable OData Service*, the service additionally: 18. MUST include edit links (explicitly or implicitly) for all -updatable or deletable resources according to [OData-JSON](#ODataJSON) +updatable or deletable resources according to [OData-JSON, section 4.6.9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink) 19. MUST support `POST` of new entities to insertable entity sets ([section 11.4.1.5](#ReturningResultsfromDataModificationRequests)) 20. MUST support `POST` of new related entities to updatable navigation @@ -6755,7 +6756,7 @@ Level](#OData40MinimalConformanceLevel) follow the specification or fail the request 3. MUST support `$select` ([section 11.2.5.1](#SystemQueryOptionselect)) 4. MUST support casting to a derived type according to -[OData-URL](#ODataURL) if derived types are present in the model +[OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes) if derived types are present in the model 5. MUST support `$top` ([section 11.2.6.3](#SystemQueryOptiontop)) 6. MUST support `/$value` on media entities ([section 11.1.2](#MetadataDocumentRequest)) and individual properties ([section 11.2.4.2](#RequestingaRawValueusingvalue)) 7. MUST support `$filter` ([section 11.2.6.1](#SystemQueryOptionfilter)) @@ -6769,7 +6770,7 @@ operations MUST fail the request for any unsupported canonical functions 5. SHOULD support `$filter` on expanded entities ([section 11.2.5.2.1](#ExpandOptions)) 8. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) ([section 11.1.2](#MetadataDocumentRequest)) 9. SHOULD support the [OData-JSON](#ODataJSON) format 10. SHOULD consider supporting basic authentication as defined in [RFC7617](#rfc7617) over HTTPS for the highest level of interoperability @@ -6792,7 +6793,7 @@ In order to conform to the OData Advanced Conformance Level, a service: 1. MUST conform to at least the [OData 4.0 Intermediate Conformance Level](#OData40IntermediateConformanceLevel) 2. MUST publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) ([section 11.1.2](#MetadataDocumentRequest)) 3. MUST support the [OData-JSON](#ODataJSON) format 4. MUST support the `/$count` segment on navigation and collection properties ([section 11.2.10](#RequestingtheNumberofItemsinaCollection)) @@ -6817,13 +6818,13 @@ properties 10. MUST support the `$search` system query option ([section 11.2.6.6](#SystemQueryOptionsearch)) 11. MUST support batch requests according to the multipart format ([section 11.7](#BatchRequests) and all subsections) and MAY support batch requests -according to the JSON Batch format defined in [OData-JSON](#ODataJSON) +according to the JSON Batch format defined in [OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses) 12. MUST support the resource path conventions defined in -[OData-URL](#ODataURL) +[OData-URL, section 4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ResourcePath) 13. SHOULD support asynchronous requests ([section 11.6](#AsynchronousRequests)) 14. SHOULD support Delta change tracking ([section 11.3](#RequestingChanges)) -15. SHOULD support cross-join queries defined in [OData-URL](#ODataURL) +15. SHOULD support cross-join queries defined in [OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets) 16. MAY support the `$compute` system query option ([section 11.2.5.3](#SystemQueryOptioncompute)) ## 12.2 OData 4.01 Service Conformance Levels @@ -6884,12 +6885,12 @@ with a maximum cardinality of one 11. SHOULD support negative indexes for the substring function 12. MAY support Key-As-Segment URL convention 1. MUST also support canonical URL conventions (described in -[OData-URL](#ODataURL)) or include URLs in payload +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL)) or include URLs in payload 13. MAY support the count of a filtered collection in a common expression 14. MAY support equal and non-equal structural comparison 10. SHOULD publish metadata at `$metadata` according to both -[OData-CSDLXML](#ODataCSDL) and [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) and [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 11. SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case @@ -6971,7 +6972,7 @@ properties [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 7. MUST support batch requests according both to the multipart format ([section 11.7](#BatchRequests) and all subsections) and the JSON Batch format defined in -[OData-JSON](#ODataJSON) +[OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses) 8. SHOULD support filtering a collection using a `/$filter` path segment 9. SHOULD support nested parameter alias assignments in @@ -6994,7 +6995,7 @@ To be generally interoperable, OData clients 2. MUST specify `OData-Version` ([section 8.1.5](#HeaderODataVersion)) and `Content-Type` ([section 8.1.1](#HeaderContentType)) in any request with a payload 3. MUST be a conforming consumer of OData as defined in -[OData-JSON](#ODataJSON) +[OData-JSON, section 23](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#Conformance) 4. MUST follow redirects ([section 9.1.5](#ResponseCode3xxRedirection)) 5. MUST correctly handle next links ([section 11.2.6.7](#ServerDrivenPaging)) 6. MUST support instances returning properties and navigation @@ -7014,9 +7015,9 @@ returned in the response ([section 11.2.8](#RequestingEntityReferences)) in a delta response ([section 11.3](#RequestingChanges)) 14. MAY support asynchronous responses ([section 11.6](#AsynchronousRequests)) 15. MAY support `metadata=minimal` in a JSON response (see -[OData-JSON](#ODataJSON)) +[OData-JSON, section 3.1.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal)) 16. MAY support `streaming` in a JSON response (see -[OData-JSON](#ODataJSON)) +[OData-JSON, section 4.5](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PayloadOrderingConstraints)) In addition, interoperable OData 4.01 clients @@ -7054,10 +7055,11 @@ See link in "[Related work](#RelatedWork)" section on cover page. _OData Extension for Data Aggregation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-CSDL]{id=ODataCSDL} +###### [OData-CSDLJSON]{id=ODataCSDL} _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLXML]{id=ODataCSDLXML} _OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. diff --git a/docs/odata-temporal-ext/odata-temporal-ext.html b/docs/odata-temporal-ext/odata-temporal-ext.html index e5101e382..9891561ad 100644 --- a/docs/odata-temporal-ext/odata-temporal-ext.html +++ b/docs/odata-temporal-ext/odata-temporal-ext.html @@ -1929,7 +1929,7 @@

        Changes to a temporal object over a period of application time can affect multiple time slices. For timeline entity sets this can in principle be achieved by constructing batch requests with multiple operations on individual time slices. This puts burden on the client, and it also makes it harder for services to check whether the request represents a consistent change of the temporal data.

        Both can be avoided by providing convenience operations expressing the intent of the modification and leaving the actual time slice manipulation to the service. These operations can then also be used with snapshot entity sets that do not allow direct manipulation of time slices.

        -

        These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data OData-VocTemporal. Implementations SHOULD consider the preferences return=representation and return=minimal as specified invOData-Protocol. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects.

        +

        These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data OData-VocTemporal. Implementations SHOULD consider the preferences return=representation and return=minimal as specified in OData-Protocol, section 8.2.8.7. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects.

        All actions define a collection of entities as their binding parameter. This collection can be

        • A snapshot entity set
          • @@ -1949,7 +1949,7 @@

          OData-Protocol. +
        • Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities specified in OData-Protocol, section 11.4.3.
        • Gaps between selected time slices in the period to update are not affected.

      On success it returns the created or updated time slices.

      @@ -2215,9 +2215,9 @@

    • copying the property values of the preceding time slice (except for computed properties),
    • setting the period boundaries to close the gap, and then
      • -
    • updating the new time slice following the rules for updating entities specified in OData-Protocol.
      • +
    • updating the new time slice following the rules for updating entities specified in OData-Protocol, section 11.4.3.
      • -

      If no preceding time slice exists, the time slice is created following the rules for creating entities specified in OData-Protocol.

      +

      If no preceding time slice exists, the time slice is created following the rules for creating entities specified in OData-Protocol, section 11.4.2.

      On success it returns the created or updated time slices.

      @@ -2396,7 +2396,7 @@

      OData-Protocol. +
    • Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities specified in OData-Protocol, section 11.4.5.

      • On success it returns the deleted time slices.

      @@ -2488,7 +2488,7 @@

      B.1 Special Thanks

      -

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track.

      diff --git a/docs/odata-temporal-ext/odata-temporal-ext.md b/docs/odata-temporal-ext/odata-temporal-ext.md index 680d0dfe1..a3dc7892e 100644 --- a/docs/odata-temporal-ext/odata-temporal-ext.md +++ b/docs/odata-temporal-ext/odata-temporal-ext.md @@ -2008,7 +2008,7 @@ slices. These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data [OData-VocTemporal](#ODataVocTemporal). Implementations SHOULD consider the preferences `return=representation` -and `return=minimal` as specified inv[OData-Protocol](#ODataProtocol). +and `return=minimal` as specified in [OData-Protocol, section 8.2.8.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferencereturnrepresentationandreturnminimal). The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects. @@ -2062,7 +2062,7 @@ This works identical to the SQL statement UPDATE FOR PORTION OF: slice's period. 4. Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities - specified in [OData-Protocol](#ODataProtocol). + specified in [OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity). 5. Gaps between selected time slices in the period to update are not affected. On success it returns the created or updated time slices. @@ -2255,10 +2255,10 @@ Step 5 is (except for computed properties), 2. setting the period boundaries to close the gap, and then 3. updating the new time slice following the rules for updating - entities specified in [OData-Protocol](#ODataProtocol). + entities specified in [OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity). If no preceding time slice exists, the time slice is created following - the rules for creating entities specified in [OData-Protocol](#ODataProtocol). + the rules for creating entities specified in [OData-Protocol, section 11.4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#CreateanEntity). On success it returns the created or updated time slices. @@ -2404,7 +2404,7 @@ This works identical to the SQL statement DELETE FOR PORTION OF: slices, one with non-overlapping, and one with fully included period. 4. Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities - specified in [OData-Protocol](#ODataProtocol). + specified in [OData-Protocol, section 11.4.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DeleteanEntity). On success it returns the deleted time slices. @@ -2519,7 +2519,7 @@ _ISO/IEC 9075-2:2011 Information technology - Database languages - SQL - Part 2: ## B.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track. diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html index 12226e4d7..147e9a2b9 100644 --- a/docs/odata-url-conventions/odata-url-conventions.html +++ b/docs/odata-url-conventions/odata-url-conventions.html @@ -559,7 +559,7 @@

      2.2 URL Syntax

      3 Service Root URL

       -

      The service root URL identifies the root of an OData service. A GET request to this URL returns the format-specific service document, see OData-JSON.

      +

      The service root URL identifies the root of an OData service. A GET request to this URL returns the format-specific service document, see OData-JSON, section 5.

      The service root URL MUST terminate in a forward slash.

      The service document enables simple hypermedia-driven clients to enumerate and explore the resources published by the OData service.

      @@ -575,7 +575,7 @@

      4 Resource Pa

      4.1 Addressing the Model for a Service

       -

      OData services expose their entity model according to OData-CSDLJSON or OData-CSDLXML at the metadata URL, formed by appending $metadata to the service root URL.

      +

      OData services expose their entity model according to OData-CSDL at the metadata URL, formed by appending $metadata to the service root URL.

      Example 5: Metadata document URL

      http://host/service/$metadata
      @@ -721,7 +721,7 @@

      4.3.1 Canon

      4.3.2 Canonical URL for Contained Entities

       -

      For contained entities (i.e. related via a containment navigation property, see OData-CSDLJSON or OData-CSDLXML) the canonical URL is the canonical URL of the containing entity followed by:

      +

      For contained entities (i.e. related via a containment navigation property, see OData-CSDLJSON) the canonical URL is the canonical URL of the containing entity followed by:

      • A type-cast segment if the navigation property is defined on a type derived from the entity type declared for the entity set,
      • A path segment for the containment navigation property, and
        • @@ -752,7 +752,7 @@

        OData-Protocol document.

        +

        The semantics of $entity are covered in OData-Protocol, section 10.

      4.3.5 Alternate Keys

      @@ -797,7 +797,7 @@

    • matches a defined OData segment (starting with “$”), treat it as such
    • matches a qualified bound function, bound action, or type name, treat it as such
      • -
    • matches an unqualified bound function, bound action, or type name defined in a default namespace (see OData-Protocol) treat it as such
      • +
    • matches an unqualified bound function, bound action, or type name defined in a default namespace (see OData-Protocol, section 4.4) treat it as such
    • treat as a key value

      • For maximum interoperability, services that support the key-as-segment convention SHOULD also support the canonical parentheses-style convention for addressing an entity within a collection, otherwise they MUST specify the URL for each returned entity in a response, as specified by the particular format.

      @@ -813,7 +813,7 @@

      OData-Protocol.

      +

      Resource paths addressing a single related entity reference can be used in DELETE requests to unrelate two entities. In OData 4.01, this includes resource paths that identify an individual entity reference within a related collection by key. In OData 4.0, resource paths addressing a collection of references MUST be followed by the system query option $id in order to identify a single entity reference within the collection to be removed. The entity-id specified by $id may be expressed absolute or relative to the request URL. For details see OData-Protocol, section 4.1.

      Example 29: three ways of unrelating Categories(1) and Products(0); the second option is supported only in OData 4.01

      DELETE http://host/service/Categories(1)/Products/$ref?$id=../../Products(0)
      @@ -824,8 +824,8 @@

      4.5 Addressing Operations

       -

      The semantic rules for addressing and invoking actions and functions are defined in the OData-Protocol document.

      -

      Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.

      +

      The semantic rules for addressing and invoking actions and functions are defined in OData-Protocol, section 11.5.

      +

      Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4.

      4.5.1 Addressing Actions

       @@ -845,7 +845,7 @@

      OData-Protocol. +
    • The aliasAndValue syntax rule defines the grammar for providing function parameter values using Parameter Alias Syntax, see OData-Protocol, section 11.2.6.1.3.

      • Note: there is no literal representation for Edm.Stream values in URLs, so it is not possible to pass Edm.Stream values to parameters of function imports or to non-binding parameters of bound functions used in the resource path. Function expressions within query options can use path expressions of type Edm.Stream as values of non-binding function parameters. The aliases can contain common expressions. In the case of a bound function these MAY contain path expressions, which the service evaluates on the binding parameter value.

      @@ -927,7 +927,7 @@

      Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.

      +

      Services MAY additionally support the use of the unqualified name of a derived type in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4.

      Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a derived type. In this case, the set and values of properties of the addressed type may be different than the properties of the source type. The set of such possible target types outside of the type hierarchy SHOULD be called out using the Core.MayImplement annotation term, defined in OData-VocCore.

      Example 37: entity set restricted to VipCustomer instances

      @@ -1128,7 +1128,7 @@

      OData-Protocol document.

      +

      The semantics of all system query options are defined in OData-Protocol, section 11.2.1.

      The grammar and syntax rules for system query options are defined in OData-ABNF.

      Dynamic properties can be used in the same way as declared properties. If they are not defined on an instance, they evaluate to null.

      @@ -2060,7 +2060,7 @@

      Core.Messages annotation

      http://host/service/Employees?$filter=@Core.Messages/any(m:m/severity eq 'error')

      -

      Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.

      +

      Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.

      5.1.1.17 Operator Precedence

      @@ -2374,7 +2374,7 @@

      OData-Protocol) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via $select. The Preference-Applied response header only reflects the set of annotations included due to the include-annotations preference and not those only included due to $select.

      +

      Annotations requested in $select MUST be included in the response; $select overrules the include-annotations preference (see OData-Protocol, section 8.2.8.4) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via $select. The Preference-Applied response header only reflects the set of annotations included due to the include-annotations preference and not those only included due to $select.

      If any select item (including a star) is specified, actions and functions SHOULD be omitted unless explicitly requested.

      If an action or function is requested as a select item, either explicitly by using its qualified name, or implicitly by requesting all operations in a schema, then the service includes information about how to invoke that operation for each entity identified by the last path segment in the request URL for which the operation can be bound.

      If an action or function is requested in a select item using its qualified name and that operation cannot be bound to the entities requested, the service MUST ignore the select item.

      @@ -2388,20 +2388,20 @@

      5.1.5 System Query Option $orderby

      The $orderby system query option allows clients to request resources in a particular order.

      -

      The semantics of $orderby are covered in the OData-Protocol document.

      +

      The semantics of $orderby are covered in OData-Protocol, section 11.2.6.2.

      The OData-ABNF orderby syntax rule defines the formal grammar of the $orderby query option.

      5.1.6 System Query Options $top and $skip

      The $top system query option requests the number of items in the queried collection to be included in the result. The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining $top and $skip.

      -

      The semantics of $top and $skip are covered in the OData-Protocol document. The OData-ABNF top and skip syntax rules define the formal grammar of the $top and $skip query options respectively.

      +

      The semantics of $top and $skip are covered in OData-Protocol, section 11.2.6.3 and OData-Protocol, section 11.2.6.4. The OData-ABNF top and skip syntax rules define the formal grammar of the $top and $skip query options respectively.

      5.1.7 System Query Option $count

      The $count system query option allows clients to request a count of the matching resources included with the resources in the response. The $count query option has a Boolean value of true or false.

      -

      The semantics of $count is covered in the OData-Protocol document.

      +

      The semantics of $count is covered in OData-Protocol, section 11.2.6.5.

      @@ -2435,7 +2435,7 @@

      5.1.9 System Query Option $format

      The $format system query option allows clients to request a response in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present $format takes precedence over standard content-type negotiation.

      -

      The semantics of $format is covered in the OData-Protocol document.

      +

      The semantics of $format is covered in OData-Protocol, section 11.2.11.

      The OData-ABNF format syntax rule defines the formal grammar of the $format query option.

      @@ -2464,7 +2464,7 @@

      5.1.12 System Query Option $schemaversion

       -

      The $schemaversion system query option allows clients to specify the version of the schema against which the request is made. The semantics of $schemaversion is covered in the OData-Protocol document.

      +

      The $schemaversion system query option allows clients to specify the version of the schema against which the request is made. The semantics of $schemaversion is covered in OData-Protocol, section 11.2.12.

      The OData-ABNF schemaversion syntax rule defines the formal grammar of the $schemaversion query option

      @@ -2483,7 +2483,7 @@

      Parameter aliases can be used in place of literal values in entity keys, function parameters, or within a $filter or $orderby expression.

      Parameter aliases MUST start with an @ character, see rule parameterAlias in OData-ABNF.

      -

      The semantics of parameter aliases are covered in OData-Protocol. The OData-ABNF rule aliasAndValue defines the formal grammar for passing parameter alias values as query options.

      +

      The semantics of parameter aliases are covered in OData-Protocol, section 11.2.6.1.3. The OData-ABNF rule aliasAndValue defines the formal grammar for passing parameter alias values as query options.

      Example 144:

      http://host/service/Movies?$filter=contains(@word,Title)&@word='Black'
      @@ -2503,7 +2503,7 @@

      6 Conformance

       -

      The conformance requirements for OData clients and services are described in OData-Protocol.

      +

      The conformance requirements for OData clients and services are described in OData-Protocol, section 12.

      diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md index 7bb811cce..3ed0a7932 100644 --- a/docs/odata-url-conventions/odata-url-conventions.md +++ b/docs/odata-url-conventions/odata-url-conventions.md @@ -448,7 +448,7 @@ path segment, nor is `Tablet')`. The service root URL identifies the root of an OData service. A `GET` request to this URL returns the format-specific service document, see -[OData-JSON](#ODataJSON). +[OData-JSON, section 5](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ServiceDocument). The service root URL MUST terminate in a forward slash. @@ -490,7 +490,7 @@ An OData service MAY respond with `301 Moved Permanently` or ## 4.1 Addressing the Model for a Service OData services expose their entity model according to -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) at the +[OData-CSDL](#ODataCSDL) at the metadata URL, formed by appending `$metadata` to the [service root URL](#ServiceRootURL). @@ -727,8 +727,7 @@ http://host/service/Products(1) ### 4.3.2 Canonical URL for Contained Entities For contained entities (i.e. related via a containment navigation -property, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL)) the canonical URL is the canonical URL of +property, see [OData-CSDLJSON](#ODataCSDL)) the canonical URL is the canonical URL of the containing entity followed by: - A [type-cast segment](#AddressingDerivedTypes) if the navigation property is defined on a type derived from the entity type declared for @@ -790,8 +789,7 @@ http://host/service/$entity?$id=Products(0) ``` ::: -The semantics of `$entity` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$entity` are covered in [OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL). ### 4.3.5 Alternate Keys @@ -909,7 +907,7 @@ such 2. matches a qualified bound function, bound action, or type name, treat it as such 3. matches an unqualified bound function, bound action, or type name -defined in a default namespace (see [OData-Protocol](#ODataProtocol)) treat it +defined in a default namespace (see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces)) treat it as such 4. treat as a key value @@ -951,7 +949,7 @@ addressing a collection of references MUST be followed by the system query option `$id` in order to identify a single entity reference within the collection to be removed. The entity-id specified by `$id` may be expressed absolute or relative to the request URL. For details see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences). ::: example Example 29: three ways of unrelating `Categories(1)` and @@ -972,14 +970,14 @@ DELETE http://host/service/Products(0)/Category/$ref ## 4.5 Addressing Operations The semantic rules for addressing and invoking actions and functions are -defined in the [OData-Protocol](#ODataProtocol) document. +defined in [OData-Protocol, section 11.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Operations). Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). ### 4.5.1 Addressing Actions @@ -1026,7 +1024,7 @@ syntax rule define the grammar for invoking functions, for example to help filte and order resources identified by the `resourcePath` of the URL. - The `aliasAndValue` syntax rule defines the grammar for providing function parameter values using Parameter -Alias Syntax, see [OData-Protocol](#ODataProtocol). +Alias Syntax, see [OData-Protocol, section 11.2.6.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases). Note: there is no literal representation for `Edm.Stream` values in URLs, so it is not possible to pass `Edm.Stream` values to parameters of function imports or @@ -1203,7 +1201,7 @@ derived type in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a @@ -1631,8 +1629,8 @@ The same system query option, irrespective of casing or whether or not it is prefixed with a `$`, MUST NOT be specified more than once for any resource. -The semantics of all system query options are defined in the -[OData-Protocol](#ODataProtocol) document. +The semantics of all system query options are defined in +[OData-Protocol, section 11.2.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptions). The grammar and syntax rules for system query options are defined in [OData-ABNF](#ODataABNF). @@ -3483,7 +3481,7 @@ Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) annotation term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a [parameter alias](#ParameterAliases), then any occurrence of the parameter alias @@ -3910,7 +3908,7 @@ omitted from the response. Annotations requested in `$select` MUST be included in the response; `$select` overrules the `include-annotations` preference (see -[OData-Protocol](#ODataProtocol)) for the explicitly requested annotations. +[OData-Protocol, section 8.2.8.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferenceincludeannotationsodataincludeannotations)) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via `$select`. The `Preference-Applied` response header only reflects the set of annotations included due to the @@ -3949,8 +3947,7 @@ identified by each select item. The `$orderby` system query option allows clients to request resources in a particular order. -The semantics of `$orderby` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$orderby` are covered in [OData-Protocol, section 11.2.6.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionorderby). The [OData-ABNF](#ODataABNF) `orderby` syntax rule defines the formal grammar of the `$orderby` query option. @@ -3963,8 +3960,9 @@ option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining `$top` and `$skip`. -The semantics of `$top` and `$skip` are covered in the -[OData-Protocol](#ODataProtocol) document. The [OData-ABNF](#ODataABNF) `top` +The semantics of `$top` and `$skip` are covered in +[OData-Protocol, section 11.2.6.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptiontop) and [OData-Protocol, section 11.2.6.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionskip). +The [OData-ABNF](#ODataABNF) `top` and `skip` syntax rules define the formal grammar of the `$top` and `$skip` query options respectively. @@ -3974,8 +3972,7 @@ The `$count` system query option allows clients to request a count of the matching resources included with the resources in the response. The `$count` query option has a Boolean value of `true` or `false`. -The semantics of `$count` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$count` is covered in [OData-Protocol, section 11.2.6.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptioncount). ### 5.1.8 System Query Option `$search` @@ -4057,8 +4054,7 @@ in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present `$format` takes precedence over standard content-type negotiation. -The semantics of `$format` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$format` is covered in [OData-Protocol, section 11.2.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionformat). The [OData-ABNF](#ODataABNF) `format` syntax rule defines the formal grammar of the `$format` query option. @@ -4121,7 +4117,7 @@ grammar of the `$index` query option. The `$schemaversion` system query option allows clients to specify the version of the schema against which the request is made. The semantics -of `$schemaversion` is covered in the [OData-Protocol](#ODataProtocol) document. +of `$schemaversion` is covered in [OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion). The [OData-ABNF](#ODataABNF) `schemaversion` syntax rule defines the formal grammar of the `$schemaversion` query option @@ -4153,7 +4149,7 @@ Parameter aliases MUST start with an `@` character, see rule `parameterAlias` in [OData-ABNF](#ODataABNF). The semantics of parameter aliases are covered in -[OData-Protocol](#ODataProtocol). The [OData-ABNF](#ODataABNF) rule +[OData-Protocol, section 11.2.6.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases). The [OData-ABNF](#ODataABNF) rule `aliasAndValue` defines the formal grammar for passing parameter alias values as query options. @@ -4186,7 +4182,7 @@ http://host/service/Products/Model.WithIngredients(Ingredients=@i) # 6 Conformance The conformance requirements for OData clients and services are -described in [OData-Protocol](#ODataProtocol). +described in [OData-Protocol, section 12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance). ------- diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md index 3aa65bc79..16330f221 100644 --- a/odata-csdl/1 Introduction.md +++ b/odata-csdl/1 Introduction.md @@ -560,7 +560,7 @@ length. The value of `$MaxLength` is a positive integer. -Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic +Note: [#OData-CSDLXML#MaxLength] defines a symbolic value `max` that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the diff --git a/odata-csdl/14 Vocabulary and Annotation.md b/odata-csdl/14 Vocabulary and Annotation.md index 73801ec63..6268d2b76 100644 --- a/odata-csdl/14 Vocabulary and Annotation.md +++ b/odata-csdl/14 Vocabulary and Annotation.md @@ -18,7 +18,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [#OData-JSON#InstanceAnnotations]. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -195,10 +195,10 @@ of the collection and specifies whether the collection MAY contain The value of `$DefaultValue` is the type-specific JSON representation of the default value of the term, see -[OData-JSON](#ODataJSON). +[#OData-JSON#PrimitiveValue]. Note: the `$DefaultValue` member is purely for documentation and -isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in +isomorphy to [#OData-CSDLXML#DefaultValue]. Annotations in CSDL JSON documents MUST always specify an explicit value. ::: @@ -1223,7 +1223,7 @@ Example ##ex: ### ##subsubsec Geo Values ::: {.varjson .rep} -Values are represented as GeoJSON, see [OData-JSON](#ODataJSON). +Values are represented as GeoJSON, see [RFC7946](#rfc7946). ::: ::: {.varjson .example} @@ -1252,7 +1252,7 @@ Example ##ex: ### ##subsubsec Stream Values ::: {.varjson .rep} -Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by +Constant values of type `Edm.Stream` are represented according to [#OData-JSON#StreamProperty] and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. ::: @@ -1330,7 +1330,7 @@ than the `Edm.*Path` types. #### ##subsubsubsec Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [#OData-URL#PathExpressions]. A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -1466,7 +1466,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[#OData-URL#CanonicalURL]. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -1981,7 +1981,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [#OData-URL#LogicalOperators]. The other comparison operators require two operand expressions that evaluate to comparable values. @@ -2208,7 +2208,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[#OData-URL#ArithmeticOperators]. Operator|Description --------|----------- @@ -2412,10 +2412,10 @@ specification and its future versions. #### ##subsubsubsec Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [#OData-URL#CanonicalFunctions] can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [#OData-URL#CanonicalFunctions]. For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -2656,7 +2656,7 @@ Example ##ex: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[#OData-URL#cast]. ::: {.varjson .rep} ### ##subisec `$Cast` @@ -3167,7 +3167,7 @@ property value expression. The member name is the property name, and the member value is the property value expression. The type of a record expression is represented as the `type` control -information, see [OData-JSON](#ODataJSON). +information, see [#OData-JSON#ControlInformationtypeodatatype]. It MAY contain [annotations](#Annotation) for itself and its members. Annotations for record members are prefixed with the member name. diff --git a/odata-csdl/4 CSDL Document.md b/odata-csdl/4 CSDL Document.md index 8e5727994..f7dd24b31 100644 --- a/odata-csdl/4 CSDL Document.md +++ b/odata-csdl/4 CSDL Document.md @@ -104,8 +104,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`]($$$OData-VocCore$$$#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[#OData-Protocol#SystemQueryOptionschemaversion], SHOULD be used when retrieving the referenced schema document. ::: {.varjson .rep} diff --git a/odata-csdl/5 Schema.md b/odata-csdl/5 Schema.md index 274d34e5e..f9e316229 100644 --- a/odata-csdl/5 Schema.md +++ b/odata-csdl/5 Schema.md @@ -386,7 +386,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#DataModel]. ::: {.varjson .rep} ### ##subisec `$OpenType` @@ -413,7 +413,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#RequestingtheMediaStreamofaMediaEntityusingvalue]. An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -480,7 +480,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[#OData-Protocol#EntityIdsandEntityReferences]) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable diff --git a/odata-csdl/7 Structural Property.md b/odata-csdl/7 Structural Property.md index 3ff11b515..e3228b0a7 100644 --- a/odata-csdl/7 Structural Property.md +++ b/odata-csdl/7 Structural Property.md @@ -217,7 +217,7 @@ If no value is specified, the client SHOULD NOT assume a default value. The value of `$DefaultValue` is the type-specific JSON representation of the default value of the property, see -[OData-JSON](#ODataJSON). For properties of type +[#OData-JSON#PrimitiveValue]. For properties of type `Edm.Decimal` and `Edm.Int64` the representation depends on the media type parameter [`IEEE754Compatible`](#ControllingtheRepresentationofNumbers). @@ -494,7 +494,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[#OData-URL#CanonicalURLforContainedEntities]. Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. diff --git a/odata-csdl/9 Complex Type.md b/odata-csdl/9 Complex Type.md index 6f553fc10..c8769313e 100644 --- a/odata-csdl/9 Complex Type.md +++ b/odata-csdl/9 Complex Type.md @@ -178,7 +178,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[#OData-Protocol#DataModel]. ::: {.varjson .rep} ### ##subisec `$OpenType` diff --git a/odata-csdl/Appendix.md b/odata-csdl/Appendix.md index 29ae9cede..9ce4175b5 100644 --- a/odata-csdl/Appendix.md +++ b/odata-csdl/Appendix.md @@ -92,6 +92,10 @@ https://www.rfc-editor.org/info/rfc6570. ###### [RFC7493]{id=rfc7493} _The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_. https://www.rfc-editor.org/info/rfc7493. + +###### [RFC7946]{id=rfc7946} +_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_. +https://www.rfc-editor.org/info/rfc7946. : ###### [RFC8174]{id=rfc8174} @@ -164,7 +168,7 @@ especially the contributions of : The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md b/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md index f49feb631..7fa9bb6dd 100644 --- a/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md +++ b/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md @@ -5,7 +5,7 @@ OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships. -In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL](#ODataURL) for details. +In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [#OData-URL#AddressingtheCrossJoinofEntitySets] for details. Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions. diff --git a/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md b/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md index 01f9ce681..f2ebcc9cf 100644 --- a/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md +++ b/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md @@ -7,7 +7,7 @@ The following terms are defined in the vocabulary for data aggregation [OData-Vo ## ##subsec Aggregation Capabilities -The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example ##containerrooted]). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL](#ODataCSDL). The term has a complex type with the following properties: +The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example ##containerrooted]). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [#OData-CSDL#OpenEntityType]. The term has a complex type with the following properties: - The `Transformations` collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If `Transformations` is omitted the server supports all transformations defined by this specification. - The `CustomAggregationMethods` collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported. - `Rollup` specifies whether the service supports no rollup, only a single rollup hierarchy, or multiple rollup hierarchies in a [`groupby`](#Transformationgroupby) transformation. If omitted, multiple rollup hierarchies are supported. diff --git a/odata-data-aggregation-ext/8 Conformance.md b/odata-data-aggregation-ext/8 Conformance.md index 5f1e57b36..057febd1c 100644 --- a/odata-data-aggregation-ext/8 Conformance.md +++ b/odata-data-aggregation-ext/8 Conformance.md @@ -68,7 +68,7 @@ https://www.rfc-editor.org/info/rfc8174. ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-json-format/10 Media Entity.md b/odata-json-format/10 Media Entity.md index 348bfdd74..6bc26b796 100644 --- a/odata-json-format/10 Media Entity.md +++ b/odata-json-format/10 Media Entity.md @@ -34,7 +34,7 @@ object. A single-valued property or operation response that has the `null` value does not have a representation; see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#ResponseCode204NoContent]. A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is @@ -194,7 +194,7 @@ Example ##ex: # ##sec Entity Reference -An entity reference (see [OData-Protocol](#ODataProtocol)) MAY take the +An entity reference (see [#OData-Protocol#EntityIdsandEntityReferences]) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the [id](#ControlInformationidodataid) of the referenced entity and MAY contain the [`type`](#ControlInformationtypeodatatype) diff --git a/odata-json-format/15 Delta Payload.md b/odata-json-format/15 Delta Payload.md index d6263f857..6037a2831 100644 --- a/odata-json-format/15 Delta Payload.md +++ b/odata-json-format/15 Delta Payload.md @@ -109,7 +109,7 @@ entity's primary key fields are omitted from the response _or_ the entity-id is identical to the canonical URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an -[alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) +[alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [#OData-URL#AlternateKeys]) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it @@ -204,7 +204,7 @@ For ordered payloads, this control information MUST follow the information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an - [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) + [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [#OData-URL#AlternateKeys]) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. diff --git a/odata-json-format/16 Bound Function.md b/odata-json-format/16 Bound Function.md index 27e447c5a..9cb2d9da0 100644 --- a/odata-json-format/16 Bound Function.md +++ b/odata-json-format/16 Bound Function.md @@ -7,8 +7,7 @@ A bound function is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) A +service, see [OData-CSDL](#ODataCSDL). A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule @@ -125,8 +124,7 @@ A bound action is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) +service, see [OData-CSDL](#ODataCSDL). An action that is bound to a single structured type is advertised within the JSON object representing that structured type. diff --git a/odata-json-format/19 Batch Requests and Responses.md b/odata-json-format/19 Batch Requests and Responses.md index b70c3addc..3a4ba39d3 100644 --- a/odata-json-format/19 Batch Requests and Responses.md +++ b/odata-json-format/19 Batch Requests and Responses.md @@ -20,13 +20,13 @@ name/value pairs `atomicityGroup`, `dependsOn`, `if`, `headers`, and `body`. The value of `id` is a string containing the request identifier of the individual request, see -[OData-Protocol](#ODataProtocol). It MUST NOT be identical to the value +[#OData-Protocol#IdentifyingIndividualRequests]. It MUST NOT be identical to the value of any other request identifier nor any `atomicityGroup` within the batch request. Note: the `id` name/value pair corresponds to the `Content-ID` header in the multipart batch format specified -in [OData-Protocol](#ODataProtocol). +in [#OData-Protocol#MultipartBatchRequestBody]. The value of `method` is a string that MUST contain one of the literals `delete`, `get`, `patch`, `post`, or `put`. @@ -61,7 +61,7 @@ request, and which MUST satisfy the rule `request-id` in operation and MUST either all succeed, or all fail. Note: the atomicity group is a generalization of the change set in the -multipart batch format specified in [OData-Protocol](#ODataProtocol). +multipart batch format specified in [#OData-Protocol#MultipartBatchRequestBody]. The value of `dependsOn` is an array of strings whose values MUST be values of either `id` or `atomicityGroup` @@ -77,7 +77,7 @@ dependent request is not executed and a response with status code of The `if` member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see -[OData-URL](#ODataURL)) that evaluates to a Boolean value. +[#OData-URL#CommonExpressionSyntax]) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows - `$/$succeeded` @@ -348,7 +348,7 @@ processing the remaining individual requests while waiting for the client to fire a `GET` request to the next link. In a response to a batch request using the multipart format defined in -[OData-Protocol](#ODataProtocol) the response objects +[#OData-Protocol#MultipartBatchFormat] the response objects MUST appear in the same order as required for multipart batch responses because the `Content-ID` header is not required outside of change sets. Response objects corresponding to requests that specify a `Content-ID` header MUST contain the diff --git a/odata-json-format/20 Instance Annotations.md b/odata-json-format/20 Instance Annotations.md index 400e16f98..ff6acfd7b 100644 --- a/odata-json-format/20 Instance Annotations.md +++ b/odata-json-format/20 Instance Annotations.md @@ -13,7 +13,7 @@ dot (`.`) as part of the name. The part after the "at" sign namespace or alias of the schema that defines the term, followed by a dot (`.`), followed by the name of the term, optionally followed by a hash (`#`) and a qualifier. The namespace or alias MUST be defined in the -metadata document, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) +metadata document, see [OData-CSDL](#ODataCSDL). The annotation identifier `odata` is reserved for future extensions of the protocol and format. Instance annotations MUST have a @@ -179,7 +179,7 @@ JSON object in the response. Services MAY include the header `OData-Error` as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#HeaderODataError]. The value of the `OData-Error` trailing header is an OData error object as defined in the preceding chapter, represented in a diff --git a/odata-json-format/23 Conformance.md b/odata-json-format/23 Conformance.md index 2eceda742..9264c00ee 100644 --- a/odata-json-format/23 Conformance.md +++ b/odata-json-format/23 Conformance.md @@ -56,7 +56,7 @@ In order to be a conforming producer of the OData JSON format, a client or servi In addition, in order to conform to the OData JSON format, a service: -11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) +11. MUST comply with one of the conformance levels defined in [#OData-Protocol#Conformance] 12. MUST support the `application/json` media type in the `Accept` header ([section ##RequestingtheJSONFormat]) 13. MUST return well-formed JSON payloads 14. MUST support `odata.metadata=full` ([section ##metadatafullodatametadatafull]) diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md index 4c32577c6..b09a85016 100644 --- a/odata-json-format/4 Common Characteristics.md +++ b/odata-json-format/4 Common Characteristics.md @@ -51,7 +51,7 @@ order of objects within an array in JSON responses. ## ##subsec URLs in Message Bodies URLs represented as a string within a JSON payload, including [batch -requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL](#ODataURL). +requests](#BatchRequest), must follow standard OData encoding rules as defined in [#OData-URL#URLParsing]. For [relative URLs](#RelativeURLs) this means that colons (`:`) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the @@ -212,7 +212,7 @@ stop processing and MUST NOT signal an error. ### ##subsubsec Control Information: `context` (`odata.context`) The `context` control information -returns the context URL (see [OData-Protocol](#ODataProtocol)) for the +returns the context URL (see [#OData-Protocol#ContextURL]) for the payload. This URL can be absolute or [relative](#RelativeURLs). The fragment portion of the context URL MUST NOT be percent-encoded. @@ -226,7 +226,7 @@ entity set cannot be determined from the context URL of the collection. For more information on the format of the context URL, see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#ContextURL]. Request payloads MAY include a context URL as a base URL for [relative URLs](#RelativeURLs) in the request payload. @@ -257,7 +257,7 @@ If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the `metadataEtag` control information in any responses. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [#OData-Protocol#UseofETagsforAvoidingUpdateConflicts]. ### ##subsubsec Control Information: `type` (`odata.type`) @@ -278,7 +278,7 @@ The root `type` may be absolute or relative to the root 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 `$schemaversion` system query option -defined in [OData-Protocol](#ODataProtocol). +defined in [#OData-Protocol#SystemQueryOptionschemaversion]. For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI @@ -287,8 +287,7 @@ fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with `Collection`. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). The `type` control information MUST appear in requests and in responses with [minimal](#metadataminimalodatametadataminimal) or @@ -330,8 +329,7 @@ The `type` control information can be absent in properties nested in an instance In particular, individual primitive values within a collection cannot have `type` control information. For more information on namespace- and alias-qualified names, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). ::: example Example ##ex: entity of type @@ -402,9 +400,9 @@ control information. ### ##subsubsec Control Information: `id` (`odata.id`) The `id` control information contains the entity-id, see -[OData-Protocol](#ODataProtocol). By convention the entity-id is +[#OData-Protocol#EntityIdsandEntityReferences]. By convention the entity-id is identical to the canonical URL of the entity, as defined in -[OData-URL](#ODataURL). +[#OData-URL#CanonicalURL]. The `id` control information MUST appear in responses if [`metadata=full`](#metadatafullodatametadatafull) @@ -424,7 +422,7 @@ if it does not match convention for the localized key values. If the `id` is represented, it MAY be a [relative URL](#RelativeURLs). -If the entity is transient (see [OData-Protocol](#ODataProtocol)), the +If the entity is transient (see [#OData-Protocol#TransientEntities]), the `id` control information MUST appear in OData 4.0 payloads and have the `null` value. In 4.01 or greater payloads transient entities need not have the `id` control information, and @@ -443,10 +441,10 @@ of this specification. ### ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains -the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol](#ODataProtocol). +the edit [URL](URLsinMessageBodies) of the entity; see [#OData-Protocol#ReadURLsandEditURLs]. The `readLink` control information contains the read URL of -the entity or collection; see [OData-Protocol](#ODataProtocol). +the entity or collection; see [#OData-Protocol#ReadURLsandEditURLs]. The `editLink` and `readLink` control information is ignored in request payloads and not written in responses if @@ -500,7 +498,7 @@ 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. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [#OData-Protocol#UseofETagsforAvoidingUpdateConflicts]. The `etag` control information is ignored in request payloads for single entities and not written in responses if diff --git a/odata-json-format/5 Service Document.md b/odata-json-format/5 Service Document.md index 6140d0505..00538e5ad 100644 --- a/odata-json-format/5 Service Document.md +++ b/odata-json-format/5 Service Document.md @@ -15,7 +15,7 @@ The value of the `value` property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of `true` for the attribute `IncludeInServiceDocument` and each singleton exposed by the -service, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +service, see [OData-CSDL](#ODataCSDL). Each element MUST be a JSON object with at least two name/value pairs, one with name `name` containing the name of the entity set, @@ -104,9 +104,8 @@ represented as a name/value pair within the object. The order properties appear within the object is considered insignificant. An entity in a payload may be a complete entity, a projected entity (see -_System Query Option_ `$select` in -[OData-Protocol](#ODataProtocol)), or a partial entity update (see -_Update an Entity_ in [OData-Protocol](#ODataProtocol)). +[#OData-Protocol#SystemQueryOptionselect]), or a partial entity update (see +[#OData-Protocol#UpdateanEntity]). An entity representation can be (modified and) round-tripped to the service directly. The [context diff --git a/odata-json-format/7 Structural Property.md b/odata-json-format/7 Structural Property.md index b09ce9311..1550d31ef 100644 --- a/odata-json-format/7 Structural Property.md +++ b/odata-json-format/7 Structural Property.md @@ -201,6 +201,7 @@ an `Edm.Boolean`, `Edm.String`, or `Edm.Decimal` value, depending on the JavaScript type. Collections directly contained within an untyped collection are themselves untyped. + ------- # ##sec Navigation Property @@ -467,7 +468,7 @@ Instead stream property data is generally read and edited via URLs. [`media*`](#ControlInformationmediaodatamedia) control information. - Stream properties requested with `$expand` or implicitly expanded are represented as a property with its value. -See [OData-Protocol](#ODataProtocol) for details on the system query options `$select` and `$expand`. +See [#OData-Protocol#SystemQueryOptionselect] for details on the system query options `$select` and `$expand`. Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), the stream property MAY be annotated to provide the read link, edit diff --git a/odata-json-format/Appendix.md b/odata-json-format/Appendix.md index 47fe80089..d2650b278 100644 --- a/odata-json-format/Appendix.md +++ b/odata-json-format/Appendix.md @@ -96,7 +96,7 @@ For JSON-relevant security implications please cf. at least the relevant subsect ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md index e8a0d0b67..b43b3c1c8 100644 --- a/odata-protocol/1 Introduction.md +++ b/odata-protocol/1 Introduction.md @@ -16,7 +16,7 @@ service as well as a set of reserved URL query options. The [OData-CSDLJSON](#ODataCSDL) specification defines a JSON representation of the entity data model exposed by an OData service. -The [OData-CSDLXML](#ODataCSDL) specification defines an XML +The [OData-CSDLXML](#ODataCSDLXML) specification defines an XML representation of the entity data model exposed by an OData service. The [OData-JSON](#ODataJSON) document specifies the JSON format of the @@ -210,7 +210,7 @@ set. An OData *resource* is anything in the model that can be addressed (an entity set, entity, property, or operation). -Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) for +Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML) for more information on the OData entity data model. ## ##subsec Annotations @@ -269,7 +269,7 @@ of the specification since there is currently no lossless representation of an IRI in the [`EntityId`](#HeaderODataEntityId) header. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) as its entity-id, but clients cannot assume +as defined in [#OData-URL#CanonicalURL] as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the [`Core.DereferenceableIDs`]($$$OData-VocCore$$$#DereferenceableIDs) term is applied to the entity container, nor can the client assume any @@ -296,7 +296,7 @@ The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) for both the read URL and the edit URL of an +as defined in [#OData-URL#CanonicalURL] for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention diff --git a/odata-protocol/10 Context URL.md b/odata-protocol/10 Context URL.md index 5ad8ce5a5..d2356653f 100644 --- a/odata-protocol/10 Context URL.md +++ b/odata-protocol/10 Context URL.md @@ -569,7 +569,7 @@ Context URL template: {context-url}#Collection(Edm.EntityType) Responses to requests to the virtual collection `$all` (see -[OData-URL](#ODataURL)) use the built-in abstract entity type. Each +[#OData-URL#AddressingAllEntitiesinaService]) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton. @@ -580,5 +580,5 @@ Context URL template: {context-url}#Collection(Edm.ComplexType) Responses to requests to the virtual collections `$crossjoin(…)` (see -[OData-URL](#ODataURL)) use the built-in abstract complex type. Single +[#OData-URL#AddressingtheCrossJoinofEntitySets]) use the built-in abstract complex type. Single instances in these responses do not have a context URL. diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md index 1af411359..229b55478 100644 --- a/odata-protocol/11 Data Service Requests.md +++ b/odata-protocol/11 Data Service Requests.md @@ -67,7 +67,7 @@ metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is `application/json`. -[OData-CSDLXML](#ODataCSDL) describes an XML representation for OData +[OData-CSDLXML](#ODataCSDLXML) describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is `application/xml`. @@ -151,9 +151,9 @@ URL that identifies the entity, e.g. its read URL. The read URL can be obtained from a response payload containing that instance, for example as a `readLink` or `editLink` in an -[OData-JSON](#ODataJSON) payload. In addition, services +[#OData-JSON#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink] payload. In addition, services MAY support conventions for constructing a read URL using the entity's -key value(s), as described in [OData-URL](#ODataURL). +key value(s), as described in [#OData-URL#CanonicalURL]. The set of structural or navigation properties to return may be specified through [`$select`](#SystemQueryOptionselect) or @@ -213,7 +213,7 @@ the property name appended. For complex typed properties, the path can be further extended with the name of an individual property of the complex type. -See [OData-URL](#ODataURL) for details. +See [#OData-URL#AddressingaProperty] for details. If the property is single-valued and has the `null` value, the service responds with [`204 No Content`](#ResponseCode204NoContent). @@ -243,7 +243,7 @@ system query option. #### ##subsubsubsec Requesting a Raw Value using `$value` To retrieve the raw value of a primitive property or operation result, the client sends -a `GET` request to the raw value URL. See the [OData-URL](#ODataURL) document for details. +a `GET` request to the raw value URL. See [#OData-URL#AddressingaRawValue] for details. The `Content-Type` of the response is determined using the `Accept` header and the [`$format`](#SystemQueryOptionformat) system query @@ -442,7 +442,7 @@ GET http://host/service.svc/Customers?$expand=Photo The set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see -[OData-URL](#ODataURL). +[#OData-URL#SystemQueryOptionexpand]. Allowed system query options are [`$compute`](#SystemQueryOptioncompute), @@ -1232,7 +1232,7 @@ GET http://host/service/Orders?$format=application/json;metadata=full is equivalent to a request with an `Accept` header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in -[OData-JSON](#ODataJSON). +[#OData-JSON#metadatafullodatametadatafull]. ::: example Example ##ex: the request @@ -1244,7 +1244,7 @@ GET http://host/service/Orders?$format=json is equivalent to a request with the `Accept` header set to `application/json`; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in -[OData-JSON](#ODataJSON). +[#OData-JSON#metadataminimalodatametadataminimal]. In [metadata document requests](#MetadataDocumentRequest), the values `application/xml` and `application/json`, along with their subtypes and diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 4c61d0e75..67be5abc9 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -733,7 +733,7 @@ deleted, the dependent entity is also deleted. Relationships between entities are represented by navigation properties as described in [Data Model](#DataModel). URL conventions for navigation -properties are described in [OData-URL](#ODataURL). +properties are described in [#OData-URL#URLsforRelatedEntitieswithReferentialConstraints]. #### ##subsubsubsec Add a Reference to a Collection-Valued Navigation Property @@ -759,7 +759,7 @@ collection of related references, with the reference to be removed identified by the [`$id`](#ResolvinganEntityId) query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as -described in [OData-URL](#ODataURL). +described in [#OData-URL#AddressingReferencesbetweenEntities]. For single-valued navigation properties, the [`$id`](#ResolvinganEntityId) query option MUST NOT be specified. @@ -783,7 +783,7 @@ On successful completion, the response MUST be Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see -[OData-JSON](#ODataJSON) for details. +[#OData-JSON#RelatedEntities] for details. If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with @@ -976,7 +976,7 @@ Attempting to request a stream property whose value is null results in Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows -properties to be individually modified. See [OData-URL](#ODataURL) for +properties to be individually modified. See [#OData-URL#AddressingaProperty] for details on addressing individual properties. #### ##subsubsubsec Update a Primitive Property @@ -1261,7 +1261,8 @@ describes an update to each member of the collection, not an update to the collection itself. The resource path of the collection MAY contain type-cast or filter -segments to subset the collection, see [OData-URL](#ODataURL). +segments to subset the collection, see [#OData-URL#AddressingDerivedTypes] and +[#OData-URL#AddressingaSubsetofaCollection]. For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is diff --git a/odata-protocol/11.5 Operations.md b/odata-protocol/11.5 Operations.md index 6406a1079..9313aaabf 100644 --- a/odata-protocol/11.5 Operations.md +++ b/odata-protocol/11.5 Operations.md @@ -4,7 +4,7 @@ Custom operations ([Actions](#Actions) and [Functions](#Functions)) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See `Action`, `ActionImport`, `Function`, and `FunctionImport` in -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML). ### ##subsubsec Binding an Operation to a Resource @@ -123,7 +123,7 @@ bound to the entity An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in -[OData-URL](#ODataURL). +[#OData-URL#AddressingOperations]. Services can advertise that a function or action is not available for a particular instance by setting its value to null. @@ -250,7 +250,7 @@ result requires a `4xx` response, and continues otherwise. Function imports preceded by the `$root` literal MAY be used in the [`$filter`](#SystemQueryOptionfilter) or [`$orderby`](#SystemQueryOptionorderby) system query options, see -[OData-URL](#ODataURL). +[#OData-URL#SystemQueryOptionfilter] and [#OData-URL#SystemQueryOptionorderby]. ##### ##subsubsubsubsec Inline Parameter Syntax @@ -338,7 +338,7 @@ If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the -hierarchy, see [OData-URL](#ODataURL). +hierarchy, see [#OData-URL#AddressingDerivedTypes]. Non-binding parameters MAY be marked as optional by annotating them with the term @@ -474,7 +474,7 @@ If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, -see [OData-URL](#ODataURL). +see [#OData-URL#AddressingDerivedTypes]. ## ##subsec Asynchronous Requests diff --git a/odata-protocol/11.7 Batch Requests.md b/odata-protocol/11.7 Batch Requests.md index df053c89c..c8e46f9b9 100644 --- a/odata-protocol/11.7 Batch Requests.md +++ b/odata-protocol/11.7 Batch Requests.md @@ -17,7 +17,7 @@ a batch request. A batch request is represented using either the [multipart batch format](#MultipartBatchFormat) defined in this document or the JSON -batch format defined in [OData-JSON](#ODataJSON). +batch format defined in [#OData-JSON#BatchRequestsandResponses]. If the set of request headers of a batch request are valid the service MUST return a [`200 OK`](#ResponseCode200OK) HTTP response code to diff --git a/odata-protocol/12 Conformance.md b/odata-protocol/12 Conformance.md index 13adc84b9..262959d7d 100644 --- a/odata-protocol/12 Conformance.md +++ b/odata-protocol/12 Conformance.md @@ -60,7 +60,7 @@ request 7. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) for any supported system query options and follow the specification or fail the request -8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL) +8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDLXML) 9. MUST NOT require clients to understand any metadata or instance annotations ([section ##VocabularyExtensibility]), custom headers ([section ##HeaderFieldExtensibility]), or custom content ([section ##PayloadExtensibility]) in the payload in order to correctly consume the @@ -70,7 +70,7 @@ service 11. MUST NOT violate any other OData-defined semantics 12. SHOULD support `$expand` ([section ##SystemQueryOptionexpand]) 13. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) and MAY publish metadata according to +[OData-CSDLXML](#ODataCSDLXML) and MAY publish metadata according to [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 14. MUST support prefixed variants of supported headers and preference values @@ -88,7 +88,7 @@ final response to an asynchronous request To be considered an *Updatable OData Service*, the service additionally: 18. MUST include edit links (explicitly or implicitly) for all -updatable or deletable resources according to [OData-JSON](#ODataJSON) +updatable or deletable resources according to [#OData-JSON#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink] 19. MUST support `POST` of new entities to insertable entity sets ([section ##ReturningResultsfromDataModificationRequests]) 20. MUST support `POST` of new related entities to updatable navigation @@ -129,7 +129,7 @@ Level](#OData40MinimalConformanceLevel) follow the specification or fail the request 3. MUST support `$select` ([section ##SystemQueryOptionselect]) 4. MUST support casting to a derived type according to -[OData-URL](#ODataURL) if derived types are present in the model +[#OData-URL#AddressingDerivedTypes] if derived types are present in the model 5. MUST support `$top` ([section ##SystemQueryOptiontop]) 6. MUST support `/$value` on media entities ([section ##MetadataDocumentRequest]) and individual properties ([section ##RequestingaRawValueusingvalue]) 7. MUST support `$filter` ([section ##SystemQueryOptionfilter]) @@ -143,7 +143,7 @@ operations MUST fail the request for any unsupported canonical functions 5. SHOULD support `$filter` on expanded entities ([section ##ExpandOptions]) 8. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) ([section ##MetadataDocumentRequest]) 9. SHOULD support the [OData-JSON](#ODataJSON) format 10. SHOULD consider supporting basic authentication as defined in [RFC7617](#rfc7617) over HTTPS for the highest level of interoperability @@ -166,7 +166,7 @@ In order to conform to the OData Advanced Conformance Level, a service: 1. MUST conform to at least the [OData 4.0 Intermediate Conformance Level](#OData40IntermediateConformanceLevel) 2. MUST publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) ([section ##MetadataDocumentRequest]) 3. MUST support the [OData-JSON](#ODataJSON) format 4. MUST support the `/$count` segment on navigation and collection properties ([section ##RequestingtheNumberofItemsinaCollection]) @@ -191,13 +191,13 @@ properties 10. MUST support the `$search` system query option ([section ##SystemQueryOptionsearch]) 11. MUST support batch requests according to the multipart format ([section ##BatchRequests] and all subsections) and MAY support batch requests -according to the JSON Batch format defined in [OData-JSON](#ODataJSON) +according to the JSON Batch format defined in [#OData-JSON#BatchRequestsandResponses] 12. MUST support the resource path conventions defined in -[OData-URL](#ODataURL) +[#OData-URL#ResourcePath] 13. SHOULD support asynchronous requests ([section ##AsynchronousRequests]) 14. SHOULD support Delta change tracking ([section ##RequestingChanges]) -15. SHOULD support cross-join queries defined in [OData-URL](#ODataURL) +15. SHOULD support cross-join queries defined in [#OData-URL#AddressingtheCrossJoinofEntitySets] 16. MAY support the `$compute` system query option ([section ##SystemQueryOptioncompute]) ## ##subsec OData 4.01 Service Conformance Levels @@ -258,12 +258,12 @@ with a maximum cardinality of one 11. SHOULD support negative indexes for the substring function 12. MAY support Key-As-Segment URL convention 1. MUST also support canonical URL conventions (described in -[OData-URL](#ODataURL)) or include URLs in payload +[#OData-URL#CanonicalURL]) or include URLs in payload 13. MAY support the count of a filtered collection in a common expression 14. MAY support equal and non-equal structural comparison 10. SHOULD publish metadata at `$metadata` according to both -[OData-CSDLXML](#ODataCSDL) and [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) and [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 11. SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case @@ -345,7 +345,7 @@ properties [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 7. MUST support batch requests according both to the multipart format ([section ##BatchRequests] and all subsections) and the JSON Batch format defined in -[OData-JSON](#ODataJSON) +[#OData-JSON#BatchRequestsandResponses] 8. SHOULD support filtering a collection using a `/$filter` path segment 9. SHOULD support nested parameter alias assignments in @@ -368,7 +368,7 @@ To be generally interoperable, OData clients 2. MUST specify `OData-Version` ([section ##HeaderODataVersion]) and `Content-Type` ([section ##HeaderContentType]) in any request with a payload 3. MUST be a conforming consumer of OData as defined in -[OData-JSON](#ODataJSON) +[#OData-JSON#Conformance] 4. MUST follow redirects ([section ##ResponseCode3xxRedirection]) 5. MUST correctly handle next links ([section ##ServerDrivenPaging]) 6. MUST support instances returning properties and navigation @@ -388,9 +388,9 @@ returned in the response ([section ##RequestingEntityReferences]) in a delta response ([section ##RequestingChanges]) 14. MAY support asynchronous responses ([section ##AsynchronousRequests]) 15. MAY support `metadata=minimal` in a JSON response (see -[OData-JSON](#ODataJSON)) +[#OData-JSON#metadataminimalodatametadataminimal]) 16. MAY support `streaming` in a JSON response (see -[OData-JSON](#ODataJSON)) +[#OData-JSON#PayloadOrderingConstraints]) In addition, interoperable OData 4.01 clients diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md index aa388e72c..f7b7b985d 100644 --- a/odata-protocol/8 Header Fields.md +++ b/odata-protocol/8 Header Fields.md @@ -27,7 +27,7 @@ ignored. Custom format parameters MUST NOT start with `odata` and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload. -See [OData-JSON](#ODataJSON) for format-specific details about format +See [#OData-JSON#HeaderContentType] for format-specific details about format parameters within the `Content-Type` header. ### ##subsubsec Header `Content-Encoding` @@ -838,7 +838,7 @@ HTTP/2). The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport -in a header, see e.g. [OData-JSON](#ODataJSON). +in a header, see e.g. [#OData-JSON#InStreamError]. ### ##subsubsec Header `Preference-Applied` diff --git a/odata-protocol/Appendix.md b/odata-protocol/Appendix.md index 7f458754b..c3fe5fdf2 100644 --- a/odata-protocol/Appendix.md +++ b/odata-protocol/Appendix.md @@ -19,10 +19,11 @@ See link in "[Related work](#RelatedWork)" section on cover page. _OData Extension for Data Aggregation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-CSDL]{id=ODataCSDL} +###### [OData-CSDLJSON]{id=ODataCSDL} _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLXML]{id=ODataCSDLXML} _OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. diff --git a/odata-temporal-ext/4.3 Modifying Temporal Data.md b/odata-temporal-ext/4.3 Modifying Temporal Data.md index 5e2ba23e9..8cf601064 100644 --- a/odata-temporal-ext/4.3 Modifying Temporal Data.md +++ b/odata-temporal-ext/4.3 Modifying Temporal Data.md @@ -54,7 +54,7 @@ slices. These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data [OData-VocTemporal](#ODataVocTemporal). Implementations SHOULD consider the preferences `return=representation` -and `return=minimal` as specified inv[OData-Protocol](#ODataProtocol). +and `return=minimal` as specified in [#OData-Protocol#Preferencereturnrepresentationandreturnminimal]. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects. @@ -108,7 +108,7 @@ This works identical to the SQL statement UPDATE FOR PORTION OF: slice's period. 4. Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities - specified in [OData-Protocol](#ODataProtocol). + specified in [#OData-Protocol#UpdateanEntity]. 5. Gaps between selected time slices in the period to update are not affected. On success it returns the created or updated time slices. @@ -301,10 +301,10 @@ Step 5 is (except for computed properties), 2. setting the period boundaries to close the gap, and then 3. updating the new time slice following the rules for updating - entities specified in [OData-Protocol](#ODataProtocol). + entities specified in [#OData-Protocol#UpdateanEntity]. If no preceding time slice exists, the time slice is created following - the rules for creating entities specified in [OData-Protocol](#ODataProtocol). + the rules for creating entities specified in [#OData-Protocol#CreateanEntity]. On success it returns the created or updated time slices. @@ -450,7 +450,7 @@ This works identical to the SQL statement DELETE FOR PORTION OF: slices, one with non-overlapping, and one with fully included period. 4. Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities - specified in [OData-Protocol](#ODataProtocol). + specified in [#OData-Protocol#DeleteanEntity]. On success it returns the deleted time slices. diff --git a/odata-temporal-ext/Appendix.md b/odata-temporal-ext/Appendix.md index 90b20e4fc..14d055657 100644 --- a/odata-temporal-ext/Appendix.md +++ b/odata-temporal-ext/Appendix.md @@ -78,7 +78,7 @@ _ISO/IEC 9075-2:2011 Information technology - Database languages - SQL - Part 2: ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track. diff --git a/odata-url-conventions/1 Introduction.md b/odata-url-conventions/1 Introduction.md index 5a141e690..cda1a171d 100644 --- a/odata-url-conventions/1 Introduction.md +++ b/odata-url-conventions/1 Introduction.md @@ -212,7 +212,7 @@ path segment, nor is `Tablet')`. The service root URL identifies the root of an OData service. A `GET` request to this URL returns the format-specific service document, see -[OData-JSON](#ODataJSON). +[#OData-JSON#ServiceDocument]. The service root URL MUST terminate in a forward slash. diff --git a/odata-url-conventions/4 Resource Path.md b/odata-url-conventions/4 Resource Path.md index bc00cc85d..cfd518641 100644 --- a/odata-url-conventions/4 Resource Path.md +++ b/odata-url-conventions/4 Resource Path.md @@ -33,7 +33,7 @@ An OData service MAY respond with `301 Moved Permanently` or ## ##subsec Addressing the Model for a Service OData services expose their entity model according to -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) at the +[OData-CSDL](#ODataCSDL) at the metadata URL, formed by appending `$metadata` to the [service root URL](#ServiceRootURL). @@ -270,8 +270,7 @@ http://host/service/Products(1) ### ##subsubsec Canonical URL for Contained Entities For contained entities (i.e. related via a containment navigation -property, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL)) the canonical URL is the canonical URL of +property, see [OData-CSDLJSON](#ODataCSDL)) the canonical URL is the canonical URL of the containing entity followed by: - A [type-cast segment](#AddressingDerivedTypes) if the navigation property is defined on a type derived from the entity type declared for @@ -333,8 +332,7 @@ http://host/service/$entity?$id=Products(0) ``` ::: -The semantics of `$entity` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$entity` are covered in [#OData-Protocol#ContextURL]. ### ##subsubsec Alternate Keys @@ -452,7 +450,7 @@ such 2. matches a qualified bound function, bound action, or type name, treat it as such 3. matches an unqualified bound function, bound action, or type name -defined in a default namespace (see [OData-Protocol](#ODataProtocol)) treat it +defined in a default namespace (see [#OData-Protocol#DefaultNamespaces]) treat it as such 4. treat as a key value @@ -494,7 +492,7 @@ addressing a collection of references MUST be followed by the system query option `$id` in order to identify a single entity reference within the collection to be removed. The entity-id specified by `$id` may be expressed absolute or relative to the request URL. For details see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#EntityIdsandEntityReferences]. ::: example Example ##ex: three ways of unrelating `Categories(1)` and @@ -515,14 +513,14 @@ DELETE http://host/service/Products(0)/Category/$ref ## ##subsec Addressing Operations The semantic rules for addressing and invoking actions and functions are -defined in the [OData-Protocol](#ODataProtocol) document. +defined in [#OData-Protocol#Operations]. Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. ### ##subsubsec Addressing Actions @@ -569,7 +567,7 @@ syntax rule define the grammar for invoking functions, for example to help filte and order resources identified by the `resourcePath` of the URL. - The `aliasAndValue` syntax rule defines the grammar for providing function parameter values using Parameter -Alias Syntax, see [OData-Protocol](#ODataProtocol). +Alias Syntax, see [#OData-Protocol#ParameterAliases]. Note: there is no literal representation for `Edm.Stream` values in URLs, so it is not possible to pass `Edm.Stream` values to parameters of function imports or @@ -746,7 +744,7 @@ derived type in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a diff --git a/odata-url-conventions/5 Query Options.md b/odata-url-conventions/5 Query Options.md index 4222a8dcb..d82a7de56 100644 --- a/odata-url-conventions/5 Query Options.md +++ b/odata-url-conventions/5 Query Options.md @@ -57,8 +57,8 @@ The same system query option, irrespective of casing or whether or not it is prefixed with a `$`, MUST NOT be specified more than once for any resource. -The semantics of all system query options are defined in the -[OData-Protocol](#ODataProtocol) document. +The semantics of all system query options are defined in +[#OData-Protocol#SystemQueryOptions]. The grammar and syntax rules for system query options are defined in [OData-ABNF](#ODataABNF). @@ -1909,7 +1909,7 @@ Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) annotation term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a [parameter alias](#ParameterAliases), then any occurrence of the parameter alias @@ -2336,7 +2336,7 @@ omitted from the response. Annotations requested in `$select` MUST be included in the response; `$select` overrules the `include-annotations` preference (see -[OData-Protocol](#ODataProtocol)) for the explicitly requested annotations. +[#OData-Protocol#Preferenceincludeannotationsodataincludeannotations]) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via `$select`. The `Preference-Applied` response header only reflects the set of annotations included due to the @@ -2375,8 +2375,7 @@ identified by each select item. The `$orderby` system query option allows clients to request resources in a particular order. -The semantics of `$orderby` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$orderby` are covered in [#OData-Protocol#SystemQueryOptionorderby]. The [OData-ABNF](#ODataABNF) `orderby` syntax rule defines the formal grammar of the `$orderby` query option. @@ -2389,8 +2388,9 @@ option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining `$top` and `$skip`. -The semantics of `$top` and `$skip` are covered in the -[OData-Protocol](#ODataProtocol) document. The [OData-ABNF](#ODataABNF) `top` +The semantics of `$top` and `$skip` are covered in +[#OData-Protocol#SystemQueryOptiontop] and [#OData-Protocol#SystemQueryOptionskip]. +The [OData-ABNF](#ODataABNF) `top` and `skip` syntax rules define the formal grammar of the `$top` and `$skip` query options respectively. @@ -2400,8 +2400,7 @@ The `$count` system query option allows clients to request a count of the matching resources included with the resources in the response. The `$count` query option has a Boolean value of `true` or `false`. -The semantics of `$count` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$count` is covered in [#OData-Protocol#SystemQueryOptioncount]. ### ##subsubsec System Query Option `$search` @@ -2483,8 +2482,7 @@ in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present `$format` takes precedence over standard content-type negotiation. -The semantics of `$format` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$format` is covered in [#OData-Protocol#SystemQueryOptionformat]. The [OData-ABNF](#ODataABNF) `format` syntax rule defines the formal grammar of the `$format` query option. @@ -2547,7 +2545,7 @@ grammar of the `$index` query option. The `$schemaversion` system query option allows clients to specify the version of the schema against which the request is made. The semantics -of `$schemaversion` is covered in the [OData-Protocol](#ODataProtocol) document. +of `$schemaversion` is covered in [#OData-Protocol#SystemQueryOptionschemaversion]. The [OData-ABNF](#ODataABNF) `schemaversion` syntax rule defines the formal grammar of the `$schemaversion` query option @@ -2579,7 +2577,7 @@ Parameter aliases MUST start with an `@` character, see rule `parameterAlias` in [OData-ABNF](#ODataABNF). The semantics of parameter aliases are covered in -[OData-Protocol](#ODataProtocol). The [OData-ABNF](#ODataABNF) rule +[#OData-Protocol#ParameterAliases]. The [OData-ABNF](#ODataABNF) rule `aliasAndValue` defines the formal grammar for passing parameter alias values as query options. @@ -2612,4 +2610,4 @@ http://host/service/Products/Model.WithIngredients(Ingredients=@i) # ##sec Conformance The conformance requirements for OData clients and services are -described in [OData-Protocol](#ODataProtocol). +described in [#OData-Protocol#Conformance]. diff --git a/odata-vocabularies/Appendix.md b/odata-vocabularies/Appendix.md index 96dbe7e90..00357a24f 100644 --- a/odata-vocabularies/Appendix.md +++ b/odata-vocabularies/Appendix.md @@ -50,7 +50,7 @@ do we have considerations specific to URLs, for example length, encoding, privac ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Partipants], are gratefully acknowledged. ## ##subasec Participants From 874253e07c209a67ce27fe3e551d090aaecefb30 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 6 Nov 2024 19:01:24 +0100 Subject: [PATCH 5/5] return=minimal for status monitor resources (#2024) Fixes #336 --- docs/odata-protocol/odata-protocol.html | 4 ++-- docs/odata-protocol/odata-protocol.md | 14 ++++++++------ odata-protocol/11.5 Operations.md | 14 ++++++++------ 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 35d02a8b8..244404065 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -3013,8 +3013,8 @@

      202 Accepted response. A service MUST NOT reply to a Data Service Request with 202 Accepted if the request has not included the respond-async preference.

      Responses that return 202 Accepted MUST include a Location header pointing to a status monitor resource that represents the current state of the asynchronous processing in addition to an optional Retry-After header indicating the time, in seconds, the client should wait before querying the service for status. Services MAY include a response body, for example, to provide additional status information.

      A GET request to the status monitor resource again returns 202 Accepted response if the asynchronous processing has not finished. This response MUST again include a Location header and MAY include a Retry-After header to be used for a subsequent request. The Location header and optional Retry-After header may or may not contain the same values as returned by the previous request.

      -

      A GET request to the status monitor resource returns 200 OK once the asynchronous processing has completed. For OData 4.01 or greater responses, or OData 4.0 requests that include an Accept header that does not specify application/http, the response MUST include the AsyncResult response header. Any other headers, along with the response body, represent the result of the completed asynchronous operation. If the GET request to the status monitor includes an OData-MaxVersion header with a value of 4.0 and no Accept header, or an Accept header that includes application/http, then the body of the final 200 OK response MUST be represented as an HTTP message, as described in RFC9110, which is the full HTTP response to the completed asynchronous operation.

      -

      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.

      +

      Once the asynchronous processing has completed, a GET request to the status monitor resource returns 200 OK, or 204 No Content if the request included a Prefer header with a value of return=minimal that was applied by the service. For OData 4.01 or greater responses, or OData 4.0 requests that include an Accept header that does not specify application/http, the response MUST include the AsyncResult response header. A 204 No Content response MUST include a Location header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request’s URL. In a 200 OK response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the GET request to the status monitor includes an OData-MaxVersion header with a value of 4.0 and no Accept header, or an Accept header that includes application/http, then the body of the final 200 OK response MUST be represented as an HTTP message, as described in RFC9110, which is the full HTTP response to the completed asynchronous operation.

      +

      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.

      After a successful DELETE request against the status monitor resource, any subsequent GET requests for the same status monitor resource returns 404 Not Found.

      If an asynchronous request is cancelled for reasons other than the consumers issuing a DELETE request against the status monitor resource, a GET request to the status monitor resource returns 200 OK with a response body containing a single HTTP response with a status code in the 5xx Server Error range indicating that the operation was cancelled.

      The service MUST ensure that no observable change has occurred as a result of a canceled request.

      diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 88e7ac8d8..acc0233cd 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -5864,11 +5864,13 @@ and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a sub `Location` header and optional `Retry-After` header may or may not contain the same values as returned by the previous request. -A `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK) once the -asynchronous processing has completed. For OData 4.01 or greater -responses, or OData 4.0 requests that include an `Accept` header that +Once the asynchronous processing has completed, a `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK), +or [`204 No Content`](#ResponseCode204NoContent) if the request included a `Prefer` header with a value of `return=minimal` that was applied by the service. +For OData 4.01 or greater responses, or OData 4.0 requests that include an `Accept` header that does not specify `application/http`, the response MUST include the -[`AsyncResult`](#HeaderAsyncResult) response header. Any other headers, +[`AsyncResult`](#HeaderAsyncResult) response header. +A `204 No Content` response MUST include a `Location` header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request's URL. +In a `200 OK` response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the `GET` request to the status monitor includes an `OData-MaxVersion` header with a value of `4.0` and no @@ -5879,11 +5881,11 @@ HTTP response to the completed asynchronous operation. A `DELETE` request sent to the status monitor resource requests that the asynchronous processing be canceled. A `200 OK` or a -[`204 No Content`](#ResponseCode204NoContent) response indicates that the asynchronous processing has +`204 No Content` response indicates that the asynchronous processing has been successfully canceled. A client can request that the `DELETE` should be executed asynchronously. A `202 Accepted` response indicates that the cancellation is being processed asynchronously; the client can -use the returned [`Location`](#HeaderLocation) header (which MUST be +use the returned `Location` header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns diff --git a/odata-protocol/11.5 Operations.md b/odata-protocol/11.5 Operations.md index 9313aaabf..4d5d08928 100644 --- a/odata-protocol/11.5 Operations.md +++ b/odata-protocol/11.5 Operations.md @@ -505,11 +505,13 @@ and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a sub `Location` header and optional `Retry-After` header may or may not contain the same values as returned by the previous request. -A `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK) once the -asynchronous processing has completed. For OData 4.01 or greater -responses, or OData 4.0 requests that include an `Accept` header that +Once the asynchronous processing has completed, a `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK), +or [`204 No Content`](#ResponseCode204NoContent) if the request included a `Prefer` header with a value of `return=minimal` that was applied by the service. +For OData 4.01 or greater responses, or OData 4.0 requests that include an `Accept` header that does not specify `application/http`, the response MUST include the -[`AsyncResult`](#HeaderAsyncResult) response header. Any other headers, +[`AsyncResult`](#HeaderAsyncResult) response header. +A `204 No Content` response MUST include a `Location` header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request's URL. +In a `200 OK` response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the `GET` request to the status monitor includes an `OData-MaxVersion` header with a value of `4.0` and no @@ -520,11 +522,11 @@ HTTP response to the completed asynchronous operation. A `DELETE` request sent to the status monitor resource requests that the asynchronous processing be canceled. A `200 OK` or a -[`204 No Content`](#ResponseCode204NoContent) response indicates that the asynchronous processing has +`204 No Content` response indicates that the asynchronous processing has been successfully canceled. A client can request that the `DELETE` should be executed asynchronously. A `202 Accepted` response indicates that the cancellation is being processed asynchronously; the client can -use the returned [`Location`](#HeaderLocation) header (which MUST be +use the returned `Location` header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns