diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index e05c7694..718ece73 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -464,25 +464,35 @@

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 15.2 +Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers +375 + Section 17 Additional conformance clauses for version 4.02 @@ -813,7 +823,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.

@@ -1009,7 +1019,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.

@@ -1290,7 +1300,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.

@@ -1299,7 +1309,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.

@@ -1330,7 +1340,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.

    @@ -1485,7 +1495,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.

    @@ -1578,7 +1588,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.

    @@ -1746,7 +1756,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.

    @@ -2011,8 +2021,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

    @@ -2331,7 +2340,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:

      @@ -2404,8 +2413,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

      @@ -2931,7 +2940,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:

      @@ -2942,7 +2951,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.

      @@ -2973,7 +2982,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.

      @@ -3020,7 +3029,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
      @@ -3233,7 +3242,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

      @@ -3345,7 +3354,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.

      @@ -3475,7 +3484,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:

      @@ -3598,7 +3607,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.

      @@ -3786,7 +3795,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.

      @@ -3884,6 +3893,7 @@

      The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)”, “Letter number (Nl)”, “Decimal number (Nd)”, “Non-spacing mark (Mn)”, “Combining spacing mark (Mc)”, “Connector punctuation (Pc)”, and “Other, format (Cf)”.

      Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.

      +

      For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern ^[_A-Za-z][_A-Za-z0-9]*$.

      15.3 Qualified Name

      @@ -4221,9 +4231,10 @@

      17 Conformance
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
      • -

      In addition, OData 4.01 services:

      +

      In addition, OData 4.02 or greater services:

      1. SHOULD NOT include constant Geo or Stream values in annotations
        2. +
      2. SHOULD use simple identifiers matching the pattern ^[_A-Za-z][_A-Za-z0-9]*$

      Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom annotations, and MUST ignore constructs not defined in this version of the specification.

      @@ -4279,6 +4290,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.

      @@ -4478,7 +4491,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 a4cf256b..f8f960a6 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -268,10 +268,12 @@ 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) [Section 14.4.7](#IfThenElse)| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326) +[Section 15.2](#SimpleIdentifier) | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375) [Section 17](#Conformance) | Additional conformance clauses for version 4.02 | ## 1.2 Glossary @@ -672,7 +674,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 @@ -992,8 +994,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} @@ -1499,7 +1501,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` @@ -1520,7 +1522,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. @@ -1581,7 +1583,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 @@ -1864,7 +1866,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). @@ -2071,7 +2073,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. @@ -2393,7 +2395,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` @@ -2895,10 +2897,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. @@ -3543,7 +3542,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. @@ -3685,10 +3684,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. ::: @@ -4205,7 +4204,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} @@ -4220,7 +4219,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. ::: @@ -4268,7 +4267,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 (`/`). @@ -4404,7 +4403,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 @@ -4776,7 +4775,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. @@ -4914,7 +4913,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 --------|----------- @@ -5047,10 +5046,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 @@ -5232,7 +5231,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` @@ -5560,7 +5559,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. @@ -5697,6 +5696,10 @@ restrictions: Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits. +For maximum interoperability services SHOULD use simple identifiers +that additionally only consist of characters from the Basic Latin code block +and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`. + ## 15.3 Qualified Name For model elements that are direct children of a schema: the namespace @@ -6073,9 +6076,10 @@ In addition, OData 4.01 or greater services: schema, a structural type, or an entity container) that differ only by case -In addition, OData 4.01 services: +In addition, OData 4.02 or greater services: 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations +16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$` Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom @@ -6155,6 +6159,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. @@ -6316,7 +6324,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 14978ace..8eb5d574 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -468,25 +468,35 @@

      348

      + + + + + - + - + - + + + + + + @@ -989,7 +999,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.

      @@ -1233,7 +1243,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.

      @@ -1242,7 +1252,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.

      @@ -1273,7 +1283,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.

      @@ -1481,7 +1491,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.

      @@ -1632,7 +1642,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.

      @@ -1897,8 +1907,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

      @@ -2159,7 +2168,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:

        @@ -2866,7 +2875,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.

        @@ -2913,7 +2922,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
        @@ -3128,7 +3137,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

        @@ -3194,7 +3203,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.

      Section 12.8Returned collections of entities may contain null values1983
      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 15.2Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers375
      Section 17 Additional conformance clauses for version 4.02
      @@ -3288,7 +3297,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:

      @@ -3367,7 +3376,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.

      @@ -3638,6 +3647,7 @@

      The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)”, “Letter number (Nl)”, “Decimal number (Nd)”, “Non-spacing mark (Mn)”, “Combining spacing mark (Mc)”, “Connector punctuation (Pc)”, and “Other, format (Cf)”.

      Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.

      +

      For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern ^[_A-Za-z][_A-Za-z0-9]*$.

      15.3 Qualified Name

      @@ -3857,9 +3867,10 @@

      17 Conformance
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
      • -

      In addition, OData 4.01 services:

      +

      In addition, OData 4.02 or greater services:

      1. SHOULD NOT include constant Geo or Stream values in annotations
        2. +
      2. SHOULD use simple identifiers matching the pattern ^[_A-Za-z][_A-Za-z0-9]*$

      Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom annotations, and MUST ignore constructs not defined in this version of the specification.

      @@ -4190,7 +4201,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 1e4fa24a..9b762167 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -269,10 +269,12 @@ 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) [Section 14.4.7](#IfThenElse)| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326) +[Section 15.2](#SimpleIdentifier) | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375) [Section 17](#Conformance) | Additional conformance clauses for version 4.02 | ## 1.2 Glossary @@ -927,8 +929,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. @@ -1417,7 +1419,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} @@ -1438,7 +1440,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. @@ -1499,7 +1501,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 @@ -1955,7 +1957,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. @@ -2271,7 +2273,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} @@ -2772,10 +2774,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. @@ -3349,7 +3348,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. @@ -4199,7 +4198,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 (`/`). @@ -4335,7 +4334,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 @@ -4714,7 +4713,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. @@ -4803,7 +4802,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 --------|----------- @@ -4899,10 +4898,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 @@ -5040,7 +5039,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). @@ -5497,6 +5496,10 @@ restrictions: Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits. +For maximum interoperability services SHOULD use simple identifiers +that additionally only consist of characters from the Basic Latin code block +and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`. + ## 15.3 Qualified Name For model elements that are direct children of a schema: the namespace @@ -5755,9 +5758,10 @@ In addition, OData 4.01 or greater services: schema, a structural type, or an entity container) that differ only by case -In addition, OData 4.01 services: +In addition, OData 4.02 or greater services: 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations +16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$` Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom @@ -6044,7 +6048,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 bf4590bc..c9d45241 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.
        • @@ -3628,12 +3628,11 @@

        { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14, "Total@type": "Decimal", "Total": 8 }, { "ID": "P4", "Name": "Pencil", "Color": "Black", "TaxRate": 0.14, - "Total": null }, + "Total": null }, { "ID": "P1", "Name": "Sugar", "Color": "White", "TaxRate": 0.06, "Total@type": "Decimal", "Total": 4 } ] }

      -

      The expression $it/Sales refers to the sales of the current product. Without $it, all sales of all products would be aggregated, because the input collection for the aggregate function consists of all products.

      Example 79: Alternatively, join could be applied to yield a flat structure:

      @@ -4922,7 +4921,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 773993b5..7c9ac06b 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. @@ -3471,14 +3471,12 @@ results in { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14, "Total@type": "Decimal", "Total": 8 }, { "ID": "P4", "Name": "Pencil", "Color": "Black", "TaxRate": 0.14, - "Total": null }, + "Total": null }, { "ID": "P1", "Name": "Sugar", "Color": "White", "TaxRate": 0.06, "Total@type": "Decimal", "Total": 4 } ] } ``` - -The expression `$it/Sales` refers to the sales of the current product. Without `$it`, all sales of all products would be aggregated, because the input collection for the `aggregate` function consists of all products. ::: ::: example @@ -5012,7 +5010,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 8aebc90f..c5828252 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 name/value pair whose name is value and whose value is a primitive value or null.

      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 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 27c9e503..1796b501 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 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 50148984..ebaf7601 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

      @@ -584,31 +584,36 @@

      356

      + + + + + - + - + - + - + - + @@ -704,7 +709,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 +734,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 +744,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 +873,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 +1163,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

      @@ -1304,15 +1309,16 @@

      10 Context URL

      For details on how the context URL is used to describe a payload, see the relevant sections in the particular format.

      The following subsections describe how the context URL is constructed for each category of payload by providing a context URL template. The context URL template uses the following terms:

        -
      • {context-url} is the canonical resource path to the $metadata document,
        • -
      • {entity-set} is the name of an entity set or path to a containment navigation property,
        • -
      • {entity} is the canonical URL for an entity,
        • -
      • {singleton} is the canonical URL for a singleton entity,
        • -
      • {select-list} is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions,
        • -
      • {property-path} is the path to a structural property of the entity,
        • -
      • {type-name} is a qualified type name,
        • +
      • {context-url} is the canonical resource path to the $metadata document.
        • +
      • A canonical collection is an entity set OData-CSDL, section 13.2 or a collection addressed by a containment navigation property OData-CSDL, section 8.4. We denote by {canonical-collection} the canonical URL OData-URL, section 4.3.1 that addresses a canonical collection relative to the service root.
        • +
      • A canonical singleton is a singleton OData-CSDL, section 13.3 or an entity addressed by a single-valued containment navigation property. We denote by {canonical-singleton} the canonical URL that addresses a canonical singleton relative to the service root.
        • +
      • A canonical member is an entity within a canonical collection. We denote by {canonical-member} the canonical URL that addresses a canonical member relative to the service root.
        • +
      • {select-list} is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions.
        • +
      • {property-path} is the path to a structural property of the entity.
        • +
      • {type-name} is a qualified type name.
      • {/type-name} is an optional type-cast segment containing the qualified name of a derived or implemented type prefixed with a forward slash.
      +

      Key values in {canonical-collection}, {canonical-singleton}, and {canonical-member} are represented in canonical form (parentheses-style) without percent-encoding.

      The full grammar for the context URL is defined in OData-ABNF. Note that the syntax of the context URL is independent of whatever URL conventions the service uses for addressing individual entities.

      10.1 Service Document

      @@ -1330,62 +1336,65 @@

      10

      10.2 Collection of Entities

      Context URL template:

      -
      {context-url}#{entity-set}
+
      {context-url}#{canonical-collection}
 {context-url}#Collection({type-name})
      
-
      If all entities in the collection are members of one entity set, its name is the context URL fragment.
      
+
      If all entities in the response or a response part are members of a single canonical collection, the context URL fragment is the {canonical-collection}.
      
 
      
 
      Example 11: resource URL and corresponding context URL
      
 
      http://host/service/Customers
 http://host/service/$metadata#Customers
      
 
      
-
      If the entities are contained, then entity-set is the top-level entity set or singleton followed by the canonical path to the containment navigation property of the containing entity. Key values in that path are represented in canonical form (parentheses-style) without percent-encoding.
      
 
      
 
      Example 12: resource URL and corresponding context URL for contained entities
      
 
      http://host/service/Orders(4711)/Items
 http://host/service/$metadata#Orders(4711)/Items
      
 
      
-
      If the entities in the response are not bound to a single entity set, such as from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the type of the returned entity collection.
      
+
      If the entities are not members of a single canonical collection, such as entities from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the type of the returned entity collection.

      10.3 Entity

      Context URL template:

      -
      {context-url}#{entity-set}/$entity
+
      {context-url}#{canonical-collection}/$entity
 {context-url}#{type-name}
      
-
      If a response or response part is a single entity of the declared type of an entity set, the context URL fragment is the entity set’s name with /$entity appended.
      
+
      If a response or response part is an entity within in a canonical collection, the context URL fragment is the {canonical-collection} with /$entity appended.
      
 
      
-
      Example 13: resource URL and corresponding context URL
      
+
      Example 13: resource URL and corresponding context URL for named entity set. Note the absence of the key predicate (1) in the context URL.
      
 
      http://host/service/Customers(1)
 http://host/service/$metadata#Customers/$entity
      
 
      
-
      If the entity is contained, then entity-set is the top-level entity set or singleton followed by the path to the containment navigation property of the containing entity.
      
 
      
 
      Example 14: resource URL and corresponding context URL for contained entity
      
 
      http://host/service/Orders(4711)/Items(1)
 http://host/service/$metadata#Orders(4711)/Items/$entity
      
 
      
-
      If the entity is not bound to an entity set, such as an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the type of the returned entity.
      
+
      If the entity is within a collection, but a canonical collection cannot be determined, such as for an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the {type-name} of the returned entity.

      10.4 Singleton

      Context URL template:

      -
      {context-url}#{singleton}
      -

      If a response or response part is a singleton, its name is the context URL fragment.

      +
      {context-url}#{canonical-singleton}
      +

      If a response or response part is a canonical singleton, the context URL fragment is the {canonical-singleton} without /$entity appended.

      Example 15: resource URL and corresponding context URL

      http://host/service/MainSupplier
 http://host/service/$metadata#MainSupplier
      +
      +

      Example 16: resource URL and corresponding context URL for entity targeted by a single-valued containment navigation property

      +
      http://host/service/Orders(4711)/DeliveryAddress
+http://host/service/$metadata#Orders(4711)/DeliveryAddress
      +

      10.5 Collection of Derived Entities

      Context URL template:

      -
      {context-url}#{entity-set}{/type-name}
      -

      If an entity set consists exclusively of derived entities, a type-cast segment is added to the context URL.

      +
      {context-url}#{canonical-collection}{/type-name}
      +

      If a response or response part is a collection filtered by a type cast segment in the resource URL OData-URL, section 4.11, the type-cast segment is added to the context URL.

      -

      Example 16: resource URL and corresponding context URL

      +

      Example 17: resource URL and corresponding context URL

      http://host/service/Customers/Model.VipCustomer
 http://host/service/$metadata#Customers/Model.VipCustomer
      @@ -1394,28 +1403,34 @@

      10.6 Derived Entity

      Context URL template:

      -
      {context-url}#{entity-set}{/type-name}/$entity
      -

      If a response or response part is a single entity of a type derived from the declared type of an entity set, a type-cast segment is appended to the entity set name.

      +
      {context-url}#{canonical-collection}{/type-name}/$entity
+{context-url}#{canonical-singleton}{/type-name}
      +

      If a response or response part is an entity filtered by a type cast segment in the resource URL OData-URL, section 4.11, the type-cast segment is appended to the {canonical-collection} or {canonical-singleton} and prior to appending /$entity, if any.

      -

      Example 17: resource URL and corresponding context URL

      +

      Example 18: resource URL with key predicate and corresponding context URL

      http://host/service/Customers(2)/Model.VipCustomer
 http://host/service/$metadata#Customers/Model.VipCustomer/$entity
      +
      +

      Example 19: resource URL for singleton and corresponding context URL

      +
      http://host/service/MainSupplier/Model.PreferredVendor
+http://host/service/$metadata#MainSupplier/Model.PreferredVendor
      +

      10.7 Collection of Projected Entities

      Context URL templates:

      -
      {context-url}#{entity-set}{/type-name}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}
 {context-url}#Collection({type-name}){select-list}
      
-
      If a result contains only a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the context URL representing the collection of entities.
      
+
      If a response or response part contains only a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the context URL representing the collection of entities.
      
 
      Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the context URL using path syntax, as defined in OData 4.0.
      
 
      The shortcut * represents the list of all structural properties. Properties defined on types derived from the declared type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in OData-ABNF.
      
 
      The list also contains explicitly selected or expanded instance annotations. It is possible to select or expand only instance annotations, in which case only those selected or expanded annotations appear in the result. Note that annotations specified only in the include-annotations preference do not appear in the context URL and do not affect the selected/expanded properties.
      
 
      Operations in the context URL are represented using the namespace- or alias-qualified name. Function names suffixed with parentheses represent a specific overload, while function names without parentheses represent all overloads of the function.
      
 
      OData 4.01 responses MAY use the shortcut pattern {namespace}.* to represent the list of all bound actions or functions available for entities in the collection, see system query option $select.
      
 
      
-
      Example 18: resource URL and corresponding context URL
      
+
      Example 20: resource URL and corresponding context URL
      
 
      http://host/service/Customers?$select=Address,Orders,Model.VipCustomer/PreferredContact
 http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/PreferredContact)
      
 
      
@@ -1424,17 +1439,17 @@ 
      10.8 Projected Entity
      
 
 
      Context URL templates:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-singleton}{/type-name}{select-list}
 {context-url}#{type-name}{select-list}
      
-
      If a single entity contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the {entity-set} after an optional type-cast segment and prior to appending /$entity. If the response is not a subset of a single entity set, the {select-list} is instead appended to the {type-name} of the returned entity.
      
+
      If a response or response part is an entity that contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the {canonical-collection} or {canonical-singleton} after an optional type-cast segment and prior to appending /$entity, if any.
      
 
      Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the context URL using path syntax, as defined in OData 4.0.
      
 
      The shortcut * represents the list of all structural properties. Properties defined on types derived from the type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in OData-ABNF. Note that expanded properties are automatically included in the response.
      
 
      The list also contains explicitly selected or expanded instance annotations. It is possible to select or expand only instance annotations, in which case only those selected or expanded annotations appear in the result. Note that annotations specified only in the include-annotations preference do not appear in the context URL and do not affect the selected/expanded properties.
      
 
      Operations in the context URL are represented using the namespace- or alias-qualified name. Function names suffixed with parentheses represent a specific overload, while function names without parentheses represent all overloads of the function.
      
 
      OData 4.01 responses MAY use the shortcut pattern {namespace}.* to represent the list of all bound actions or functions available for the returned entity, see system query option $select.
      
 
      
-
      Example 19: resource URL and corresponding context URL
      
+
      Example 21: resource URL and corresponding context URL
      
 
      http://host/service/Customers(1)?$select=Name,Rating
 http://host/service/$metadata#Customers(Name,Rating)/$entity
      
 
      
@@ -1443,7 +1458,7 @@ 
      10
 
      10.9 Collection of Expanded Entities
      
 
 
      Context URL template:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}
 {context-url}#Collection({type-name}){select-list}
      
 
      For a 4.01 response, if a navigation property is explicitly expanded, then in addition to any non-suffixed names of any selected properties, navigation properties, functions or actions, the comma-separated list of properties MUST include the name of the expanded property, suffixed with the parenthesized comma-separated list of any properties of the expanded navigation property that are selected or expanded. If the expanded navigation property does not contain a nested $select or $expand, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (+) is infixed between the navigation property name and the opening parenthesis.
      
 
      For a 4.0 response, the expanded navigation property suffixed with parentheses is omitted from the select-list if it does not contain a nested $select or $expand, but MUST still be present, without a suffix, if it is explicitly selected.
      
@@ -1451,17 +1466,17 @@ 
      
-
      Example 20: resource URL and corresponding context URL — select and expand
      
+
      Example 22: resource URL and corresponding context URL — select and expand
      
 
      http://host/service/Customers?$select=Name&$expand=Address/Country
 http://host/service/$metadata#Customers(Name,Address/Country())
      
 
 
      
-
      Example 21: resource URL and corresponding context URL — expand $ref
      
+
      Example 23: resource URL and corresponding context URL — expand $ref
      
 
      http://host/service/Customers?$expand=Orders/$ref
 http://host/service/$metadata#Customers
      
 
      
 
      
-
      Example 22: resource URL and corresponding context URL — expand with $levels
      
+
      Example 24: resource URL and corresponding context URL — expand with $levels
      
 
      http://host/service/Employees/Sales.Manager?$select=DirectReports
         &$expand=DirectReports($select=FirstName,LastName;$levels=4)
 http://host/service/$metadata
@@ -1472,15 +1487,15 @@ 
      10.10 Expanded Entity
      
 
 
      Context URL template:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-singleton}{/type-name}{select-list}
 {context-url}#{type-name}{select-list}
      
 
      For a 4.01 response, if a navigation property is explicitly expanded, then in addition to the non-suffixed names of any selected properties, navigation properties, functions or actions, the comma-separated list of properties MUST include the name of the expanded property, suffixed with the parenthesized comma-separated list of any properties of the expanded navigation property that are selected or expanded. If the expanded navigation property does not contain a nested $select or $expand, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (+) is infixed between the navigation property name and the opening parenthesis.
      
 
      For a 4.0 response, the expanded navigation property suffixed with parentheses is omitted from the select-list if it does not contain a nested $select or $expand, but MUST still be present, without a suffix, if it is explicitly selected.
      
 
      If the context URL includes only expanded navigation properties (i.e., only navigation properties suffixed with parentheses), then all structural properties are implicitly selected (same as if there were no properties listed in the select-list).
      
 
      Navigation properties with expanded references are not represented in the context URL.
      
 
      
-
      Example 23: resource URL and corresponding context URL
      
+
      Example 25: resource URL and corresponding context URL
      
 
      http://host/service/Employees(1)/Sales.Manager?
         $expand=DirectReports($select=FirstName,LastName;$levels=4)
 http://host/service/$metadata
@@ -1494,7 +1509,7 @@ 
      
-
      Example 24: resource URL and corresponding context URL for a collection of entity references
      
+
      Example 26: resource URL and corresponding context URL for a collection of entity references
      
 
      http://host/service/Customers('ALFKI')/Orders/$ref
 http://host/service/$metadata#Collection($ref)
      
 
      
@@ -1506,7 +1521,7 @@ 
      1
 
      {context-url}#$ref
      
 
      If a response is a single entity reference, $ref is the context URL fragment.
      
 
      
-
      Example 25: resource URL and corresponding context URL for a single entity reference
      
+
      Example 27: resource URL and corresponding context URL for a single entity reference
      
 
      http://host/service/Orders(10643)/Customer/$ref
 http://host/service/$metadata#$ref
      
 
      
@@ -1515,12 +1530,12 @@ 
      1
 
      10.13 Property Value
      
 
 
      Context URL templates:
      
-
      {context-url}#{entity}/{property-path}{select-list}
+
      {context-url}#{canonical-member}/{property-path}{select-list}
 {context-url}#{type-name}{select-list}
      
-
      If a response represents an individual property of an entity with a canonical URL, the context URL specifies the canonical URL of the entity and the path to the structural property of that entity. The path MUST include cast segments for properties defined on types derived from the expected type of the previous segment.
      
+
      If a response represents an individual property of a canonical member, the context URL specifies the {canonical-member} and the path to the structural property. The path MUST include cast segments for properties defined on types derived from the expected type of the previous segment.
      
 
      If the property value does not contain explicitly or implicitly selected navigation properties or operations, OData 4.01 responses MAY use the less specific second template.
      
 
      
-
      Example 26: resource URL and corresponding context URL
      
+
      Example 28: resource URL and corresponding context URL
      
 
      http://host/service/Customers(1)/Addresses
 http://host/service/$metadata#Customers(1)/Addresses
      
 
      
@@ -1530,9 +1545,9 @@ 
      
-
      Example 27: resource URL and corresponding context URL
      
+
      Example 29: resource URL and corresponding context URL
      
 
      http://host/service/TopFiveHobbies()
 http://host/service/$metadata#Collection(Edm.String)
      
 
      
@@ -1542,9 +1557,9 @@ 
      
-
      Example 28: resource URL and corresponding context URL
      
+
      Example 30: resource URL and corresponding context URL
      
 
      http://host/service/MostPopularName()
 http://host/service/$metadata#Edm.String
      
 
@@ -1552,15 +1567,9 @@ 
      10.16 Operation Result
      
 
-
      Context URL templates:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}
-{context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{entity}/{property-path}{select-list}
-{context-url}#Collection({type-name}){select-list}
-{context-url}#{type-name}{select-list}
      
-
      If the response from an action or function is a collection of entities or a single entity that is a member of an entity set, the context URL identifies the entity set. If the response from an action or function is a property of a single entity, the context URL identifies the entity and property. Otherwise, the context URL identifies the type returned by the operation. The context URL will correspond to one of the former examples.
      
+
      The context URL in a response from an action or function has one of the formats described so far (except the service document format). It does not mention the name of the invoked action or function.
      
 
      
-
      Example 29: resource URL and corresponding context URL
      
+
      Example 31: resource URL and corresponding context URL
      
 
      http://host/service/TopFiveCustomers()
 http://host/service/$metadata#Customers
      
 
      
@@ -1569,14 +1578,14 @@ 
      1
 
      10.17 Delta Payload
      
 
 
      Context URL template:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}/$delta
-{context-url}#{entity}{select-list}/$delta
-{context-url}#{entity}/{property-path}{select-list}/$delta
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$delta
+{context-url}#{canonical-member}{select-list}/$delta
+{context-url}#{canonical-member}/{property-path}{select-list}/$delta
 #$delta
      
 
      The context URL of a delta response is the context URL of the response to the defining query, followed by /$delta. This includes singletons, single-valued navigation properties, and collection-valued navigation properties.
      
-
      If the entities are contained, then {entity-set} is the top-level entity set followed by the path to the containment navigation property of the containing entity.
      
+
      If the entities are contained, then {canonical-collection} is the top-level entity set followed by the path to the containment navigation property of the containing entity.
      
 
      
-
      Example 30: resource URL and corresponding context URL
      
+
      Example 32: resource URL and corresponding context URL
      
 
      http://host/service/Customers?$deltatoken=1234
 http://host/service/$metadata#Customers/$delta
      
 
      
@@ -1586,24 +1595,24 @@ 
      10.17 Delt
 
      10.18 Item in a Delta Payload
      
 
 
      Context URL templates:
      
-
      {context-url}#{entity-set}/$deletedEntity
-{context-url}#{entity-set}/$link
-{context-url}#{entity-set}/$deletedLink
      
-
      In addition to new or changed entities which have the canonical context URL for an entity, a delta response can contain deleted entities, new links, and deleted links. They are identified by the corresponding context URL fragment. {entity-set} corresponds to the set of the deleted entity, or source entity for an added or deleted link.
      
+
      {context-url}#{canonical-collection}/$deletedEntity
+{context-url}#{canonical-collection}/$link
+{context-url}#{canonical-collection}/$deletedLink
      
+
      In addition to new or changed entities which have the canonical context URL for an entity, a delta response can contain deleted entities, new links, and deleted links. They are identified by the corresponding context URL fragment. {canonical-collection} corresponds to the set of the deleted entity, or source entity for an added or deleted link.

      10.19 $all Response

      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.

      @@ -1664,7 +1673,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.

      @@ -1707,7 +1716,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.

      @@ -1727,11 +1736,11 @@

      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.

      -

      Example 31:

      +

      Example 33:

      GET http://host/service/Products(1)/Name
      @@ -1743,7 +1752,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.

      @@ -1752,7 +1761,7 @@

      204 No Content response.

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

      -

      Example 32:

      +

      Example 34:

      GET http://host/service/Products(1)/Name/$value

      @@ -1767,27 +1776,27 @@

      actions and functions explicitly requested by the client. The service returns the specified content, if available, along with any available expanded navigation or stream properties, and MAY return additional information.

      The value of the $select query option is a comma-separated list of paths that end with properties, non-entity-valued instance annotations, qualified action names, or qualified function names, as well as of the star operator (*), or the star operator prefixed with the namespace or alias of the schema in order to specify all operations defined in the schema. Only aliases defined in the metadata document of the service can be used in URLs.

      -

      Example 33: request only the Rating and ReleaseDate for the matching Products

      +

      Example 35: request only the Rating and ReleaseDate for the matching Products

      GET http://host/service/Products?$select=Rating,ReleaseDate

      It is also possible to request all structural properties, including any dynamic properties, using the star operator. The star operator SHOULD NOT introduce navigation properties, actions or functions not otherwise requested.

      -

      Example 34:

      +

      Example 36:

      GET http://host/service/Products?$select=*

      Properties of related entities can be specified by including the $select query option within the $expand.

      -

      Example 35:

      +

      Example 37:

      GET http://host/service/Products?$expand=Category($select=Name)

      The properties specified in $select are represented in addition to any expanded navigation or stream properties. If a navigation property is specified in $select, then the corresponding navigation link is represented in the response. If the navigation property also appears in an $expand query option, then it is additionally represented as inline content.

      -

      Example 36: for each category, return the CategoryName and the Products navigation link

      +

      Example 38: for each category, return the CategoryName and the Products navigation link

      GET http://host/service/Categories?$select=CategoryName,Products

      It is also possible to request all actions or functions available for each returned entity.

      -

      Example 37:

      +

      Example 39:

      GET http://host/service/Products?$select=DemoService.*

      Query options can be applied to a selected property by appending a semicolon-separated list of query options, enclosed in parentheses, to the property. Allowed system query options are $select and $compute for complex properties, plus $filter, $search, $count, $orderby, $skip, and $top for collection-valued properties. A property MUST NOT have select options specified in more than one place in a request and MUST NOT have both select options and expand options specified.

      @@ -1801,28 +1810,28 @@

      OData-URL, section 5.1.3.

      -

      Example 38: for each customer entity within the Customers entity set the value of all related Orders will be represented inline

      +

      Example 40: for each customer entity within the Customers entity set the value of all related Orders will be represented inline

      GET http://host/service.svc/Customers?$expand=Orders
      -

      Example 39: for each customer entity within the Customers entity set the references to the related Orders will be represented inline

      +

      Example 41: for each customer entity within the Customers entity set the references to the related Orders will be represented inline

      GET http://host/service.svc/Customers?$expand=Orders/$ref
      -

      Example 40: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline

      +

      Example 42: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline

      GET http://host/service.svc/Customers?$expand=Photo
      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

      +

      Example 43: 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

      GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)
      -

      Example 42: for each order within the Orders entity set, the following will be represented inline:

      +

      Example 44: for each order within the Orders entity set, the following will be represented inline:

      -

      Example 43: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)

      +

      Example 45: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)

      GET http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff
      @@ -1841,7 +1850,7 @@
      -

      Example 44: return each employee from the Employees entity set and, for each employee that is a manager, return all direct reports, recursively to four levels

      +

      Example 46: return each employee from the Employees entity set and, for each employee that is a manager, return all direct reports, recursively to four levels

      GET http://host/service/Employees?$expand=Model.Manager/DirectReports($levels=4)
      @@ -1853,7 +1862,7 @@

      The $compute system query option allows clients to define computed properties that can be used in a $select or within a $filter or $orderby expression.

      Computed properties SHOULD be included as dynamic properties in the result and MUST be included if $select is specified with the computed property name, or star (*).

      -

      Example 45: compute total price for order items (line breaks only for readability)

      +

      Example 47: compute total price for order items (line breaks only for readability)

      GET http://host/service/Customers
    ?$filter=Orders/any(o:o/TotalPrice gt 100)
    &$expand=Orders($compute=Price mult Qty as TotalPrice
@@ -1873,12 +1882,12 @@ 
      
-
      Example 46: return all Products whose Price is less than $10.00
      
+
      Example 48: return all Products whose Price is less than $10.00
      
 
      GET http://host/service/Products?$filter=Price lt 10.00

      The $count segment may be used within a $filter expression to limit the items returned based on the exact count of related entities or items within a collection-valued property.

      -

      Example 47: return all Categories with less than 10 products

      +

      Example 49: return all Categories with less than 10 products

      GET http://host/service/Categories?$filter=Products/$count lt 10

      The value of the $filter option is a Boolean expression as defined in OData-ABNF.

      @@ -1978,7 +1987,7 @@
      function parameters, or within a $compute, $filter or $orderby expression. Parameters aliases are names beginning with an at sign (@).

      Actual parameter values are specified as query options in the query part of the request URL. The query option name is the name of the parameter alias, and the query option value is the value to be used for the specified parameter alias.

      -

      Example 48: returns all employees whose Region property matches the string parameter value WA

      +

      Example 50: returns all employees whose Region property matches the string parameter value WA

      GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'

      Parameter aliases allow the same value to be used multiple times in a request and may be used to reference primitive, structured, or collection values.

      @@ -1986,7 +1995,7 @@
      -

      Example 49: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports

      +

      Example 51: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports

      GET http://host/service.svc/Employees?$expand=Manager(@m=$this;$expand=DirectReports($filter=@m/FirstName eq FirstName))

      @@ -2003,17 +2012,17 @@

      Services SHOULD order language-dependent strings according to the Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.

      Values of type Edm.Stream or any of the Geo types cannot be sorted.

      -

      Example 50: return all Products ordered by release date in ascending order, then by rating in descending order

      +

      Example 52: return all Products ordered by release date in ascending order, then by rating in descending order

      GET http://host/service/Products?$orderby=ReleaseDate asc, Rating desc

      Related entities may be ordered by specifying $orderby within the $expand clause.

      -

      Example 51: return all Categories, and their Products ordered according to release date and in descending order of rating

      +

      Example 53: return all Categories, and their Products ordered according to release date and in descending order of rating

      GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)

      $count may be used within a $orderby expression to order the returned items according to the exact count of related entities or items within a collection-valued property.

      -

      Example 52: return all Categories ordered by the number of Products within each category

      +

      Example 54: return all Categories ordered by the number of Products within each category

      GET http://host/service/Categories?$orderby=Products/$count
      @@ -2024,7 +2033,7 @@

      \(A\) be a copy of the result set with a total order that extends any existing order of the result set but is otherwise chosen by the service. If no unique ordering is imposed through an $orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.

      If \(A\) contains more than \(n\) instances, the result of \({\tt \$top}=n\) consists of the first \(n\) instances in \(A\). Otherwise, the result equals \(A\). The instances in the result are in the same order as they occur in \(A\).

      -

      Example 53: return only the first five products of the Products entity set

      +

      Example 55: return only the first five products of the Products entity set

      GET http://host/service/Products?$top=5
      @@ -2035,12 +2044,12 @@

      \(A\) be a copy of the result set with a total order that extends any existing order of the result set but is otherwise chosen by the service. If no unique ordering is imposed through an $orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.

      If \(A\) contains \(n\) or fewer instances, the result of \({\tt \$skip}=n\) is empty. Otherwise, the first \(n\) instances in \(A\) are omitted from the result and all remaining instances are kept in the same order as they occur in \(A\).

      -

      Example 54: return products starting with the 6th product of the Products entity set

      +

      Example 56: return products starting with the 6th product of the Products entity set

      GET http://host/service/Products?$skip=5

      Where $top and $skip are used together, $skip MUST be applied before $top, regardless of the order in which they appear in the request.

      -

      Example 55: return the third through seventh products of the Products entity set

      +

      Example 57: return the third through seventh products of the Products entity set

      GET http://host/service/Products?$top=5&$skip=2

      If no unique ordering is imposed through an $orderby query option, the service MUST impose a stable ordering across requests that include $skip.

      @@ -2050,12 +2059,12 @@

      -

      Example 56: return, along with the results, the total number of products in the collection

      +

      Example 58: return, along with the results, the total number of products in the collection

      GET http://host/service/Products?$count=true

      The count of related entities can be requested by specifying the $count query option within the $expand clause.

      -

      Example 57:

      +

      Example 59:

      GET http://host/service/Categories?$expand=Products($count=true)

      A $count query option with a value of false (or not specified) hints that the service SHOULD NOT return a count.

      @@ -2068,32 +2077,32 @@

      Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request363
      Section 11.4.3 Services can validate non-updatable property values in update payloads 356
      Section 11.4.4 Upserts to single-valued non-containment navigation properties 455
      Section 11.4.9.3 Setting a complex property to a different type 534
      Section 11.4.13 Semantics of continue-on-error when replacing a collection of entities 358
      Section 12 Allow 400 Bad Request in addition to 501 Not Implemented for unsupported functionality 391
      Section 12.3 Encoding of plus character in URLs 485