Edm.Stream is a primitive type that can be used as a property of an entity type or complex type, the underlying type for a type definition, or the binding parameter or return type of an action or function. Edm.Stream, or a type definition whose underlying type is Edm.Stream, cannot be used in collections or for non-binding parameters to functions or actions.
Some of these types allow facets, defined in section "Type Facets".
See rule primitiveLiteral in OData-ABNF for the representation of primitive type values in URLs and OData-JSON for the representation in requests and responses.
The facets in the following subsections modify or constrain the acceptable values of primitive typed model elements, for example a structural property, action or function parameter, action or function return type, or term.
+For single-valued model elements the facets apply to the value of the model element. For collection-valued model elements the facets apply to the items in the collection.
+A positive integer value specifying the maximum length of a binary, stream or string value. For binary or stream values this is the octet length of the binary data, for string values it is the character length (number of code points for Unicode).
+If no maximum length is specified, clients SHOULD expect arbitrary length.
+$MaxLengthThe 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.
For a decimal value: the maximum number of significant decimal digits of the model element's value; it MUST be a positive integer.
+For a temporal value (datetime-with-timezone-offset, duration, or time-of-day): the number of decimal places allowed in the seconds portion of the value; it MUST be a non-negative integer between zero and twelve.
+Note: service authors SHOULD be aware that some clients are unable to support a precision greater than 28 for decimal values and 7 for temporal values. Client developers MUST be aware of the potential for data loss when round-tripping values of greater precision. Updating via PATCH and exclusively specifying modified values will reduce the risk for unintended data loss.
Note: model elements with duration values and a granularity less than seconds (e.g. minutes, hours, days) can be annotated with term Measures.DurationGranularity, see OData-VocMeasures.
$PrecisionThe value of $Precision is a number.
Absence of $Precision means arbitrary precision.
Example 2: Precision facet applied to the DateTimeOffset type
"SuggestedTimes": {
+ "$Type": "Edm.DateTimeOffset",
+ "$Collection": true,
+ "$Precision": 6
+}A non-negative integer value specifying the maximum number of digits allowed to the right of the decimal point, or one of the symbolic values floating or variable.
The value floating means that the decimal value represents a decimal floating-point number whose number of significant digits is the value of the Precision facet. OData 4.0 responses MUST NOT specify the value floating.
The value variable means that the number of digits to the right of the decimal point can vary from zero to the value of the Precision facet.
An integer value means that the number of digits to the right of the decimal point may vary from zero to the value of the Scale facet, and the number of digits to the left of the decimal point may vary from one to the value of the Precision facet minus the value of the Scale facet. If Precision is equal to Scale, a single zero MUST precede the decimal point.
The value of Scale MUST be less than or equal to the value of Precision.
Note: if the underlying data store allows negative scale, services may use a Precision with the absolute value of the negative scale added to the actual number of significant decimal digits, and client-provided values may have to be rounded before being stored.
$ScaleThe value of $Scale is a number or a string with one of the symbolic values floating or variable.
Services SHOULD use lower-case values; clients SHOULD accept values in a case-insensitive manner.
+Absence of $Scale means variable.
Example 3: Precision=3 and Scale=2.
+Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
"Amount32": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 3,
+ "$Scale": 2
+}Example 4: Precision=2 equals Scale.
+Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
"Amount22": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 2,
+ "$Scale": 2
+}Example 5: Precision=3 and a variable Scale.
+Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed values: 12.34, 1234 and 123.4 due to the limited precision.
"Amount3v": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 3
+}Example 6: Precision=7 and a floating Scale.
+Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values: 1e-102 and 1e97 due to the limited precision.
"Amount7f": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 7,
+ "$Scale": "floating"
+}For a string-typed model element the Unicode facet indicates whether the it might contain and accept string values with Unicode characters (code points) beyond the ASCII character set. The value false indicates that the it will only contain and accept string values with characters limited to the ASCII character set.
If no value is specified, the Unicode facet defaults to true.
$UnicodeThe value of $Unicode is one of the Boolean literals true or false. Absence of the member means true.
For a geometry- or geography-typed model element the SRID facet identifies which spatial reference system is applied to its values.
The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.
The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.
$SRIDThe value of $SRID is a string containing a number or the symbolic value variable.
The following built-in abstract types can be used within a model:
Edm.PrimitiveTypeVocabulary terms can, in addition, use
Edm.AnnotationPathMany parts of the model can be decorated with additional information using annotations. Annotations are identified by their term name and an optional qualifier that allows applying the same term multiple times to the same model element.
A model element MUST NOT specify more than one annotation for a given combination of term and qualifier.
A CSDL JSON document consists of a single JSON object. This document object MUST contain the member $Version.
The document object MAY contain the member $Reference to reference other CSDL documents.
It also MAY contain members for schemas.
If the CSDL JSON document is the metadata document of an OData service, the document object MUST contain the member $EntityContainer.
$Version$VersionThe value of $Version is a string containing either 4.0 or 4.01.
$EntityContainer$EntityContainerThe value of $EntityContainer is the namespace-qualified name of the entity container of that service. This is the only place where a model element MUST be referenced with its namespace-qualified name and use of the alias-qualified name is not allowed.
Example 2:
-{
- "$Version": "4.01",
- "$EntityContainer": "org.example.DemoService",
- ...
-}Example 7:
+{
+ "$Version": "4.01",
+ "$EntityContainer": "org.example.DemoService",
+ ...
+}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.
$Reference$ReferenceThe 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.
The reference object MAY contain the members $Include and $IncludeAnnotations as well as annotations.
Example 3: references to other CSDL documents
-{
- ...
- "$Reference": {
- "http://vocabs.odata.org/capabilities/v1": {
- ...
- },
- "http://vocabs.odata.org/core/v1": {
- ...
- },
- "http://example.org/display/v1": {
- ...
- }
- },
- ...
-}Example 8: references to other CSDL documents
+{
+ ...
+ "$Reference": {
+ "http://vocabs.odata.org/capabilities/v1": {
+ ...
+ },
+ "http://vocabs.odata.org/core/v1": {
+ ...
+ },
+ "http://example.org/display/v1": {
+ ...
+ }
+ },
+ ...
+}A reference MAY include zero or more schemas from the referenced document.
@@ -758,47 +851,47 @@The alias MUST NOT be one of the reserved values Edm, odata, System, or Transient.
An alias is only valid within the document in which it is declared; a referencing document may define its own aliases for included schemas.
$Include$IncludeThe value of $Include is an array. Array items are objects that MUST contain the member $Namespace and MAY contain the member $Alias.
The item objects MAY contain annotations.
-$Namespace$NamespaceThe value of $Namespace is a string containing the namespace of the included schema.
$Alias$AliasThe value of $Alias is a string containing the alias for the included schema.
Example 4: references to entity models containing definitions of vocabulary terms
-{
- ...
- "$Reference": {
- "http://vocabs.odata.org/capabilities/v1": {
- "$Include": [
- {
- "$Namespace": "Org.OData.Capabilities.V1",
- "$Alias": "Capabilities"
- }
- ]
- },
- "http://vocabs.odata.org/core/v1": {
- "$Include": [
- {
- "$Namespace": "Org.OData.Core.V1",
- "$Alias": "Core",
- "@Core.DefaultNamespace": true
- }
- ]
- },
- "http://example.org/display/v1": {
- "$Include": [
- {
- "$Namespace": "org.example.display",
- "$Alias": "UI"
- }
- ]
- }
- },
- ...
-}Example 9: references to entity models containing definitions of vocabulary terms
+{
+ ...
+ "$Reference": {
+ "http://vocabs.odata.org/capabilities/v1": {
+ "$Include": [
+ {
+ "$Namespace": "Org.OData.Capabilities.V1",
+ "$Alias": "Capabilities"
+ }
+ ]
+ },
+ "http://vocabs.odata.org/core/v1": {
+ "$Include": [
+ {
+ "$Namespace": "Org.OData.Core.V1",
+ "$Alias": "Core",
+ "@Core.DefaultNamespace": true
+ }
+ ]
+ },
+ "http://example.org/display/v1": {
+ "$Include": [
+ {
+ "$Namespace": "org.example.display",
+ "$Alias": "UI"
+ }
+ ]
+ }
+ },
+ ...
+}In addition to including whole schemas with all model constructs defined within that schema, a reference may include annotations.
@@ -808,43 +901,43 @@The target namespace also provides consumers insight about what namespaces are present in the referenced document. If the consumer is not interested in that particular target namespace, the consumer can opt not to inspect the referenced document.
$IncludeAnnotations$IncludeAnnotationsThe value of $IncludeAnnotations is an array. Array items are objects that MUST contain the member $TermNamespace and MAY contain the members $Qualifier and $TargetNamespace.
$TermNamespace$TermNamespaceThe value of $TermNamespace is a namespace.
$Qualifier$QualifierThe value of $Qualifier is a simple identifier.
$TargetNamespace$TargetNamespaceThe value of $TargetNamespace is a namespace.
Example 5: reference documents that contain annotations
-{
- ...
- "$Reference": {
- "http://odata.org/ann/b": {
- "$IncludeAnnotations": [
- {
- "$TermNamespace": "org.example.validation"
- },
- {
- "$TermNamespace": "org.example.display",
- "$Qualifier": "Tablet"
- },
- {
- "$TermNamespace": "org.example.hcm",
- "$TargetNamespace": "com.example.Sales"
- },
- {
- "$TermNamespace": "org.example.hcm",
- "$Qualifier": "Tablet",
- "$TargetNamespace": "com.example.Person"
- }
- ]
- }
- },
- ...
-}Example 10: reference documents that contain annotations
+{
+ ...
+ "$Reference": {
+ "http://odata.org/ann/b": {
+ "$IncludeAnnotations": [
+ {
+ "$TermNamespace": "org.example.validation"
+ },
+ {
+ "$TermNamespace": "org.example.display",
+ "$Qualifier": "Tablet"
+ },
+ {
+ "$TermNamespace": "org.example.hcm",
+ "$TargetNamespace": "com.example.Sales"
+ },
+ {
+ "$TermNamespace": "org.example.hcm",
+ "$Qualifier": "Tablet",
+ "$TargetNamespace": "com.example.Person"
+ }
+ ]
+ }
+ },
+ ...
+}The following annotations from http://odata.org/ann/b are included:
Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
The namespace MUST NOT be one of the reserved values Edm, odata, System, or Transient.
A schema is represented as a member of the document object whose name is the schema namespace. Its value is an object that MAY contain the members $Alias and $Annotations.
The schema object MAY contain members representing entity types, complex types, enumeration types, type definitions, actions, functions, terms, and an entity container.
The schema object MAY also contain annotations that apply to the schema itself.
@@ -874,37 +967,37 @@Aliases are document-global, so all schemas defined within or included into a document MUST have different aliases, and aliases MUST differ from the namespaces of all schemas defined within or included into a document. Aliases defined by a schema can be used throughout the containing document and are not restricted to the schema that defines them.
The alias MUST NOT be one of the reserved values Edm, odata, System, or Transient.
$Alias$AliasThe value of $Alias is a string containing the alias for the schema.
Example 6: document defining a schema org.example with an alias and a description for the schema
{
- ...
- "org.example": {
- "$Alias": "self",
- "@Core.Description": "Example schema",
- ...
- },
- ...
-}Example 11: document defining a schema org.example with an alias and a description for the schema
{
+ ...
+ "org.example": {
+ "$Alias": "self",
+ "@Core.Description": "Example schema",
+ ...
+ },
+ ...
+}$Annotations$AnnotationsThe value of $Annotations is an object with one member per annotation target. The member name is a path identifying the annotation target, the member value is an object containing annotations for that target.
Example 7: annotations targeting the Person type with qualifier Tablet
"org.example": {
- "$Alias": "self",
- "$Annotations": {
- "self.Person": {
- "@Core.Description#Tablet": "Dummy",
- ...
- }
- }
-}Example 12: annotations targeting the Person type with qualifier Tablet
"org.example": {
+ "$Alias": "self",
+ "$Annotations": {
+ "self.Person": {
+ "@Core.Description#Tablet": "Dummy",
+ ...
+ }
+ }
+}An entity type can define two types of properties. A structural property is a named reference to a primitive, complex, or enumeration type, or a collection of primitive, complex, or enumeration types. A navigation property is a named reference to another entity type or collection of entity types.
All properties MUST have a unique name within an entity type. Properties MUST NOT have the same name as the declaring entity type. They MAY have the same name as one of the direct or indirect base types or derived types.
An entity type is represented as a member of the schema object whose name is the unqualified name of the entity type and whose value is an object.
The entity type object MUST contain the member $Kind with a string value of EntityType.
It MAY contain the members $BaseType, $Abstract, $OpenType, $HasStream, and $Key.
It also MAY contain members representing structural properties and navigation properties as well as annotations.
Example 8: a simple entity type
-"Employee": {
- "$Kind": "EntityType",
- "$Key": [
- "ID"
- ],
- "ID": {},
- "FirstName": {},
- "LastName": {},
- "Manager": {
- "$Kind": "NavigationProperty",
- "$Nullable": true,
- "$Type": "self.Manager"
- }
-}Example 13: a simple entity type
+"Employee": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "ID"
+ ],
+ "ID": {},
+ "FirstName": {},
+ "LastName": {},
+ "Manager": {
+ "$Kind": "NavigationProperty",
+ "$Nullable": true,
+ "$Type": "self.Manager"
+ }
+}An entity type can inherit from another entity type by specifying it as its base type.
An entity type inherits the key as well as structural and navigation properties of its base type.
An entity type MUST NOT introduce an inheritance cycle by specifying a base type.
$BaseType$BaseTypeThe value of $BaseType is the qualified name of the base type.
Example 9: a derived entity type based on the previous example
-"Manager": {
- "$Kind": "EntityType",
- "$BaseType": "self.Employee",
- "AnnualBudget": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Scale": 0
- },
- "Employees": {
- "$Kind": "NavigationProperty",
- "$Collection": true,
- "$Type": "self.Employee"
- }
-}Example 14: a derived entity type based on the previous example
+"Manager": {
+ "$Kind": "EntityType",
+ "$BaseType": "self.Employee",
+ "AnnualBudget": {
+ "$Nullable": true,
+ "$Type": "Edm.Decimal",
+ "$Scale": 0
+ },
+ "Employees": {
+ "$Kind": "NavigationProperty",
+ "$Collection": true,
+ "$Type": "self.Employee"
+ }
+}Note: the derived type has the same name as one of the properties of its base type.
@@ -969,7 +1062,7 @@An abstract entity type MUST NOT inherit from a non-abstract entity type.
$Abstract$AbstractThe value of $Abstract is one of the Boolean literals true or false. Absence of the member means false.
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.
$OpenType$OpenTypeThe value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.
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.
$HasStream$HasStreamThe value of $HasStream is one of the Boolean literals true or false. Absence of the member means false.
An alias MUST NOT be defined if the key property is a primitive property of the entity type itself.
For key properties that are a property of a complex or navigation property, the alias MUST be used in the key predicate of URLs instead of the path to the property because the required percent-encoding of the forward slash separating segments of the path to the property would make URL construction and parsing rather complicated. The alias MUST NOT be used in the query part of URLs, where paths to properties don't require special encoding and are a standard constituent of expressions anyway.
$Key$KeyThe value of $Key is an array with one item per key property.
Key properties without a key alias are represented as strings containing the property name.
Key properties with a key alias are represented as objects with one member whose name is the key alias and whose value is a string containing the path to the property.
Example 10: entity type with a simple key
-"Category": {
- "$Kind": "EntityType",
- "$Key": [
- "ID"
- ],
- "ID": {
- "$Type": "Edm.Int32"
- },
- "Name": {
- "$Nullable": true,
- "@Core.IsLanguageDependent": true
- }
-}Example 11: entity type with a simple key referencing a property of a complex type
-"Category": {
- "$Kind": "EntityType",
- "$Key": [
- {
- "EntityInfoID": "Info/ID"
- }
- ],
- "Info": {
- "$Type": "self.EntityInfo"
- },
- "Name": {
- "$Nullable": true
- }
-},
-"EntityInfo": {
- "$Kind": "ComplexType",
- "ID": {
- "$Type": "Edm.Int32"
- },
- "Created": {
- "$Type": "Edm.DateTimeOffset",
- "$Precision": 0
- }
-}Example 12: entity type with a composite key
-"OrderLine": {
- "$Kind": "EntityType",
- "$Key": [
- "OrderID",
- "LineNumber"
- ],
- "OrderID": {
- "$Type": "Edm.Int32"
- },
- "LineNumber": {
- "$Type": "Edm.Int32"
- }
-}Example 15: entity type with a simple key
+"Category": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "ID"
+ ],
+ "ID": {
+ "$Type": "Edm.Int32"
+ },
+ "Name": {
+ "$Nullable": true,
+ "@Core.IsLanguageDependent": true
+ }
+}Example 16: entity type with a simple key referencing a property of a complex type
+"Category": {
+ "$Kind": "EntityType",
+ "$Key": [
+ {
+ "EntityInfoID": "Info/ID"
+ }
+ ],
+ "Info": {
+ "$Type": "self.EntityInfo"
+ },
+ "Name": {
+ "$Nullable": true
+ }
+},
+"EntityInfo": {
+ "$Kind": "ComplexType",
+ "ID": {
+ "$Type": "Edm.Int32"
+ },
+ "Created": {
+ "$Type": "Edm.DateTimeOffset",
+ "$Precision": 0
+ }
+}Example 17: entity type with a composite key
+"OrderLine": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "OrderID",
+ "LineNumber"
+ ],
+ "OrderID": {
+ "$Type": "Edm.Int32"
+ },
+ "LineNumber": {
+ "$Type": "Edm.Int32"
+ }
+}Example 13 (based on example 11): requests to an entity set Categories of type Category must use the alias
Example 18 (based on example 16): requests to an entity set Categories of type Category must use the alias
GET http://host/service/Categories(EntityInfoID=1)Example 14 (based on example 11): in a query part the value assigned to the name attribute must be used
+Example 19 (based on example 16): in a query part the value assigned to the name attribute must be used
GET http://example.org/OData.svc/Categories?$filter=Info/ID le 100Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
Structural properties are represented as members of the object representing a structured type. The member name is the property name, the member value is an object.
The property object MAY contain the member $Kind with a string value of Property. This member SHOULD be omitted to reduce document size.
It MAY contain the member $Type, $Collection, $Nullable, $MaxLength, $Unicode, $Precision, $Scale, $SRID, and $DefaultValue.
It MAY contain the members $Type, $Collection, $Nullable, $MaxLength, $Unicode, $Precision, $Scale, $SRID, and $DefaultValue.
It also MAY contain annotations.
Example 15: complex type with two properties Dimension and Length
"Measurement": {
- "$Kind": "ComplexType",
- "Dimension": {
- "$MaxLength": 50,
- "$DefaultValue": "Unspecified"
- },
- "Length": {
- "$Type": "Edm.Decimal",
- "$Precision": 18,
- "$Scale": 2
- }
-}Example 20: complex type with two properties Dimension and Length
"Measurement": {
+ "$Kind": "ComplexType",
+ "Dimension": {
+ "$MaxLength": 50,
+ "$DefaultValue": "Unspecified"
+ },
+ "Length": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 18,
+ "$Scale": 2
+ }
+}The property's type MUST be a primitive type, complex type, or enumeration type in scope, or a collection of one of these types.
A collection-valued property MAY be annotated with the Core.Ordered term, defined in OData-VocCore, to specify that it supports a stable ordering.
A collection-valued property MAY be annotated with the Core.PositionalInsert term, defined in OData-VocCore, to specify that it supports inserting items into a specific ordinal position.
$Type and $Collection$Type and $CollectionFor single-valued properties the value of $Type is the qualified name of the property's type.
For collection-valued properties the value of $Type is the qualified name of the property's item type, and the member $Collection MUST be present with the literal value true.
Absence of the $Type member means the type is Edm.String. This member SHOULD be omitted for string properties to reduce document size.
Example 16: property Units that can have zero or more strings as its value
"Units": {
- "$Collection": true
-}Example 21: property Units that can have zero or more strings as its value
"Units": {
+ "$Collection": true
+}Facets modify or constrain the acceptable values of a property.
-For single-valued properties the facets apply to the value of the property. For collection-valued properties the facets apply to the items in the collection.
-A Boolean value specifying whether the property can have the value null.
$Nullable$NullableThe value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
For single-valued properties the value true means that the property allows the null value.
For collection-valued properties the property 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.
A positive integer value specifying the maximum length of a binary, stream or string value. For binary or stream values this is the octet length of the binary data, for string values it is the character length (number of code points for Unicode).
-If no maximum length is specified, clients SHOULD expect arbitrary length.
-$MaxLengthThe 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.
For a decimal value: the maximum number of significant decimal digits of the property's value; it MUST be a positive integer.
-For a temporal value (datetime-with-timezone-offset, duration, or time-of-day): the number of decimal places allowed in the seconds portion of the value; it MUST be a non-negative integer between zero and twelve.
-Note: service authors SHOULD be aware that some clients are unable to support a precision greater than 28 for decimal properties and 7 for temporal properties. Client developers MUST be aware of the potential for data loss when round-tripping values of greater precision. Updating via PATCH and exclusively specifying modified properties will reduce the risk for unintended data loss.
Note: duration properties supporting a granularity less than seconds (e.g. minutes, hours, days) can be annotated with term Measures.DurationGranularity, see OData-VocMeasures.
$PrecisionThe value of $Precision is a number.
Absence of $Precision means arbitrary precision.
Example 17: Precision facet applied to the DateTimeOffset type
"SuggestedTimes": {
- "$Type": "Edm.DateTimeOffset",
- "$Collection": true,
- "$Precision": 6
-}A non-negative integer value specifying the maximum number of digits allowed to the right of the decimal point, or one of the symbolic values floating or variable.
The value floating means that the decimal property represents a decimal floating-point number whose number of significant digits is the value of the Precision facet. OData 4.0 responses MUST NOT specify the value floating.
The value variable means that the number of digits to the right of the decimal point can vary from zero to the value of the Precision facet.
An integer value means that the number of digits to the right of the decimal point may vary from zero to the value of the Scale facet, and the number of digits to the left of the decimal point may vary from one to the value of the Precision facet minus the value of the Scale facet. If Precision is equal to Scale, a single zero MUST precede the decimal point.
The value of Scale MUST be less than or equal to the value of Precision.
Note: if the underlying data store allows negative scale, services may use a Precision with the absolute value of the negative scale added to the actual number of significant decimal digits, and client-provided values may have to be rounded before being stored.
$ScaleThe value of $Scale is a number or a string with one of the symbolic values floating or variable.
Services SHOULD use lower-case values; clients SHOULD accept values in a case-insensitive manner.
-Absence of $Scale means variable.
For collection-valued properties the 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.
Example 18: Precision=3 and Scale=2.
-Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
"Amount32": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 3,
- "$Scale": 2
-}Example 19: Precision=2 equals Scale.
-Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
"Amount22": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 2,
- "$Scale": 2
-}Example 20: Precision=3 and a variable Scale.
-Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed values: 12.34, 1234 and 123.4 due to the limited precision.
"Amount3v": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 3
-}Example 21: Precision=7 and a floating Scale.
-Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values: 1e-102 and 1e97 due to the limited precision.
"Amount7f": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 7,
- "$Scale": "floating"
-}For a string property the Unicode facet indicates whether the property might contain and accept string values with Unicode characters (code points) beyond the ASCII character set. The value false indicates that the property will only contain and accept string values with characters limited to the ASCII character set.
If no value is specified, the Unicode facet defaults to true.
$UnicodeThe value of $Unicode is one of the Boolean literals true or false. Absence of the member means true.
For a geometry or geography property the SRID facet identifies which spatial reference system is applied to values of the property on type instances.
The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.
The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.
$SRIDThe value of $SRID is a string containing a number or the symbolic value variable.
A primitive or enumeration property MAY define a default value that is used if the property is not explicitly represented in an annotation or the body of a request or response.
+A primitive- or enumeration-typed property MAY define a default value that is used if the property is not explicitly represented in an annotation or the body of a request or response.
If no value is specified, the client SHOULD NOT assume a default value.
$DefaultValue$DefaultValueThe 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.
Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
$ReferentialConstraint$ReferentialConstraintThe value of $ReferentialConstraint is an object with one member per referential constraint. The member name is the path to the dependent property, this path is relative to the structured type declaring the navigation property. The member value is a string containing the path to the principal property, this path is relative to the entity type that is the target of the navigation property.
It also MAY contain annotations. These are prefixed with the path of the dependent property of the annotated referential constraint.
@@ -1391,7 +1388,7 @@If no on-delete action is specified, the action taken by the service is not predictable by the client and could vary per entity.
$OnDelete$OnDeleteThe value of $OnDelete is a string with one of the values Cascade, None, SetNull, or SetDefault.
Annotations for $OnDelete are prefixed with $OnDelete.
A complex type can define two types of properties. A structural property is a named reference to a primitive, complex, or enumeration type, or a collection of primitive, complex, or enumeration types. A navigation property is a named reference to an entity type or a collection of entity types.
All properties MUST have a unique name within a complex type. Properties MUST NOT have the same name as the declaring complex type. They MAY have the same name as one of the direct or indirect base types or derived types.
A complex type is represented as a member of the schema object whose name is the unqualified name of the complex type and whose value is an object.
The complex type object MUST contain the member $Kind with a string value of ComplexType. It MAY contain the members $BaseType, $Abstract, and $OpenType. It also MAY contain members representing structural properties and navigation properties as well as annotations.
$BaseType$BaseTypeThe value of $BaseType is the qualified name of the base type.
A complex type MAY indicate that it is abstract and cannot have instances.
$Abstract$AbstractThe value of $Abstract is one of the Boolean literals true or false. Absence of the member means false.
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.
$OpenType$OpenTypeThe value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.
Although enumeration types have an underlying numeric value, the preferred representation for an enumeration value is the member name. Discrete sets of numeric values should be represented as numeric values annotated with the AllowedValues annotation defined in OData-VocCore.
Enumeration types marked as flags allow values that consist of more than one enumeration member at a time.
An enumeration type is represented as a member of the schema object whose name is the unqualified name of the enumeration type and whose value is an object.
The enumeration type object MUST contain the member $Kind with a string value of EnumType.
It MAY contain the members $UnderlyingType and $IsFlags.
$UnderlyingType$UnderlyingTypeThe value of $UnderlyingType is the qualified name of the underlying type.
An enumeration type MAY indicate that the enumeration type allows multiple members to be selected simultaneously.
If not explicitly specified, only one enumeration type member MAY be selected simultaneously.
$IsFlags$IsFlagsThe value of $IsFlags is one of the Boolean literals true or false. Absence of the member means false.
Enumeration type members are represented as JSON object members, where the object member name is the enumeration member name and the object member value is the enumeration member value.
For members of flags enumeration types a combined enumeration member value is equivalent to the bitwise OR of the discrete values.
Annotations for enumeration members are prefixed with the enumeration member name.
@@ -1573,7 +1570,7 @@Type definitions can be used wherever a primitive type is used (other than as the underlying type in a new type definition) and are type-comparable with their underlying types and any type definitions defined using the same underlying type.
It is up to the definition of a term to specify whether and how annotations with this term propagate to places where the annotated type definition is used, and whether they can be overridden.
A type definition is represented as a member of the schema object whose name is the unqualified name of the type definition and whose value is an object.
The type definition object MUST contain the member $Kind with a string value of TypeDefinition and the member $UnderlyingType. It MAY contain the members $MaxLength, $Unicode, $Precision, $Scale, and $SRID, and it MAY contain annotations.
The underlying type of a type definition MUST be a primitive type that MUST NOT be another type definition.
$UnderlyingType$UnderlyingTypeThe value of $UnderlyingType is the qualified name of the underlying type.
The type definition MAY specify facets applicable to the underlying type. Possible facets are: $MaxLength, $Unicode, $Precision, $Scale, or $SRID.
Unbound actions do not support overloads. The names of all unbound actions MUST be unique within a schema.
An unbound action MAY have the same name as a bound action.
An action is represented as a member of the schema object whose name is the unqualified name of the action and whose value is an array. The array contains one object per action overload.
The action overload object MUST contain the member $Kind with a string value of Action.
It MAY contain the members $IsBound, $EntitySetPath, $Parameter, and $ReturnType, and it MAY contain annotations.
A function is represented as a member of the schema object whose name is the unqualified name of the function and whose value is an array. The array contains one object per function overload.
The function overload object MUST contain the member $Kind with a string value of Function.
It MUST contain the member $ReturnType, and it MAY contain the members $IsBound, $EntitySetPath, and $Parameter, and it MAY contain annotations.
An action or function overload MAY indicate that it is bound. If not explicitly indicated, it is unbound.
-Bound actions or functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and it MAY be nullable.
+Bound actions or functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and it MAY be nullable.
Unbound actions are invoked from the entity container through an action import.
Unbound functions are invoked as static functions within a common expression (see OData-URL, section 5.1.1), or from the entity container through a function import.
$IsBound$IsBoundThe value of $IsBound is one of the Boolean literals true or false. Absence of the member means false.
The first segment of the entity set path MUST be the name of the binding parameter. The remaining segments of the entity set path MUST represent navigation segments or type casts.
A navigation segment names the simple identifier of the navigation property to be traversed. A type-cast segment names the qualified name of the entity type that should be returned from the type cast.
$EntitySetPath$EntitySetPathThe value of $EntitySetPath is a string containing the entity set path.
A function MAY indicate that it is composable. If not explicitly indicated, it is not composable.
A composable function can be invoked with additional path segments or key predicates appended to the resource path that identifies the composable function, and with system query options as appropriate for the type returned by the composable function.
$IsComposable$IsComposableThe value of $IsComposable is one of the Boolean literals true or false. Absence of the member means false.
The return type of an action or function overload MAY be any type in scope, or a collection of any type in scope.
-The facets Nullable, MaxLength, Precision, Scale, and SRID can be used as appropriate to specify value restrictions of the return type, as well as the Unicode facet for 4.01 and greater payloads.
The facets MaxLength, Precision, Scale, and SRID can be used as appropriate to specify value restrictions of the return type, as well as the Unicode facet for 4.01 and greater payloads.
For a single-valued return type the facets apply to the returned value. For a collection-valued return type the facets apply to the items in the returned collection.
$ReturnType$ReturnTypeThe value of $ReturnType is an object. It MAY contain the members $Type, $Collection, $Nullable, $MaxLength, $Unicode, $Precision, $Scale, and $SRID.
It also MAY contain annotations.
-$Type and $Collection$Type and $CollectionFor single-valued return types the value of $Type is the qualified name of the returned type.
For collection-valued return types the value of $Type is the qualified name of the returned item type, and the member $Collection MUST be present with the literal value true.
Absence of the $Type member means the type is Edm.String.
$Nullable$NullableThe 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.
The facets MaxLength, Precision, Scale, or SRID can be used as appropriate to specify value restrictions of the parameter, as well as the Unicode facet for 4.01 and greater payloads.
For single-valued parameters the facets apply to the parameter value. If the parameter value is a collection, the facets apply to the items in the collection.
$Parameter$ParameterThe value of $Parameter is an array. The array contains one object per parameter.
A parameter object MUST contain the member $Name, and it MAY contain the members $Type, $Collection, $Nullable, $MaxLength, $Unicode, $Precision, $Scale, and $SRID.
Parameter objects MAY also contain annotations.
-$Name$NameThe value of $Name is a string containing the parameter name.
$Type and $Collection$Type and $CollectionFor single-valued parameters the value of $Type is the qualified name of the accepted type.
For collection-valued parameters the value of $Type is the qualified name of the accepted item type, and the member $Collection MUST be present with the literal value true.
Absence of the $Type member means the type is Edm.String.
$Nullable$NullableThe value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
For single-valued parameters the value true means that the parameter accepts a null value.
For collection-valued parameters the parameter 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.
A singleton allows addressing a single entity directly from the entity container without having to know its key, and without requiring an entity set.
A function import or an action import is used to expose a function or action defined in an entity model as a top level resource.
An entity container is represented as a member of the schema object whose name is the unqualified name of the entity container and whose value is an object.
The entity container object MUST contain the member $Kind with a string value of EntityContainer.
The entity container object MAY contain the member $Extends, members representing entity sets, singletons, action imports, and function imports, as well as annotations.
Note: services should not introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.
$Extends$ExtendsThe value of $Extends is the qualified name of the entity container to be extended.
Entity sets that cannot be queried without specifying additional query options SHOULD NOT be included in the service document.
An entity set is represented as a member of the entity container object whose name is the name of the entity set and whose value is an object.
The entity set object MUST contain the members $Collection and $Type.
It MAY contain the members $IncludeInServiceDocument and $NavigationPropertyBinding as well as annotations.
$Collection$CollectionThe value of $Collection is the Booelan value true.
$Type$TypeThe value of $Type is the qualified name of an entity type.
$IncludeInServiceDocument$IncludeInServiceDocumentThe value of $IncludeInServiceDocument is one of the Boolean literals true or false. Absence of the member means true.
A singleton MUST specify a type that MUST be an entity type in scope.
A singleton MUST reference an instance its entity type.
A singleton is represented as a member of the entity container object whose name is the name of the singleton and whose value is an object.
The singleton object MUST contain the member $Type and it MAY contain the member $Nullable.
It MAY contain the member $NavigationPropertyBinding as well as annotations.
$Type$TypeThe value of $Type is the qualified name of an entity type.
$Nullable$NullableThe value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.In OData 4.0 responses this member MUST NOT be specified.
If the target is a simple identifier, it MUST resolve to an entity set or singleton defined in the same entity container.
If the target is a target path, it MUST resolve to an entity set, singleton, or direct or indirect containment navigation property of a singleton in scope. The path can traverse single-valued containment navigation properties or single-valued complex properties before ending in a containment navigation property, and there MUST NOT be any non-containment navigation properties prior to the final segment.
An action import MUST specify the name of an unbound action in scope.
If the imported action returns an entity or a collection of entities, a simple identifier or target path value MAY be specified to identify the entity set that contains the returned entities. If a simple identifier is specified, it MUST resolve to an entity set defined in the same entity container. If a target path is specified, it MUST resolve to an entity set in scope.
An action import is represented as a member of the entity container object whose name is the name of the action import and whose value is an object.
The action import object MUST contain the member $Action.
It MAY contain the member $EntitySet.
It MAY also contain annotations.
-$Action$ActionThe value of $Action is a string containing the qualified name of an unbound action.
$EntitySet$EntitySetThe value of $EntitySet is a string containing either the unqualified name of an entity set in the same entity container or a path to an entity set in a different entity container.
If the imported function returns an entity or a collection of entities, a simple identifier or target path value MAY be specified to identify the entity set that contains the returned entities. If a simple identifier is specified, it MUST resolve to an entity set defined in the same entity container. If a target path is specified, it MUST resolve to an entity set in scope.
A function import for a parameterless function MAY indicate whether it is included in the service document. If not explicitly indicated, it is not included.
A function import is represented as a member of the entity container object whose name is the name of the function import and whose value is an object.
The function import object MUST contain the member $Function.
It MAY contain the members $EntitySet and $IncludeInServiceDocument.
It MAY also contain annotations.
-$Function$FunctionThe value of $Function is a string containing the qualified name of an unbound function.
$EntitySet$EntitySetThe value of $EntitySet is a string containing either the unqualified name of an entity set in the same entity container or a path to an entity set in a different entity container.
$IncludeInServiceDocument$IncludeInServiceDocumentThe value of $IncludeInServiceDocument is one of the Boolean literals true or false. Absence of the member means false.
The term's name is a simple identifier that MUST be unique within its schema.
The term's type MUST be a type in scope, or a collection of a type in scope.
A term is represented as a member of the schema object whose name is the unqualified name of the term and whose value is an object.
The term object MUST contain the member $Kind with a string value of Term.
It MAY contain the members $Type, $Collection, $AppliesTo, $Nullable, $MaxLength, $Precision, $Scale, $SRID, and $DefaultValue, as well as $Unicode for 4.01 and greater payloads.
It MAY contain the members $Type, $Collection, $Nullable, $DefaultValue, $BaseTerm, $AppliesTo, $MaxLength, $Precision, $Scale, and $SRID, as well as $Unicode for 4.01 and greater payloads.
It MAY contain annotations.
-$Type and $Collection$Type and $CollectionFor single-valued terms the value of $Type is the qualified name of the term's type.
For collection-valued terms the value of $Type is the qualified name of the term's item type, and the member $Collection MUST be present with the literal value true.
Absence of the $Type member means the type is Edm.String.
$DefaultValue$NullableThe value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
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.
$DefaultValueThe 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.
When applying a specialized term, the base term MUST also be applied with the same qualifier, and so on until a term without a base term is reached.
$BaseTerm$BaseTermThe value of $BaseTerm is the qualified name of the base term.
$AppliesTo$AppliesToThe value of $AppliesTo is an array whose items are strings containing symbolic values from the table above that identify model elements the term is intended to be applied to.
An annotation applies a term to a model element and defines how to calculate a value for the term application. Both term and model element MUST be in scope. Section 14.1.2 specifies which model elements MAY be annotated with a term.
The value of an annotation is specified as an annotation expression, which is either a constant expression representing a constant value, or a dynamic expression. The most common construct for assigning an annotation value is a path expression that refers to a property of the same or a related structured type.
An annotation is represented as a member whose name consists of an at (@) character, followed by the qualified name of a term, optionally followed by a hash (#) and a qualifier.
The value of the annotation MUST be a constant expression or dynamic expression.
The annotation can be a member of the object representing the model element it annotates, or a second-level member of the $Annotations member of a schema object.
The value path expression allows assigning a value by traversing an object graph. It can be used in annotations that target entity containers, entity sets, entity types, complex types, navigation properties of structured types, and structural properties of structured types. Its argument is an instance path.
The value of the path expression is the instance or collection of instances identified by the path.
$Path$PathPath expressions are represented as an object with a single member $Path whose value is a string containing a path.
The other comparison operators require two operand expressions that evaluate to comparable values.
$And and $Or$And and $OrThe And and Or logical expressions are represented as an object with a single member whose value is an array with two annotation expressions. The member name is one of $And, or $Or.
It MAY contain annotations.
-$Not$NotNegation expressions are represented as an object with a single member $Not whose value is an annotation expression.
It MAY contain annotations.
-$Eq, $Ne, $Gt, $Ge, $Lt, $Le, $Has, and $In$Eq, $Ne, $Gt, $Ge, $Lt, $Le, $Has, and $InAll comparison expressions are represented as an object with a single member whose value is an array with two annotation expressions. The member name is one of $Eq, $Ne, $Gt, $Ge, $Lt, $Le, $Has, or $In.
They MAY contain annotations.
$Neg$NegNegation expressions are represented as an object with a single member $Neg whose value is an annotation expression.
It MAY contain annotations.
-$Add, $Sub, $Mul, $Div, $DivBy, and $Mod$Add, $Sub, $Mul, $Div, $DivBy, and $ModThese arithmetic expressions are represented as an object with as single member whose value is an array with two annotation expressions. The member name is one of $Add, $Sub, $Neg, $Mul, $Div, $DivBy, or $Mod.
They MAY contain annotations.
The apply expression enables a value to be obtained by applying a client-side function. The apply expression MAY have operand expressions. The operand expressions are used as parameters to the client-side function.
$Apply$ApplyApply expressions are represented as an object with a member $Apply whose value is an array of annotation expressions, and a member $Function whose value is a string containing the qualified name of the client-side function to be applied.
It MAY contain annotations.
odata.fillUriTemplateThe odata.fillUriTemplate client-side function takes two or more expressions as arguments and returns a value of type Edm.String.
The odata.fillUriTemplate client-side function takes two or more expressions as arguments and returns a value of type Edm.String.
The first argument MUST be of type Edm.String and specifies a URI template according to RFC6570, the other arguments MUST be labeled element expressions. Each labeled element expression specifies the template parameter name as its name and evaluates to the template parameter value.
RFC6570 defines three kinds of template parameters: simple values, lists of values, and key-value maps.
Simple values are represented as labeled element expressions that evaluate to a single primitive value. The literal representation of this value according to OData-ABNF is used to fill the corresponding template parameter.
@@ -3072,7 +3073,7 @@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.
$Cast$CastCast 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.
It MAY contain annotations.
If the specified type is a primitive type or a collection of primitive types, the facet members $MaxLength, $Unicode, $Precision, $Scale, and $SRID MAY be specified if applicable to the specified primitive type. If the facet members are not specified, their values are considered unspecified.
The second and third child expressions are evaluated conditionally. The result MUST be type compatible with the type expected by the surrounding expression.
If the first expression evaluates to true, the second expression MUST be evaluated and its value MUST be returned as the result of the if-then-else expression. If the first expression evaluates to false and a third child element is present, it MUST be evaluated and its value MUST be returned as the result of the if-then-else expression. If no third expression is present, nothing is added to the surrounding collection.
$If$IfConditional expressions are represented as an object with a member $If whose value is an array of two or three annotation expressions.
It MAY contain annotations.
$IfThe is-of expression checks whether the value obtained from its single child expression is compatible with the specified type. It returns true if the child expression returns a type that is compatible with the specified type, and false otherwise.
$IsOf$IsOfIs-of expressions are represented as an object with a member $IsOf whose value is an annotation expression, a member $Type whose value is a string containing an qualified type name, and optionally a member $Collection with a value of true.
It MAY contain annotations.
If the specified type is a primitive type or a collection of primitive types, the facet members $MaxLength, $Unicode, $Precision, $Scale, and $SRID MAY be specified if applicable to the specified primitive type. If the facet members are not specified, their values are considered unspecified.
A labeled element expression MUST contain exactly one child expression. The value of the child expression is also the value of the labeled element expression.
A labeled element expression MUST provide a simple identifier value as its name that MUST be unique within the schema containing the expression.
$LabeledElement$LabeledElementLabeled element expressions are represented as an object with a member $LabeledElement whose value is an annotation expression, and a member $Name whose value is a string containing the labeled element's name.
It MAY contain annotations.
$LabeledEle
14.4.10 Labeled Element Reference
The labeled element reference expression MUST specify the qualified name of a labeled element expression in scope and returns the value of the identified labeled element expression as its value.
- $LabeledElementReference
+ $LabeledElementReference
Labeled element reference expressions are represented as an object with a member $LabeledElementReference whose value is a string containing an qualified name.
@@ -3178,7 +3179,7 @@ 14.4.11 Null
"@UI.DisplayName": null,
- $Null
+ $Null
Null expression containing annotations are represented as an object with a member $Null whose value is the literal null.
@@ -3199,7 +3200,7 @@ 14.4.12 Record
It MAY contain annotations for itself and its members. Annotations for record members are prefixed with the member name.
-Example 87: this annotation "morphs" the entity type from example 8 into a structured type with two structural properties GivenName and Surname and two navigation properties DirectSupervisor and CostCenter. The first three properties simply rename properties of the annotated entity type, the fourth adds a calculated navigation property that is pointing to a different service
+Example 87: this annotation "morphs" the entity type from example 13 into a structured type with two structural properties GivenName and Surname and two navigation properties DirectSupervisor and CostCenter. The first three properties simply rename properties of the annotated entity type, the fourth adds a calculated navigation property that is pointing to a different service
"@person.Employee": {
"@type": "https://example.org/vocabs/person#org.example.person.Manager",
"@Core.Description": "Annotation on record",
@@ -3234,7 +3235,7 @@ 14.4.13
The URL reference expression MUST contain exactly one expression of type Edm.String. Its value is treated as a URL that MAY be relative or absolute; relative URLs are relative to the URL of the document containing the URL reference expression, or relative to a base URL specified in a format-specific way.
The response body of the GET request MUST be returned as the result of the URL reference expression. The result of the URL reference expression MUST be type compatible with the type expected by the surrounding expression.
- $UrlRef
+ $UrlRef
URL reference expressions are represented as an object with a single member $UrlRef whose value is an annotation expression.
It MAY contain annotations.
@@ -3652,156 +3653,160 @@ [OpenUI5]
Appendix B. Table of JSON Objects and Members
-- Document Object
+
- Type Facet Members
-- Reference Object
-
-- Schema Object
+
- Document Object
-- Entity Type Object
+
- Reference Object
+
+- Schema Object
-- Property Object
-
-$Type$Collection$Nullable$MaxLength$Precision$Scale$Unicode$SRID$DefaultValue- Entity Type Object
+
-- Navigation Property Object
+
- Property Object
-- Complex Type Object
-
-$BaseType$Abstract$OpenType- Navigation Property Object
+
-- Enumeration Type Object
+
- Complex Type Object
-- Enumeration Member Object
-- Type Definition Object
+
- Enumeration Type Object
-- Action Overload Object
-- Function Overload Object
-
-- Parameter Object
+
- Enumeration Member Object
+- Type Definition Object
+- Action Overload Object
+- Function Overload Object
+
-- Entity Container Object
+
- Parameter Object
-- Entity Set Object
+
- Entity Container Object
-- Singleton Object
+
- Entity Set Object
-- Action Import Object
+
- Singleton Object
-- Function Import Object
+
- Action Import Object
-- Term Object
+
- Function Import Object
+- Term Object
+
-- Annotation Member
-
diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md
index 19eafa7cc..c3c0540a2 100644
--- a/docs/odata-csdl-json/odata-csdl-json.md
+++ b/docs/odata-csdl-json/odata-csdl-json.md
@@ -113,9 +113,15 @@ For complete copyright information please see the full Notices section in an App
- [3.1 Nominal Types](#NominalTypes)
- [3.2 Structured Types](#StructuredTypes)
- [3.3 Primitive Types](#PrimitiveTypes)
- - [3.4 Built-In Abstract Types](#BuiltInAbstractTypes)
- - [3.5 Built-In Types for defining Vocabulary Terms](#BuiltInTypesfordefiningVocabularyTerms)
- - [3.6 Annotations](#Annotations)
+ - [3.4 Type Facets](#TypeFacets)
+ - [3.4.1 MaxLength](#MaxLength)
+ - [3.4.2 Precision](#Precision)
+ - [3.4.3 Scale](#Scale)
+ - [3.4.4 Unicode](#Unicode)
+ - [3.4.5 SRID](#SRID)
+ - [3.5 Built-In Abstract Types](#BuiltInAbstractTypes)
+ - [3.6 Built-In Types for defining Vocabulary Terms](#BuiltInTypesfordefiningVocabularyTerms)
+ - [3.7 Annotations](#Annotations)
- [4 CSDL JSON Document](#CSDLJSONDocument)
- [4.1 Reference](#Reference)
- [4.2 Included Schema](#IncludedSchema)
@@ -131,14 +137,8 @@ For complete copyright information please see the full Notices section in an App
- [6.5 Key](#Key)
- [7 Structural Property](#StructuralProperty)
- [7.1 Type](#Type)
- - [7.2 Type Facets](#TypeFacets)
- - [7.2.1 Nullable](#Nullable)
- - [7.2.2 MaxLength](#MaxLength)
- - [7.2.3 Precision](#Precision)
- - [7.2.4 Scale](#Scale)
- - [7.2.5 Unicode](#Unicode)
- - [7.2.6 SRID](#SRID)
- - [7.2.7 Default Value](#DefaultValue)
+ - [7.2 Nullable](#Nullable)
+ - [7.3 Default Value](#DefaultValue)
- [8 Navigation Property](#NavigationProperty)
- [8.1 Navigation Property Type](#NavigationPropertyType)
- [8.2 Nullable Navigation Property](#NullableNavigationProperty)
@@ -618,7 +618,218 @@ representation of primitive type values in URLs and
[OData-JSON](#ODataJSON) for the representation in requests and
responses.
-## 3.4 Built-In Abstract Types
+## 3.4 Type Facets
+
+The facets in the following subsections modify or constrain the acceptable values of primitive typed model elements,
+for example a [structural property](#StructuralProperty),
+action or function [parameter](#Parameter), action or function [return type](#ReturnType), or [term](#Term).
+
+For single-valued model elements the facets apply to the value of the
+model element. For collection-valued model elements the facets apply to the items
+in the collection.
+
+### 3.4.1 MaxLength
+
+A positive integer value specifying the maximum length of a binary,
+stream or string value. For binary or stream values this is the octet
+length of the binary data, for string values it is the character length
+(number of code points for Unicode).
+
+If no maximum length is specified, clients SHOULD expect arbitrary
+length.
+
+::: {.varjson .rep}
+### Type Facet Members
+### `$MaxLength`
+
+The value of `$MaxLength` is a positive integer.
+
+Note: [OData-CSDL-XML](#ODataCSDL) 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.
+:::
+
+
+### 3.4.2 Precision
+
+For a decimal value: the maximum number of significant decimal digits of
+the model element's value; it MUST be a positive integer.
+
+For a temporal value (datetime-with-timezone-offset, duration, or
+time-of-day): the number of decimal places allowed in the seconds
+portion of the value; it MUST be a non-negative integer between zero and
+twelve.
+
+Note: service authors SHOULD be aware that some clients are unable to
+support a precision greater than 28 for decimal values and 7 for
+temporal values. Client developers MUST be aware of the potential
+for data loss when round-tripping values of greater precision. Updating
+via `PATCH` and exclusively specifying modified values will reduce
+the risk for unintended data loss.
+
+Note: model elements with duration values and a granularity less than seconds
+(e.g. minutes, hours, days) can be annotated with term
+[`Measures.DurationGranularity`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Measures.V1.md#DurationGranularity),
+see [OData-VocMeasures](#ODataVocMeasures).
+
+::: {.varjson .rep}
+### `$Precision`
+
+The value of `$Precision` is a number.
+
+Absence of `$Precision` means arbitrary precision.
+:::
+
+::: {.varjson .example}
+Example 2: `Precision` facet applied to the `DateTimeOffset` type
+```json
+"SuggestedTimes": {
+ "$Type": "Edm.DateTimeOffset",
+ "$Collection": true,
+ "$Precision": 6
+}
+```
+:::
+
+
+
+### 3.4.3 Scale
+
+A non-negative integer value specifying the maximum number of digits
+allowed to the right of the decimal point, or one of the symbolic values
+`floating` or `variable`.
+
+The value `floating` means that the decimal value represents a
+decimal floating-point number whose number of significant digits is the
+value of the [`Precision`](#Precision) facet. OData 4.0 responses MUST
+NOT specify the value `floating`.
+
+The value `variable` means that the number of digits to the right of the
+decimal point can vary from zero to the value of the
+[`Precision`](#Precision) facet.
+
+An integer value means that the number of digits to the right of the
+decimal point may vary from zero to the value of the `Scale` facet, and
+the number of digits to the left of the decimal point may vary from one
+to the value of the `Precision` facet minus the value of the `Scale`
+facet. If `Precision` is equal to `Scale`, a single zero MUST precede
+the decimal point.
+
+The value of `Scale` MUST be less than or equal to the value of
+[`Precision`](#Precision).
+
+Note: if the underlying data store allows negative scale, services may
+use a [`Precision`](#Precision) with the absolute value of the negative
+scale added to the actual number of significant decimal digits, and
+client-provided values may have to be rounded before being stored.
+
+::: {.varjson .rep}
+### `$Scale`
+
+The value of `$Scale` is a number or a string with one of the symbolic
+values `floating` or `variable`.
+
+Services SHOULD use lower-case values; clients SHOULD accept values in a
+case-insensitive manner.
+
+Absence of `$Scale` means `variable`.
+:::
+
+::: {.varjson .example}
+Example 3: [`Precision`](#Precision)`=3` and `Scale=2`.
+Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
+```json
+"Amount32": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 3,
+ "$Scale": 2
+}
+```
+:::
+
+::: {.varjson .example}
+Example 4: `Precision=2` equals `Scale`.
+Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
+```json
+"Amount22": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 2,
+ "$Scale": 2
+}
+```
+:::
+
+::: {.varjson .example}
+Example 5: `Precision=3` and a variable `Scale`.
+Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed
+values: 12.34, 1234 and 123.4 due to the limited precision.
+```json
+"Amount3v": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 3
+}
+```
+:::
+
+::: {.varjson .example}
+Example 6: `Precision=7` and a floating `Scale`.
+Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values:
+1e-102 and 1e97 due to the limited precision.
+```json
+"Amount7f": {
+ "$Type": "Edm.Decimal",
+ "$Precision": 7,
+ "$Scale": "floating"
+}
+```
+:::
+
+
+
+
+
+
+### 3.4.4 Unicode
+
+For a string-typed model element the `Unicode` facet indicates whether the it
+might contain and accept string values with Unicode characters (code
+points) beyond the ASCII character set. The value `false` indicates that
+the it will only contain and accept string values with characters
+limited to the ASCII character set.
+
+If no value is specified, the `Unicode` facet defaults to `true`.
+
+::: {.varjson .rep}
+### `$Unicode`
+
+The value of `$Unicode` is one of the Boolean literals `true` or
+`false`. Absence of the member means `true`.
+:::
+
+
+### 3.4.5 SRID
+
+For a geometry- or geography-typed model element the `SRID` facet identifies which
+spatial reference system is applied to its values.
+
+The value of the `SRID` facet MUST be a non-negative integer or the
+special value `variable`. If no value is specified, the facet defaults
+to `0` for `Geometry` types or `4326` for `Geography` types.
+
+The valid values of the `SRID` facet and their meanings are as defined
+by the European Petroleum Survey Group [EPSG](#_EPSG).
+
+::: {.varjson .rep}
+### `$SRID`
+
+The value of `$SRID` is a string containing a number or the symbolic
+value `variable`.
+:::
+
+
+## 3.5 Built-In Abstract Types
The following built-in abstract types can be used within a model:
- `Edm.PrimitiveType`
@@ -664,7 +875,7 @@ be used anywhere a corresponding concrete type can be used, except:
of `4.0`. Services should treat untyped properties as dynamic
properties in `4.0` payloads.
-## 3.5 Built-In Types for defining Vocabulary Terms
+## 3.6 Built-In Types for defining Vocabulary Terms
[Vocabulary terms](#VocabularyandAnnotation) can, in addition, use
- `Edm.AnnotationPath`
@@ -679,7 +890,7 @@ as the type of a primitive term, or the type of a property of a complex
type (recursively) that is exclusively used as the type of a term. See
section "[Path Expressions](#PathExpressions)" for details.
-## 3.6 Annotations
+## 3.7 Annotations
Many parts of the model can be decorated with additional information
using [annotations](#Annotation). Annotations are identified by their
@@ -696,7 +907,7 @@ combination of term and qualifier.
::: {.varjson .rep}
-### Document Object
+### Document Object
A CSDL JSON document consists of a single JSON object. This document object MUST contain the member `$Version`.
@@ -706,17 +917,17 @@ It also MAY contain members for schemas.
If the CSDL JSON document is the metadata document of an OData service, the document object MUST contain the member `$EntityContainer`.
-### `$Version`
+### `$Version`
The value of `$Version` is a string containing either `4.0` or `4.01`.
-### `$EntityContainer`
+### `$EntityContainer`
The value of `$EntityContainer` is the namespace-qualified name of the entity container of that service. This is the only place where a model element MUST be referenced with its namespace-qualified name and use of the alias-qualified name is not allowed.
:::
::: {.varjson .example}
-Example 2:
+Example 7:
```json
{
"$Version": "4.01",
@@ -755,14 +966,14 @@ annotation is present, the `$schemaversion` system query option, defined
referenced schema document.
::: {.varjson .rep}
-### `$Reference`
+### `$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.
-### Reference Object
+### Reference Object
The reference object MAY contain the members
[`$Include`](#IncludedSchema) and
@@ -771,7 +982,7 @@ The reference object MAY contain the members
:::
::: {.varjson .example}
-Example 3: references to other CSDL documents
+Example 8: references to other CSDL documents
```json
{
...
@@ -829,26 +1040,26 @@ An alias is only valid within the document in which it is declared; a
referencing document may define its own aliases for included schemas.
::: {.varjson .rep}
-### `$Include`
+### `$Include`
The value of `$Include` is an array. Array items are objects that MUST
contain the member `$Namespace` and MAY contain the member `$Alias`.
The item objects MAY contain [annotations](#Annotation).
-### `$Namespace`
+### `$Namespace`
The value of `$Namespace` is a string containing the namespace of the
included schema.
-### `$Alias`
+### `$Alias`
The value of `$Alias` is a string containing the alias for the included
schema.
:::
::: {.varjson .example}
-Example 4: references to entity models containing definitions of
+Example 9: references to entity models containing definitions of
vocabulary terms
```json
{
@@ -926,27 +1137,27 @@ not interested in that particular target namespace, the consumer can opt
not to inspect the referenced document.
::: {.varjson .rep}
-### `$IncludeAnnotations`
+### `$IncludeAnnotations`
The value of `$IncludeAnnotations` is an array. Array items are objects
that MUST contain the member `$TermNamespace` and MAY contain the
members `$Qualifier` and `$TargetNamespace`.
-### `$TermNamespace`
+### `$TermNamespace`
The value of `$TermNamespace` is a namespace.
-### `$Qualifier`
+### `$Qualifier`
The value of `$Qualifier` is a simple identifier.
-### `$TargetNamespace`
+### `$TargetNamespace`
The value of `$TargetNamespace` is a namespace.
:::
::: {.varjson .example}
-Example 5: reference documents that contain annotations
+Example 10: reference documents that contain annotations
```json
{
...
@@ -1019,7 +1230,7 @@ The namespace MUST NOT be one of the reserved values `Edm`, `odata`,
`System`, or `Transient`.
::: {.varjson .rep}
-### Schema Object
+### Schema Object
A schema is represented as a member of the document object whose name is
the schema namespace. Its value is an object that MAY contain the
@@ -1059,13 +1270,13 @@ The alias MUST NOT be one of the reserved values `Edm`, `odata`,
`System`, or `Transient`.
::: {.varjson .rep}
-### `$Alias`
+### `$Alias`
The value of `$Alias` is a string containing the alias for the schema.
:::
::: {.varjson .example}
-Example 6: document defining a schema `org.example` with an alias and a
+Example 11: document defining a schema `org.example` with an alias and a
description for the schema
```json
{
@@ -1085,7 +1296,7 @@ description for the schema
## 5.2 Annotations with External Targeting
::: {.varjson .rep}
-### `$Annotations`
+### `$Annotations`
The value of `$Annotations` is an object with one member per [annotation
target](#Target). The member name is a path identifying the [annotation
@@ -1094,7 +1305,7 @@ target](#Target), the member value is an object containing
:::
::: {.varjson .example}
-Example 7: annotations targeting the `Person` type with qualifier
+Example 12: annotations targeting the `Person` type with qualifier
`Tablet`
```json
"org.example": {
@@ -1136,7 +1347,7 @@ the same name as one of the direct or indirect base types or derived
types.
::: {.varjson .rep}
-### Entity Type Object
+### Entity Type Object
An entity type is represented as a member of the schema object whose
name is the unqualified name of the entity type and whose value is an
@@ -1155,7 +1366,7 @@ properties](#NavigationProperty) as well as [annotations](#Annotation).
:::
::: {.varjson .example}
-Example 8: a simple entity type
+Example 13: a simple entity type
```json
"Employee": {
"$Kind": "EntityType",
@@ -1188,13 +1399,13 @@ An entity type MUST NOT introduce an inheritance cycle by specifying a
base type.
::: {.varjson .rep}
-### `$BaseType`
+### `$BaseType`
The value of `$BaseType` is the qualified name of the base type.
:::
::: {.varjson .example}
-Example 9: a derived entity type based on the previous example
+Example 14: a derived entity type based on the previous example
```json
"Manager": {
"$Kind": "EntityType",
@@ -1233,7 +1444,7 @@ An abstract entity type MUST NOT inherit from a non-abstract entity
type.
::: {.varjson .rep}
-### `$Abstract`
+### `$Abstract`
The value of `$Abstract` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -1257,7 +1468,7 @@ properties on instances of any structured type, see
[OData-Protocol](#ODataProtocol).
::: {.varjson .rep}
-### `$OpenType`
+### `$OpenType`
The value of `$OpenType` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -1286,7 +1497,7 @@ annotation with term
see [OData-VocCore](#ODataVocCore).
::: {.varjson .rep}
-### `$HasStream`
+### `$HasStream`
The value of `$HasStream `is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -1370,7 +1581,7 @@ used in the query part of URLs, where paths to properties don't require
special encoding and are a standard constituent of expressions anyway.
::: {.varjson .rep}
-### `$Key`
+### `$Key`
The value of `$Key` is an array with one item per key property.
@@ -1383,7 +1594,7 @@ containing the path to the property.
:::
::: {.varjson .example}
-Example 10: entity type with a simple key
+Example 15: entity type with a simple key
```json
"Category": {
"$Kind": "EntityType",
@@ -1402,7 +1613,7 @@ Example 10: entity type with a simple key
:::
::: {.varjson .example}
-Example 11: entity type with a simple key referencing a property of a
+Example 16: entity type with a simple key referencing a property of a
[complex type](#ComplexType)
```json
"Category": {
@@ -1433,7 +1644,7 @@ Example 11: entity type with a simpl
:::
::: {.varjson .example}
-Example 12: entity type with a composite key
+Example 17: entity type with a composite key
```json
"OrderLine": {
"$Kind": "EntityType",
@@ -1456,7 +1667,7 @@ Example 12: entity type with a composite key
::: example
-Example 13 (based on [example 11](#complexkey)): requests to an entity set `Categories`
+Example 18 (based on [example 16](#complexkey)): requests to an entity set `Categories`
of type `Category` must use the alias
```
GET http://host/service/Categories(EntityInfoID=1)
@@ -1464,7 +1675,7 @@ GET http://host/service/Categories(EntityInfoID=1)
:::
::: example
-Example 14 (based on [example 11](#complexkey)): in a query part the value assigned to
+Example 19 (based on [example 16](#complexkey)): in a query part the value assigned to
the name attribute must be used
```
GET http://example.org/OData.svc/Categories?$filter=Info/ID le 100
@@ -1502,7 +1713,7 @@ Names are case-sensitive, but service authors SHOULD NOT choose names
that differ only in case.
::: {.varjson .rep}
-### Property Object
+### Property Object
Structural properties are represented as members of the object
representing a structured type. The member name is the property name,
@@ -1511,7 +1722,7 @@ the member value is an object.
The property object MAY contain the member `$Kind` with a string value
of `Property`. This member SHOULD be omitted to reduce document size.
-It MAY contain the member [`$Type`](#Type), [`$Collection`](#Type),
+It MAY contain the members [`$Type`](#Type), [`$Collection`](#Type),
[`$Nullable`](#Nullable), [`$MaxLength`](#MaxLength),
[`$Unicode`](#Unicode), [`$Precision`](#Precision), [`$Scale`](#Scale),
[`$SRID`](#SRID), and [`$DefaultValue`](#DefaultValue).
@@ -1520,7 +1731,7 @@ It also MAY contain [annotations](#Annotation).
:::
::: {.varjson .example}
-Example 15: complex type with two properties `Dimension` and `Length`
+Example 20: complex type with two properties `Dimension` and `Length`
```json
"Measurement": {
"$Kind": "ComplexType",
@@ -1557,7 +1768,7 @@ term, defined in [OData-VocCore](#ODataVocCore), to specify that it
supports inserting items into a specific ordinal position.
::: {.varjson .rep}
-### `$Type` and `$Collection`
+### `$Type` and `$Collection`
For single-valued properties the value of `$Type` is the qualified name
of the property's type.
@@ -1571,7 +1782,7 @@ member SHOULD be omitted for string properties to reduce document size.
:::
::: {.varjson .example}
-Example 16: property `Units` that can have zero or more strings as its
+Example 21: property `Units` that can have zero or more strings as its
value
```json
"Units": {
@@ -1582,21 +1793,13 @@ value
-## 7.2 Type Facets
-
-Facets modify or constrain the acceptable values of a property.
-
-For single-valued properties the facets apply to the value of the
-property. For collection-valued properties the facets apply to the items
-in the collection.
-
-### 7.2.1 Nullable
+## 7.2 Nullable
A Boolean value specifying whether the property can have the value
`null`.
::: {.varjson .rep}
-### `$Nullable`
+### `$Nullable`
The value of `$Nullable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -1604,228 +1807,23 @@ The value of `$Nullable` is one of the Boolean literals `true` or
For single-valued properties the value `true` means that the property
allows the `null` value.
-For collection-valued properties the property value will always be a
+For collection-valued properties the 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.
:::
-### 7.2.2 MaxLength
-
-A positive integer value specifying the maximum length of a binary,
-stream or string value. For binary or stream values this is the octet
-length of the binary data, for string values it is the character length
-(number of code points for Unicode).
-
-If no maximum length is specified, clients SHOULD expect arbitrary
-length.
-
-::: {.varjson .rep}
-### `$MaxLength`
-
-The value of `$MaxLength` is a positive integer.
-
-Note: [OData-CSDL-XML](#ODataCSDL) 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.
-:::
-
-
-### 7.2.3 Precision
-
-For a decimal value: the maximum number of significant decimal digits of
-the property's value; it MUST be a positive integer.
-
-For a temporal value (datetime-with-timezone-offset, duration, or
-time-of-day): the number of decimal places allowed in the seconds
-portion of the value; it MUST be a non-negative integer between zero and
-twelve.
-
-Note: service authors SHOULD be aware that some clients are unable to
-support a precision greater than 28 for decimal properties and 7 for
-temporal properties. Client developers MUST be aware of the potential
-for data loss when round-tripping values of greater precision. Updating
-via `PATCH` and exclusively specifying modified properties will reduce
-the risk for unintended data loss.
-
-Note: duration properties supporting a granularity less than seconds
-(e.g. minutes, hours, days) can be annotated with term
-[`Measures.DurationGranularity`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Measures.V1.md#DurationGranularity),
-see [OData-VocMeasures](#ODataVocMeasures).
-
-::: {.varjson .rep}
-### `$Precision`
-
-The value of `$Precision` is a number.
-
-Absence of `$Precision` means arbitrary precision.
-:::
+## 7.3 Default Value
-::: {.varjson .example}
-Example 17: `Precision` facet applied to the `DateTimeOffset` type
-```json
-"SuggestedTimes": {
- "$Type": "Edm.DateTimeOffset",
- "$Collection": true,
- "$Precision": 6
-}
-```
-:::
-
-
-
-### 7.2.4 Scale
-
-A non-negative integer value specifying the maximum number of digits
-allowed to the right of the decimal point, or one of the symbolic values
-`floating` or `variable`.
-
-The value `floating` means that the decimal property represents a
-decimal floating-point number whose number of significant digits is the
-value of the [`Precision`](#Precision) facet. OData 4.0 responses MUST
-NOT specify the value `floating`.
-
-The value `variable` means that the number of digits to the right of the
-decimal point can vary from zero to the value of the
-[`Precision`](#Precision) facet.
-
-An integer value means that the number of digits to the right of the
-decimal point may vary from zero to the value of the `Scale` facet, and
-the number of digits to the left of the decimal point may vary from one
-to the value of the `Precision` facet minus the value of the `Scale`
-facet. If `Precision` is equal to `Scale`, a single zero MUST precede
-the decimal point.
-
-The value of `Scale` MUST be less than or equal to the value of
-[`Precision`](#Precision).
-
-Note: if the underlying data store allows negative scale, services may
-use a [`Precision`](#Precision) with the absolute value of the negative
-scale added to the actual number of significant decimal digits, and
-client-provided values may have to be rounded before being stored.
-
-::: {.varjson .rep}
-### `$Scale`
-
-The value of `$Scale` is a number or a string with one of the symbolic
-values `floating` or `variable`.
-
-Services SHOULD use lower-case values; clients SHOULD accept values in a
-case-insensitive manner.
-
-Absence of `$Scale` means `variable`.
-:::
-
-::: {.varjson .example}
-Example 18: [`Precision`](#Precision)`=3` and `Scale=2`.
-Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
-```json
-"Amount32": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 3,
- "$Scale": 2
-}
-```
-:::
-
-::: {.varjson .example}
-Example 19: `Precision=2` equals `Scale`.
-Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
-```json
-"Amount22": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 2,
- "$Scale": 2
-}
-```
-:::
-
-::: {.varjson .example}
-Example 20: `Precision=3` and a variable `Scale`.
-Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed
-values: 12.34, 1234 and 123.4 due to the limited precision.
-```json
-"Amount3v": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 3
-}
-```
-:::
-
-::: {.varjson .example}
-Example 21: `Precision=7` and a floating `Scale`.
-Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values:
-1e-102 and 1e97 due to the limited precision.
-```json
-"Amount7f": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 7,
- "$Scale": "floating"
-}
-```
-:::
-
-
-
-
-
-
-### 7.2.5 Unicode
-
-For a string property the `Unicode` facet indicates whether the property
-might contain and accept string values with Unicode characters (code
-points) beyond the ASCII character set. The value `false` indicates that
-the property will only contain and accept string values with characters
-limited to the ASCII character set.
-
-If no value is specified, the `Unicode` facet defaults to `true`.
-
-::: {.varjson .rep}
-### `$Unicode`
-
-The value of `$Unicode` is one of the Boolean literals `true` or
-`false`. Absence of the member means `true`.
-:::
-
-
-### 7.2.6 SRID
-
-For a geometry or geography property the `SRID` facet identifies which
-spatial reference system is applied to values of the property on type
-instances.
-
-The value of the `SRID` facet MUST be a non-negative integer or the
-special value `variable`. If no value is specified, the facet defaults
-to `0` for `Geometry` types or `4326` for `Geography` types.
-
-The valid values of the `SRID` facet and their meanings are as defined
-by the European Petroleum Survey Group [EPSG](#_EPSG).
-
-::: {.varjson .rep}
-### `$SRID`
-
-The value of `$SRID` is a string containing a number or the symbolic
-value `variable`.
-:::
-
-
-### 7.2.7 Default Value
-
-A primitive or enumeration property MAY define a default value that is
+A primitive- or enumeration-typed property MAY define a default value that is
used if the property is not explicitly represented in an annotation or
the body of a request or response.
If no value is specified, the client SHOULD NOT assume a default value.
::: {.varjson .rep}
-### `$DefaultValue`
+### `$DefaultValue`
The value of `$DefaultValue` is the type-specific JSON representation of
the default value of the property, see
@@ -1861,7 +1859,7 @@ Names are case-sensitive, but service authors SHOULD NOT choose names
that differ only in case.
::: {.varjson .rep}
-### Navigation Property Object
+### Navigation Property Object
Navigation properties are represented as members of the object
representing a structured type. The member name is the property name,
@@ -1944,7 +1942,7 @@ term, defined in [OData-VocCore](#ODataVocCore), to specify that it
supports inserting items into a specific ordinal position.
::: {.varjson .rep}
-### `$Type` and `$Collection`
+### `$Type` and `$Collection`
For single-valued navigation properties the value of `$Type` is the
qualified name of the navigation property's type.
@@ -1965,7 +1963,7 @@ Nullable MUST NOT be specified for a collection-valued navigation
property, a collection is allowed to have zero items.
::: {.varjson .rep}
-### `$Nullable`
+### `$Nullable`
The value of `$Nullable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2005,7 +2003,7 @@ navigation property is defined on a type derived from the type of the
partner navigation property.
::: {.varjson .rep}
-### `$Partner`
+### `$Partner`
The value of `$Partner` is a string containing the path to the partner
navigation property.
@@ -2080,7 +2078,7 @@ entity. This may lead to problems for clients if the contained entity
can also be reached via a non-containment navigation path.
::: {.varjson .rep}
-### `$ContainsTarget`
+### `$ContainsTarget`
The value of `$ContainsTarget` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2113,7 +2111,7 @@ property and the principal property are not nullable, then the dependent
property MUST NOT be nullable.
::: {.varjson .rep}
-### `$ReferentialConstraint`
+### `$ReferentialConstraint`
The value of `$ReferentialConstraint` is an object with one member per
referential constraint. The member name is the path to the dependent
@@ -2190,7 +2188,7 @@ If no on-delete action is specified, the action taken by the service is
not predictable by the client and could vary per entity.
::: {.varjson .rep}
-### `$OnDelete`
+### `$OnDelete`
The value of `$OnDelete` is a string with one of the values `Cascade`,
`None`, `SetNull`, or `SetDefault`.
@@ -2246,7 +2244,7 @@ the same name as one of the direct or indirect base types or derived
types.
::: {.varjson .rep}
-### Complex Type Object
+### Complex Type Object
A complex type is represented as a member of the schema object whose
name is the unqualified name of the complex type and whose value is an
@@ -2317,7 +2315,7 @@ The rules for annotations of derived complex types are described in
[section 14.2](#Annotation).
::: {.varjson .rep}
-### `$BaseType`
+### `$BaseType`
The value of `$BaseType` is the qualified name of the base type.
:::
@@ -2329,7 +2327,7 @@ A complex type MAY indicate that it is abstract and cannot have
instances.
::: {.varjson .rep}
-### `$Abstract`
+### `$Abstract`
The value of `$Abstract` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2353,7 +2351,7 @@ properties on instances of any structured type, see
[OData‑Protocol](#ODataProtocol).
::: {.varjson .rep}
-### `$OpenType`
+### `$OpenType`
The value of `$OpenType` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2381,7 +2379,7 @@ Enumeration types marked as flags allow values that consist of more than
one enumeration member at a time.
::: {.varjson .rep}
-### Enumeration Type Object
+### Enumeration Type Object
An enumeration type is represented as a member of the schema object
whose name is the unqualified name of the enumeration type and whose
@@ -2424,7 +2422,7 @@ An enumeration type MAY specify one of `Edm.Byte`, `Edm.SByte`,
If not explicitly specified, `Edm.Int32` is used as the underlying type.
::: {.varjson .rep}
-### `$UnderlyingType`
+### `$UnderlyingType`
The value of `$UnderlyingType` is the qualified name of the underlying
type.
@@ -2440,7 +2438,7 @@ If not explicitly specified, only one enumeration type member MAY be
selected simultaneously.
::: {.varjson .rep}
-### `$IsFlags`
+### `$IsFlags`
The value of `$IsFlags` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2495,7 +2493,7 @@ selected members is the bitwise OR of the discrete numeric member
values.
::: {.varjson .rep}
-### Enumeration Member Object
+### Enumeration Member Object
Enumeration type members are represented as JSON object members, where
the object member name is the enumeration member name and the object
@@ -2549,7 +2547,7 @@ annotations with this term propagate to places where the annotated type
definition is used, and whether they can be overridden.
::: {.varjson .rep}
-### Type Definition Object
+### Type Definition Object
A type definition is represented as a member of the schema object whose
name is the unqualified name of the type definition and whose value is
@@ -2598,7 +2596,7 @@ The underlying type of a type definition MUST be a primitive type that
MUST NOT be another type definition.
::: {.varjson .rep}
-### `$UnderlyingType`
+### `$UnderlyingType`
The value of `$UnderlyingType` is the qualified name of the underlying
type.
@@ -2661,7 +2659,7 @@ schema.
An unbound action MAY have the same name as a bound action.
::: {.varjson .rep}
-### Action Overload Object
+### Action Overload Object
An action is represented as a member of the schema object whose name is
the unqualified name of the action and whose value is an array. The
@@ -2727,7 +2725,7 @@ disambiguate overloads for both bound and unbound functions, even if
they specify the same underlying type.
::: {.varjson .rep}
-### Function Overload Object
+### Function Overload Object
A function is represented as a member of the schema object whose name is
the unqualified name of the function and whose value is an array. The
@@ -2750,7 +2748,7 @@ explicitly indicated, it is unbound.
Bound actions or functions are invoked on resources matching the type of
the binding parameter. The binding parameter can be of any type, and it
-MAY be [nullable](#Nullable).
+MAY be nullable.
Unbound actions are invoked from the entity container through an [action
import](#ActionImport).
@@ -2760,7 +2758,7 @@ Unbound functions are invoked as static functions within a common expression
or from the entity container through a [function import](#FunctionImport).
::: {.varjson .rep}
-### `$IsBound`
+### `$IsBound`
The value of `$IsBound` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2787,7 +2785,7 @@ type-cast segment names the [qualified name](#QualifiedName) of the
entity type that should be returned from the type cast.
::: {.varjson .rep}
-### `$EntitySetPath`
+### `$EntitySetPath`
The value of `$EntitySetPath` is a string containing the entity set
path.
@@ -2805,7 +2803,7 @@ composable function, and with system query options as appropriate for
the type returned by the composable function.
::: {.varjson .rep}
-### `$IsComposable`
+### `$IsComposable`
The value of `$IsComposable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2817,7 +2815,7 @@ The value of `$IsComposable` is one of the Boolean literals `true` or
The return type of an action or function overload MAY be any type in
scope, or a collection of any type in scope.
-The facets [`Nullable`](#Nullable), [`MaxLength`](#MaxLength),
+The facets [`MaxLength`](#MaxLength),
[`Precision`](#Precision), [`Scale`](#Scale), and [`SRID`](#SRID) can be
used as appropriate to specify value restrictions of the return type, as
well as the [`Unicode`](#Unicode) facet for 4.01 and greater payloads.
@@ -2827,7 +2825,7 @@ For a collection-valued return type the facets apply to the items in the
returned collection.
::: {.varjson .rep}
-### `$ReturnType`
+### `$ReturnType`
The value of `$ReturnType` is an object. It MAY contain the members
`$Type`, `$Collection`, `$Nullable`, [`$MaxLength`](#MaxLength),
@@ -2836,7 +2834,7 @@ and [`$SRID`](#SRID).
It also MAY contain [annotations](#Annotation).
-### `$Type` and `$Collection`
+### `$Type` and `$Collection`
For single-valued return types the value of `$Type` is the qualified
name of the returned type.
@@ -2847,7 +2845,7 @@ present with the literal value `true`.
Absence of the `$Type` member means the type is `Edm.String`.
-### `$Nullable`
+### `$Nullable`
The value of `$Nullable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -2892,12 +2890,12 @@ the parameter value is a collection, the facets apply to the items in
the collection.
::: {.varjson .rep}
-### `$Parameter`
+### `$Parameter`
The value of `$Parameter` is an array. The array contains one object per
parameter.
-### Parameter Object
+### Parameter Object
A parameter object MUST contain the member `$Name`, and it MAY contain
the members `$Type`, `$Collection`, `$Nullable`,
@@ -2906,11 +2904,11 @@ the members `$Type`, `$Collection`, `$Nullable`,
Parameter objects MAY also contain [annotations](#Annotation).
-### `$Name`
+### `$Name`
The value of `$Name` is a string containing the parameter name.
-### `$Type` and `$Collection`
+### `$Type` and `$Collection`
For single-valued parameters the value of `$Type` is the qualified name
of the accepted type.
@@ -2921,7 +2919,7 @@ present with the literal value `true`.
Absence of the `$Type` member means the type is `Edm.String`.
-### `$Nullable`
+### `$Nullable`
The value of `$Nullable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.
@@ -3045,7 +3043,7 @@ import*](#ActionImport) is used to expose a function or action defined
in an entity model as a top level resource.
::: {.varjson .rep}
-### Entity Container Object
+### Entity Container Object
An entity container is represented as a member of the schema object
whose name is the unqualified name of the entity container and whose
@@ -3126,7 +3124,7 @@ containers. Clients should be prepared to process cycles introduced by
extending entity containers.
::: {.varjson .rep}
-### `$Extends`
+### `$Extends`
The value of `$Extends` is the qualified name of the entity container to
be extended.
@@ -3168,7 +3166,7 @@ Entity sets that cannot be queried without specifying additional query
options SHOULD NOT be included in the service document.
::: {.varjson .rep}
-### Entity Set Object
+### Entity Set Object
An entity set is represented as a member of the entity container object
whose name is the name of the entity set and whose value is an object.
@@ -3180,15 +3178,15 @@ It MAY contain the members `$IncludeInServiceDocument` and
[`$NavigationPropertyBinding`](#NavigationPropertyBinding) as well as
[annotations](#Annotation).
-### `$Collection`
+### `$Collection`
The value of `$Collection` is the Booelan value `true`.
-### `$Type`
+### `$Type`
The value of `$Type` is the qualified name of an entity type.
-### `$IncludeInServiceDocument`
+### `$IncludeInServiceDocument`
The value of `$IncludeInServiceDocument` is one of the Boolean literals
`true` or `false`. Absence of the member means `true`.
@@ -3208,7 +3206,7 @@ A singleton MUST specify a type that MUST be an entity type in scope.
A singleton MUST reference an instance its entity type.
::: {.varjson .rep}
-### Singleton Object
+### Singleton Object
A singleton is represented as a member of the entity container object
whose name is the name of the singleton and whose value is an object.
@@ -3220,11 +3218,11 @@ It MAY contain the member
[`$NavigationPropertyBinding`](#NavigationPropertyBinding) as well as
[annotations](#Annotation).
-### `$Type`
+### `$Type`
The value of `$Type` is the qualified name of an entity type.
-### `$Nullable`
+### `$Nullable`
The value of `$Nullable` is one of the Boolean literals `true` or
`false`. Absence of the member means `false`.In OData 4.0 responses this
@@ -3304,7 +3302,7 @@ before ending in a containment navigation property, and there MUST NOT
be any non-containment navigation properties prior to the final segment.
::: {.varjson .rep}
-### `$NavigationPropertyBinding`
+### `$NavigationPropertyBinding`
The value of `$NavigationPropertyBinding` is an object. It consists of
members whose name is the navigation property binding path and whose
@@ -3378,7 +3376,7 @@ container. If a [target path](#TargetPath) is specified, it MUST resolve
to an entity set in scope.
::: {.varjson .rep}
-### Action Import Object
+### Action Import Object
An action import is represented as a member of the entity container
object whose name is the name of the action import and whose value is an
@@ -3390,12 +3388,12 @@ It MAY contain the member `$EntitySet`.
It MAY also contain [annotations](#Annotation).
-### `$Action`
+### `$Action`
The value of `$Action` is a string containing the qualified name of an
unbound action.
-### `$EntitySet`
+### `$EntitySet`
The value of `$EntitySet` is a string containing either the unqualified
name of an entity set in the same entity container or a path to an
@@ -3428,7 +3426,7 @@ is included in the service document. If not explicitly indicated, it is
not included.
::: {.varjson .rep}
-### Function Import Object
+### Function Import Object
A function import is represented as a member of the entity container
object whose name is the name of the function import and whose value is
@@ -3440,18 +3438,18 @@ It MAY contain the members `$EntitySet` and `$IncludeInServiceDocument`.
It MAY also contain [annotations](#Annotation).
-### `$Function`
+### `$Function`
The value of `$Function` is a string containing the qualified name of an
unbound function.
-### `$EntitySet`
+### `$EntitySet`
The value of `$EntitySet` is a string containing either the unqualified
name of an entity set in the same entity container or a path to an
entity set in a different entity container.
-### `$IncludeInServiceDocument`
+### `$IncludeInServiceDocument`
The value of `$IncludeInServiceDocument` is one of the Boolean literals
`true` or `false`. Absence of the member means `false`.
@@ -3568,7 +3566,7 @@ The term's type MUST be a type in scope, or a collection of a type in
scope.
::: {.varjson .rep}
-### Term Object
+### Term Object
A term is represented as a member of the schema object whose name is the
unqualified name of the term and whose value is an object.
@@ -3576,15 +3574,16 @@ unqualified name of the term and whose value is an object.
The term object MUST contain the member `$Kind` with a string value of
`Term`.
-It MAY contain the members `$Type`, `$Collection`,
-[`$AppliesTo`](#Applicability), [`$Nullable`](#Nullable),
+It MAY contain the members `$Type`, `$Collection`, `$Nullable`, `$DefaultValue`,
+[`$BaseTerm`](#SpecializedTerm),
+[`$AppliesTo`](#Applicability),
[`$MaxLength`](#MaxLength), [`$Precision`](#Precision),
-[`$Scale`](#Scale), [`$SRID`](#SRID), and `$DefaultValue`, as well as
+[`$Scale`](#Scale), and [`$SRID`](#SRID), as well as
[`$Unicode`](#Unicode) for 4.01 and greater payloads.
It MAY contain [annotations](#Annotation).
-### `$Type` and `$Collection`
+### `$Type` and `$Collection`
For single-valued terms the value of `$Type` is the qualified name of
the term's type.
@@ -3595,7 +3594,20 @@ with the literal value `true`.
Absence of the `$Type` member means the type is `Edm.String`.
-### `$DefaultValue`
+### `$Nullable`
+
+The value of `$Nullable` is one of the Boolean literals `true` or
+`false`. Absence of the member means `false`.
+
+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
@@ -3617,7 +3629,7 @@ with the same qualifier, and so on until a term without a base term is
reached.
::: {.varjson .rep}
-### `$BaseTerm`
+### `$BaseTerm`
The value of `$BaseTerm` is the qualified name of the base term.
:::
@@ -3670,7 +3682,7 @@ Symbolic Value|Model Element
`UrlRef` |UrlRef annotation expression
::: {.varjson .rep}
-### `$AppliesTo`
+### `$AppliesTo`
The value of `$AppliesTo` is an array whose items are strings containing
symbolic values from the table above that identify model elements the
@@ -3713,7 +3725,7 @@ an annotation value is a [path expression](#ValuePath) that refers to a
property of the same or a related structured type.
::: {.varjson .rep}
-### Annotation Member
+### Annotation Member
An annotation is represented as a member whose name consists of an at
(`@`) character, followed by the qualified name of a term, optionally
@@ -4596,7 +4608,7 @@ The value of the path expression is the instance or collection of
instances identified by the path.
::: {.varjson .rep}
-### `$Path`
+### `$Path`
Path expressions are represented as an object with a single member
`$Path` whose value is a string containing a path.
@@ -4649,7 +4661,7 @@ The other comparison operators require two operand expressions that
evaluate to comparable values.
::: {.varjson .rep}
-### `$And` and `$Or`
+### `$And` and `$Or`
The `And` and `Or` logical expressions are represented as an object with
a single member whose value is an array with two annotation expressions.
@@ -4657,14 +4669,14 @@ The member name is one of `$And`, or `$Or`.
It MAY contain [annotations](#Annotation).
-### `$Not`
+### `$Not`
Negation expressions are represented as an object with a single member
`$Not` whose value is an annotation expression.
It MAY contain [annotations](#Annotation).
-### `$Eq`, `$Ne`, `$Gt`, `$Ge`, `$Lt`, `$Le`, `$Has`, and `$In`
+### `$Eq`, `$Ne`, `$Gt`, `$Ge`, `$Lt`, `$Le`, `$Has`, and `$In`
All comparison expressions are represented as an object with a single
member whose value is an array with two annotation expressions. The
@@ -4797,14 +4809,14 @@ to a numeric value. The other arithmetic operators require two operand
expressions that evaluate to numeric values.
::: {.varjson .rep}
-### `$Neg`
+### `$Neg`
Negation expressions are represented as an object with a single member
`$Neg` whose value is an annotation expression.
It MAY contain [annotations](#Annotation).
-### `$Add`, `$Sub`, `$Mul`, `$Div`, `$DivBy`, and `$Mod`
+### `$Add`, `$Sub`, `$Mul`, `$Div`, `$DivBy`, and `$Mod`
These arithmetic expressions are represented as an object with as single
member whose value is an array with two annotation expressions. The
@@ -4895,7 +4907,7 @@ The operand expressions are used as parameters to the client-side
function.
::: {.varjson .rep}
-### `$Apply`
+### `$Apply`
Apply expressions are represented as an object with a member `$Apply`
whose value is an array of annotation expressions, and a member
@@ -4960,7 +4972,7 @@ the member name of the enumeration value.
#### 14.4.4.2 Function `odata.fillUriTemplate`
The `odata.fillUriTemplate` client-side function takes two or more
-expressions as arguments and returns a value of type `Edm.String.`
+expressions as arguments and returns a value of type `Edm.String`.
The first argument MUST be of type `Edm.String` and specifies a URI
template according to [RFC6570](#rfc6570), the other arguments MUST be
@@ -5076,7 +5088,7 @@ rules as the `cast` canonical function defined in
[OData-URL](#ODataURL).
::: {.varjson .rep}
-### `$Cast`
+### `$Cast`
Cast expressions are represented as an object with a member `$Cast`
whose value is an annotation expression, a member `$Type` whose value is
@@ -5159,7 +5171,7 @@ third expression is present, nothing is added to the surrounding
collection.
::: {.varjson .rep}
-### `$If`
+### `$If`
Conditional expressions are represented as an object with a member `$If`
whose value is an array of two or three annotation expressions.
@@ -5194,7 +5206,7 @@ child expression is compatible with the specified type. It returns
the specified type, and `false` otherwise.
::: {.varjson .rep}
-### `$IsOf`
+### `$IsOf`
Is-of expressions are represented as an object with a member `$IsOf`
whose value is an annotation expression, a member `$Type` whose value is
@@ -5241,7 +5253,7 @@ identifier](#SimpleIdentifier) value as its name that MUST be unique
within the schema containing the expression.
::: {.varjson .rep}
-### `$LabeledElement`
+### `$LabeledElement`
Labeled element expressions are represented as an object with a member
`$LabeledElement` whose value is an annotation expression, and a member
@@ -5272,7 +5284,7 @@ in scope and returns the value of the identified labeled element
expression as its value.
::: {.varjson .rep}
-### `$LabeledElementReference`
+### `$LabeledElementReference`
Labeled element reference expressions are represented as an object with
a member `$LabeledElementReference` whose value is a string containing
@@ -5308,7 +5320,7 @@ Example 85:
:::
::: {.varjson .rep}
-### `$Null`
+### `$Null`
Null expression containing [annotations](#Annotations) are represented
as an object with a member `$Null` whose value is the literal `null`.
@@ -5362,7 +5374,7 @@ Annotations for record members are prefixed with the member name.
:::
::: {.varjson .example}
-Example 87: this annotation "morphs" the entity type from [example 8](#entitytype) into
+Example 87: this annotation "morphs" the entity type from [example 13](#entitytype) into
a structured type with two structural properties `GivenName` and
`Surname` and two navigation properties `DirectSupervisor` and
`CostCenter`. The first three properties simply rename properties of the
@@ -5419,7 +5431,7 @@ expression MUST be type compatible with the type expected by the
surrounding expression.
::: {.varjson .rep}
-### `$UrlRef`
+### `$UrlRef`
URL reference expressions are represented as an object with a single
member `$UrlRef` whose value is an annotation expression.
@@ -5948,121 +5960,123 @@ https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a4
# Appendix B. Table of JSON Objects and Members
::: toc
-- [Document Object](#DocumentObject1)
- - [`$Version`](#Version1.1)
- - [`$EntityContainer`](#EntityContainer1.2)
- - [`$Reference`](#Reference1.3)
-- [Reference Object](#ReferenceObject2)
- - [`$Include`](#Include2.1)
- - [`$Namespace`](#Namespace2.2)
- - [`$Alias`](#Alias2.3)
- - [`$IncludeAnnotations`](#IncludeAnnotations2.4)
- - [`$TermNamespace`](#TermNamespace2.5)
- - [`$Qualifier`](#Qualifier2.6)
- - [`$TargetNamespace`](#TargetNamespace2.7)
-- [Schema Object](#SchemaObject3)
- - [`$Alias`](#Alias3.1)
- - [`$Annotations`](#Annotations3.2)
-- [Entity Type Object](#EntityTypeObject4)
- - [`$BaseType`](#BaseType4.1)
- - [`$Abstract`](#Abstract4.2)
- - [`$OpenType`](#OpenType4.3)
- - [`$HasStream`](#HasStream4.4)
- - [`$Key`](#Key4.5)
-- [Property Object](#PropertyObject5)
- - [`$Type`](#Type5.1)
- - [`$Collection`](#Collection5.2)
- - [`$Nullable`](#Nullable5.3)
- - [`$MaxLength`](#MaxLength5.4)
- - [`$Precision`](#Precision5.5)
- - [`$Scale`](#Scale5.6)
- - [`$Unicode`](#Unicode5.7)
- - [`$SRID`](#SRID5.8)
- - [`$DefaultValue`](#DefaultValue5.9)
-- [Navigation Property Object](#NavigationPropertyObject6)
+- [Type Facet Members](#TypeFacetMembers1)
+ - [`$MaxLength`](#MaxLength1.1)
+ - [`$Precision`](#Precision1.2)
+ - [`$Scale`](#Scale1.3)
+ - [`$Unicode`](#Unicode1.4)
+ - [`$SRID`](#SRID1.5)
+- [Document Object](#DocumentObject2)
+ - [`$Version`](#Version2.1)
+ - [`$EntityContainer`](#EntityContainer2.2)
+ - [`$Reference`](#Reference2.3)
+- [Reference Object](#ReferenceObject3)
+ - [`$Include`](#Include3.1)
+ - [`$Namespace`](#Namespace3.2)
+ - [`$Alias`](#Alias3.3)
+ - [`$IncludeAnnotations`](#IncludeAnnotations3.4)
+ - [`$TermNamespace`](#TermNamespace3.5)
+ - [`$Qualifier`](#Qualifier3.6)
+ - [`$TargetNamespace`](#TargetNamespace3.7)
+- [Schema Object](#SchemaObject4)
+ - [`$Alias`](#Alias4.1)
+ - [`$Annotations`](#Annotations4.2)
+- [Entity Type Object](#EntityTypeObject5)
+ - [`$BaseType`](#BaseType5.1)
+ - [`$Abstract`](#Abstract5.2)
+ - [`$OpenType`](#OpenType5.3)
+ - [`$HasStream`](#HasStream5.4)
+ - [`$Key`](#Key5.5)
+- [Property Object](#PropertyObject6)
- [`$Type`](#Type6.1)
- [`$Collection`](#Collection6.2)
- [`$Nullable`](#Nullable6.3)
- - [`$Partner`](#Partner6.4)
- - [`$ContainsTarget`](#ContainsTarget6.5)
- - [`$ReferentialConstraint`](#ReferentialConstraint6.6)
- - [`$OnDelete`](#OnDelete6.7)
-- [Complex Type Object](#ComplexTypeObject7)
- - [`$BaseType`](#BaseType7.1)
- - [`$Abstract`](#Abstract7.2)
- - [`$OpenType`](#OpenType7.3)
-- [Enumeration Type Object](#EnumerationTypeObject8)
- - [`$UnderlyingType`](#UnderlyingType8.1)
- - [`$IsFlags`](#IsFlags8.2)
-- [Enumeration Member Object](#EnumerationMemberObject9)
-- [Type Definition Object](#TypeDefinitionObject10)
- - [`$UnderlyingType`](#UnderlyingType10.1)
-- [Action Overload Object](#ActionOverloadObject11)
-- [Function Overload Object](#FunctionOverloadObject12)
- - [`$IsBound`](#IsBound12.1)
- - [`$EntitySetPath`](#EntitySetPath12.2)
- - [`$IsComposable`](#IsComposable12.3)
- - [`$ReturnType`](#ReturnType12.4)
- - [`$Type`](#Type12.5)
- - [`$Collection`](#Collection12.6)
- - [`$Nullable`](#Nullable12.7)
- - [`$Parameter`](#Parameter12.8)
-- [Parameter Object](#ParameterObject13)
- - [`$Name`](#Name13.1)
- - [`$Type`](#Type13.2)
- - [`$Collection`](#Collection13.3)
- - [`$Nullable`](#Nullable13.4)
-- [Entity Container Object](#EntityContainerObject14)
- - [`$Extends`](#Extends14.1)
-- [Entity Set Object](#EntitySetObject15)
- - [`$Collection`](#Collection15.1)
- - [`$Type`](#Type15.2)
- - [`$IncludeInServiceDocument`](#IncludeInServiceDocument15.3)
-- [Singleton Object](#SingletonObject16)
- - [`$Type`](#Type16.1)
- - [`$Nullable`](#Nullable16.2)
- - [`$NavigationPropertyBinding`](#NavigationPropertyBinding16.3)
-- [Action Import Object](#ActionImportObject17)
- - [`$Action`](#Action17.1)
- - [`$EntitySet`](#EntitySet17.2)
-- [Function Import Object](#FunctionImportObject18)
- - [`$Function`](#Function18.1)
+ - [`$DefaultValue`](#DefaultValue6.4)
+- [Navigation Property Object](#NavigationPropertyObject7)
+ - [`$Type`](#Type7.1)
+ - [`$Collection`](#Collection7.2)
+ - [`$Nullable`](#Nullable7.3)
+ - [`$Partner`](#Partner7.4)
+ - [`$ContainsTarget`](#ContainsTarget7.5)
+ - [`$ReferentialConstraint`](#ReferentialConstraint7.6)
+ - [`$OnDelete`](#OnDelete7.7)
+- [Complex Type Object](#ComplexTypeObject8)
+ - [`$BaseType`](#BaseType8.1)
+ - [`$Abstract`](#Abstract8.2)
+ - [`$OpenType`](#OpenType8.3)
+- [Enumeration Type Object](#EnumerationTypeObject9)
+ - [`$UnderlyingType`](#UnderlyingType9.1)
+ - [`$IsFlags`](#IsFlags9.2)
+- [Enumeration Member Object](#EnumerationMemberObject10)
+- [Type Definition Object](#TypeDefinitionObject11)
+ - [`$UnderlyingType`](#UnderlyingType11.1)
+- [Action Overload Object](#ActionOverloadObject12)
+- [Function Overload Object](#FunctionOverloadObject13)
+ - [`$IsBound`](#IsBound13.1)
+ - [`$EntitySetPath`](#EntitySetPath13.2)
+ - [`$IsComposable`](#IsComposable13.3)
+ - [`$ReturnType`](#ReturnType13.4)
+ - [`$Type`](#Type13.5)
+ - [`$Collection`](#Collection13.6)
+ - [`$Nullable`](#Nullable13.7)
+ - [`$Parameter`](#Parameter13.8)
+- [Parameter Object](#ParameterObject14)
+ - [`$Name`](#Name14.1)
+ - [`$Type`](#Type14.2)
+ - [`$Collection`](#Collection14.3)
+ - [`$Nullable`](#Nullable14.4)
+- [Entity Container Object](#EntityContainerObject15)
+ - [`$Extends`](#Extends15.1)
+- [Entity Set Object](#EntitySetObject16)
+ - [`$Collection`](#Collection16.1)
+ - [`$Type`](#Type16.2)
+ - [`$IncludeInServiceDocument`](#IncludeInServiceDocument16.3)
+- [Singleton Object](#SingletonObject17)
+ - [`$Type`](#Type17.1)
+ - [`$Nullable`](#Nullable17.2)
+ - [`$NavigationPropertyBinding`](#NavigationPropertyBinding17.3)
+- [Action Import Object](#ActionImportObject18)
+ - [`$Action`](#Action18.1)
- [`$EntitySet`](#EntitySet18.2)
- - [`$IncludeInServiceDocument`](#IncludeInServiceDocument18.3)
-- [Term Object](#TermObject19)
- - [`$Type`](#Type19.1)
- - [`$Collection`](#Collection19.2)
- - [`$DefaultValue`](#DefaultValue19.3)
- - [`$BaseTerm`](#BaseTerm19.4)
- - [`$AppliesTo`](#AppliesTo19.5)
-- [Annotation Member](#AnnotationMember20)
- - [`$Path`](#Path20.1)
- - [`$And`](#And20.2)
- - [`$Or`](#Or20.3)
- - [`$Not`](#Not20.4)
- - [`$Eq`](#Eq20.5)
- - [`$Ne`](#Ne20.6)
- - [`$Gt`](#Gt20.7)
- - [`$Ge`](#Ge20.8)
- - [`$Lt`](#Lt20.9)
- - [`$Le`](#Le20.10)
- - [`$Has`](#Has20.11)
- - [`$In`](#In20.12)
- - [`$Neg`](#Neg20.13)
- - [`$Add`](#Add20.14)
- - [`$Sub`](#Sub20.15)
- - [`$Mul`](#Mul20.16)
- - [`$Div`](#Div20.17)
- - [`$DivBy`](#DivBy20.18)
- - [`$Mod`](#Mod20.19)
- - [`$Apply`](#Apply20.20)
- - [`$Cast`](#Cast20.21)
- - [`$If`](#If20.22)
- - [`$IsOf`](#IsOf20.23)
- - [`$LabeledElement`](#LabeledElement20.24)
- - [`$LabeledElementReference`](#LabeledElementReference20.25)
- - [`$Null`](#Null20.26)
- - [`$UrlRef`](#UrlRef20.27)
+- [Function Import Object](#FunctionImportObject19)
+ - [`$Function`](#Function19.1)
+ - [`$EntitySet`](#EntitySet19.2)
+ - [`$IncludeInServiceDocument`](#IncludeInServiceDocument19.3)
+- [Term Object](#TermObject20)
+ - [`$Type`](#Type20.1)
+ - [`$Collection`](#Collection20.2)
+ - [`$Nullable`](#Nullable20.3)
+ - [`$DefaultValue`](#DefaultValue20.4)
+ - [`$BaseTerm`](#BaseTerm20.5)
+ - [`$AppliesTo`](#AppliesTo20.6)
+- [Annotation Member](#AnnotationMember21)
+ - [`$Path`](#Path21.1)
+ - [`$And`](#And21.2)
+ - [`$Or`](#Or21.3)
+ - [`$Not`](#Not21.4)
+ - [`$Eq`](#Eq21.5)
+ - [`$Ne`](#Ne21.6)
+ - [`$Gt`](#Gt21.7)
+ - [`$Ge`](#Ge21.8)
+ - [`$Lt`](#Lt21.9)
+ - [`$Le`](#Le21.10)
+ - [`$Has`](#Has21.11)
+ - [`$In`](#In21.12)
+ - [`$Neg`](#Neg21.13)
+ - [`$Add`](#Add21.14)
+ - [`$Sub`](#Sub21.15)
+ - [`$Mul`](#Mul21.16)
+ - [`$Div`](#Div21.17)
+ - [`$DivBy`](#DivBy21.18)
+ - [`$Mod`](#Mod21.19)
+ - [`$Apply`](#Apply21.20)
+ - [`$Cast`](#Cast21.21)
+ - [`$If`](#If21.22)
+ - [`$IsOf`](#IsOf21.23)
+ - [`$LabeledElement`](#LabeledElement21.24)
+ - [`$LabeledElementReference`](#LabeledElementReference21.25)
+ - [`$Null`](#Null21.26)
+ - [`$UrlRef`](#UrlRef21.27)
:::
-------
diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html
index 3192e4162..0d1b52af9 100644
--- a/docs/odata-csdl-xml/odata-csdl-xml.html
+++ b/docs/odata-csdl-xml/odata-csdl-xml.html
@@ -187,9 +187,17 @@ Table of Contents
- 3.1 Nominal Types
- 3.2 Structured Types
- 3.3 Primitive Types
-- 3.4 Built-In Abstract Types
-- 3.5 Built-In Types for defining Vocabulary Terms
-- 3.6 Annotations
+- 3.4 Type Facets
+
+- 3.5 Built-In Abstract Types
+- 3.6 Built-In Types for defining Vocabulary Terms
+- 3.7 Annotations
- 4 CSDL XML Document
@@ -213,16 +221,8 @@ Table of Contents
- 7 Structural Property
- 8 Navigation Property
@@ -630,7 +630,84 @@ 3.3
Edm.Stream is a primitive type that can be used as a property of an entity type or complex type, the underlying type for a type definition, or the binding parameter or return type of an action or function. Edm.Stream, or a type definition whose underlying type is Edm.Stream, cannot be used in collections or for non-binding parameters to functions or actions.
Some of these types allow facets, defined in section "Type Facets".
See rule primitiveLiteral in OData-ABNF for the representation of primitive type values in URLs and OData-JSON for the representation in requests and responses.
-3.4 Built-In Abstract Types
+3.4 Type Facets
+The facets in the following subsections modify or constrain the acceptable values of primitive typed model elements, for example a structural property, action or function parameter, action or function return type, or term.
+For single-valued model elements the facets apply to the value of the model element. For collection-valued model elements the facets apply to the items in the collection.
+3.4.1 MaxLength
+A positive integer value specifying the maximum length of a binary, stream or string value. For binary or stream values this is the octet length of the binary data, for string values it is the character length (number of code points for Unicode).
+If no maximum length is specified, clients SHOULD expect arbitrary length.
+
+ Type Facet Attributes
+ Attribute MaxLength
+The value of MaxLength is a positive integer or the symbolic value max as a shorthand for the maximum length supported for the type by the service.
+Note: the symbolic value max is only allowed in OData 4.0 responses; it is deprecated in OData 4.01. While clients MUST be prepared for this symbolic value, OData 4.01 and greater services MUST NOT return the symbolic value max and MAY instead specify the concrete maximum length supported for the type by the service or omit the attribute entirely.
+
+3.4.2 Precision
+For a decimal value: the maximum number of significant decimal digits of the model element's value; it MUST be a positive integer.
+For a temporal value (datetime-with-timezone-offset, duration, or time-of-day): the number of decimal places allowed in the seconds portion of the value; it MUST be a non-negative integer between zero and twelve.
+Note: service authors SHOULD be aware that some clients are unable to support a precision greater than 28 for decimal values and 7 for temporal values. Client developers MUST be aware of the potential for data loss when round-tripping values of greater precision. Updating via PATCH and exclusively specifying modified values will reduce the risk for unintended data loss.
+Note: model elements with duration values and a granularity less than seconds (e.g. minutes, hours, days) can be annotated with term Measures.DurationGranularity, see OData-VocMeasures.
+
+ Attribute Precision
+The value of Precision is a number.
+If not specified for a decimal value, the decimal value has arbitrary precision.
+If not specified for a temporal value, the temporal value has a precision of zero.
+
+
+Example 2: Precision facet applied to the DateTimeOffset type
+<Property Name="SuggestedTimes" Type="Collection(Edm.DateTimeOffset)"
+ Precision="6" />
+
+3.4.3 Scale
+A non-negative integer value specifying the maximum number of digits allowed to the right of the decimal point, or one of the symbolic values floating or variable.
+The value floating means that the decimal value represents a decimal floating-point number whose number of significant digits is the value of the Precision facet. OData 4.0 responses MUST NOT specify the value floating.
+The value variable means that the number of digits to the right of the decimal point can vary from zero to the value of the Precision facet.
+An integer value means that the number of digits to the right of the decimal point may vary from zero to the value of the Scale facet, and the number of digits to the left of the decimal point may vary from one to the value of the Precision facet minus the value of the Scale facet. If Precision is equal to Scale, a single zero MUST precede the decimal point.
+The value of Scale MUST be less than or equal to the value of Precision.
+Note: if the underlying data store allows negative scale, services may use a Precision with the absolute value of the negative scale added to the actual number of significant decimal digits, and client-provided values may have to be rounded before being stored.
+
+ Attribute Scale
+The value of Scale is a number or one of the symbolic values floating or variable.
+Services SHOULD use lower-case values; clients SHOULD accept values in a case-insensitive manner.
+If not specified, the Scale facet defaults to zero.
+
+
+Example 3: Precision=3 and Scale=2.
+Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
+(the Nullable attribute can be ignored in these examples)
+<Property Name="Amount32" Type="Edm.Decimal" Nullable="false" Precision="3" Scale="2" />
+
+
+Example 4: Precision=2 equals Scale.
+Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
+<Property Name="Amount22" Type="Edm.Decimal" Nullable="false" Precision="2" Scale="2" />
+
+
+Example 5: Precision=3 and a variable Scale.
+Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed values: 12.34, 1234 and 123.4 due to the limited precision.
+<Property Name="Amount3v" Type="Edm.Decimal" Nullable="false" Precision="3" Scale="variable" />
+
+
+Example 6: Precision=7 and a floating Scale.
+Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values: 1e-102 and 1e97 due to the limited precision.
+<Property Name="Amount7f" Type="Edm.Decimal" Nullable="false" Precision="7" Scale="floating" />
+
+3.4.4 Unicode
+For a string-typed model element the Unicode facet indicates whether the it might contain and accept string values with Unicode characters (code points) beyond the ASCII character set. The value false indicates that the it will only contain and accept string values with characters limited to the ASCII character set.
+If no value is specified, the Unicode facet defaults to true.
+
+ Attribute Unicode
+The value of Unicode is one of the Boolean literals true or false. Absence of the attribute means true.
+
+3.4.5 SRID
+For a geometry- or geography-typed model element the SRID facet identifies which spatial reference system is applied to its values.
+The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.
+The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.
+
+ Attribute SRID
+The value of SRID is a number or the symbolic value variable.
+
+3.5 Built-In Abstract Types
The following built-in abstract types can be used within a model:
Edm.PrimitiveType3.5 Built-In Types for defining Vocabulary Terms
+3.6 Built-In Types for defining Vocabulary Terms
Vocabulary terms can, in addition, use
Edm.AnnotationPathPath Expressions" for details.
-3.6 Annotations
+3.7 Annotations
Many parts of the model can be decorated with additional information using annotations. Annotations are identified by their term name and an optional qualifier that allows applying the same term multiple times to the same model element.
A model element MUST NOT specify more than one annotation for a given combination of term and qualifier.
@@ -693,22 +770,22 @@ 4
- Element edmx:Edmx
+ Element edmx:Edmx
The edmx:Edmx element is the root element of a CSDL XML document. It MUST contain the Version attribute and it MUST contain exactly one edmx:DataServices element.
It MAY contain edmx:Reference elements to reference other CSDL documents.
- Attribute Version
-The Version attribute specifies the OData protocol version of the service. For OData 4.0 responses the value of this attribute MUST be 4.0. For OData 4.01 responses the value of this attribute MUST be 4.01. Services MUST return an OData 4.0 response if the request was made with an OData-MaxVersion header with a value of 4.0.
- Element edmx:DataServices
+ Attribute Version
+The Version attribute specifies the OData protocol version of the service. For OData 4.0 responses the value of this attribute MUST be 4.0. For OData 4.01 responses the value of this attribute MUST be 4.01. Services MUST return an OData 4.0 response if the request was made with an OData-MaxVersion header with a value of 4.0.
+ Element edmx:DataServices
The edmx:DataServices element MUST contain one or more edm:Schema elements which define the schemas exposed by the OData service.
-Example 2:
-<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
- Version="4.01">
- <edmx:DataServices>
- ...
- </edmx:DataServices>
-</edmx:Edmx>
+Example 7:
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
+ Version="4.01">
+ <edmx:DataServices>
+ ...
+ </edmx:DataServices>
+</edmx:Edmx>
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.
@@ -716,29 +793,29 @@ 4.1 ReferenceA 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.
- Element edmx:Reference
+ 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.
The edmx:Reference element MUST contain the Uri attribute, and it MUST contain at least one edmx:Include or edmx:IncludeAnnotations child element.
It MAY contain edm:Annotation elements.
- Attribute Uri
+ Attribute Uri
The value of Uri is an absolute or relative URI; relative URIs are relative to the xml:base attribute, see XML-Base.
-Example 3: references to other CSDL documents
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
- Version="4.0">
- <edmx:Reference Uri="http://vocabs.odata.org/capabilities/v1">
- ...
- </edmx:Reference>
- <edmx:Reference Uri="http://vocabs.odata.org/core/v1">
- ...
- </edmx:Reference>
- <edmx:Reference Uri="http://example.org/display/v1">
- ...
- </edmx:Reference>
- <edmx:DataServices>...</edmx:DataServices>
-</edmx:Edmx>
+Example 8: references to other CSDL documents
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
+ Version="4.0">
+ <edmx:Reference Uri="http://vocabs.odata.org/capabilities/v1">
+ ...
+ </edmx:Reference>
+ <edmx:Reference Uri="http://vocabs.odata.org/core/v1">
+ ...
+ </edmx:Reference>
+ <edmx:Reference Uri="http://example.org/display/v1">
+ ...
+ </edmx:Reference>
+ <edmx:DataServices>...</edmx:DataServices>
+</edmx:Edmx>
4.2 Included Schema
A reference MAY include zero or more schemas from the referenced document.
@@ -751,32 +828,32 @@ 4.2
The alias MUST NOT be one of the reserved values Edm, odata, System, or Transient.
An alias is only valid within the document in which it is declared; a referencing document may define its own aliases for included schemas.
- Element edmx:Include
+ Element edmx:Include
The edmx:Include element specifies a schema to include from the referenced CSDL document. It MUST provide the Namespace attribute and it MAY provide the Alias attribute.
It MAY contain edm:Annotation elements.
- Attribute Namespace
+ Attribute Namespace
The value of Namespace is the namespace of a schema defined in the referenced CSDL document.
- Attribute Alias
+ Attribute Alias
The value of Alias is a simple identifier that can be used in qualified names instead of the namespace.
-Example 4: references to entity models containing definitions of vocabulary terms
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
- Version="4.0">
- <edmx:Reference Uri="http://vocabs.odata.org/capabilities/v1">
- <edmx:Include Namespace="Org.OData.Capabilities.V1" />
- </edmx:Reference>
- <edmx:Reference Uri="http://vocabs.odata.org/core/v1">
- <edmx:Include Namespace="Org.OData.Core.V1" Alias="Core">
- <Annotation Term="Core.DefaultNamespace" />
- </edmx:Include>
- </edmx:Reference>
- <edmx:Reference Uri="http://example.org/display/v1">
- <edmx:Include Alias="UI" Namespace="org.example.display" />
- </edmx:Reference>
- <edmx:DataServices>...</edmx:DataServices>
-</edmx:Edmx>
+Example 9: references to entity models containing definitions of vocabulary terms
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
+ Version="4.0">
+ <edmx:Reference Uri="http://vocabs.odata.org/capabilities/v1">
+ <edmx:Include Namespace="Org.OData.Capabilities.V1" />
+ </edmx:Reference>
+ <edmx:Reference Uri="http://vocabs.odata.org/core/v1">
+ <edmx:Include Namespace="Org.OData.Core.V1" Alias="Core">
+ <Annotation Term="Core.DefaultNamespace" />
+ </edmx:Include>
+ </edmx:Reference>
+ <edmx:Reference Uri="http://example.org/display/v1">
+ <edmx:Include Alias="UI" Namespace="org.example.display" />
+ </edmx:Reference>
+ <edmx:DataServices>...</edmx:DataServices>
+</edmx:Edmx>
4.3 Included Annotations
In addition to including whole schemas with all model constructs defined within that schema, a reference may include annotations.
@@ -786,33 +863,33 @@ target MAY be specified. If a target namespace is specified, only those annotations which apply a term form the specified term namespace to a model element of the target namespace (with the specified qualifier, if present) SHOULD be included. If no target namespace is specified, all annotations within the referenced document from the specified term namespace (taking into account the qualifier, if present) SHOULD be included.
The target namespace also provides consumers insight about what namespaces are present in the referenced document. If the consumer is not interested in that particular target namespace, the consumer can opt not to inspect the referenced document.
- Element edmx:IncludeAnnotations
+ Element edmx:IncludeAnnotations
The edmx:IncludeAnnotations element specifies the annotations to include from the referenced CSDL document. If no edmx:IncludeAnnotations element is specified, a client MAY ignore all annotations in the referenced document that are not explicitly used in an edm:Path expression of the referencing document.
The edmx:IncludeAnnotations element MUST provide the TermNamespace attribute, and it MAY provide the Qualifier and TargetNamespace attribute.
- Attribute TermNamespace
+ Attribute TermNamespace
The value of TermNamespace is a namespace.
- Attribute Qualifier
+ Attribute Qualifier
The value of Qualifier is a simple identifier.
- Attribute TargetNamespace
+ Attribute TargetNamespace
The value of TargetNamespace is a namespace.
-Example 5: reference documents that contain annotations
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
- Version="4.0">
- <edmx:Reference Uri="http://odata.org/ann/b">
- <edmx:IncludeAnnotations TermNamespace="org.example.validation" />
- <edmx:IncludeAnnotations TermNamespace="org.example.display"
- Qualifier="Tablet" />
- <edmx:IncludeAnnotations TermNamespace="org.example.hcm"
- TargetNamespace="com.example.Sales" />
- <edmx:IncludeAnnotations TermNamespace="org.example.hcm"
- Qualifier="Tablet"
- TargetNamespace="com.example.Person" />
- </edmx:Reference>
- <edmx:DataServices>...</edmx:DataServices>
-</edmx:Edmx>
+Example 10: reference documents that contain annotations
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
+ Version="4.0">
+ <edmx:Reference Uri="http://odata.org/ann/b">
+ <edmx:IncludeAnnotations TermNamespace="org.example.validation" />
+ <edmx:IncludeAnnotations TermNamespace="org.example.display"
+ Qualifier="Tablet" />
+ <edmx:IncludeAnnotations TermNamespace="org.example.hcm"
+ TargetNamespace="com.example.Sales" />
+ <edmx:IncludeAnnotations TermNamespace="org.example.hcm"
+ Qualifier="Tablet"
+ TargetNamespace="com.example.Person" />
+ </edmx:Reference>
+ <edmx:DataServices>...</edmx:DataServices>
+</edmx:Edmx>
The following annotations from http://odata.org/ann/b are included:
@@ -831,10 +908,10 @@ 5 Schema
Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
The namespace MUST NOT be one of the reserved values Edm, odata, System, or Transient.
- Element edm:Schema
+ Element edm:Schema
The edm:Schema element defines a schema. It MUST contain the Namespace attribute and it MAY contain the Alias attribute.
It MAY contain elements edm:Action, edm:Annotations, edm:Annotation, edm:ComplexType, edm:EntityContainer, edm:EntityType, edm:EnumType, edm:Function, edm:Term, or edm:TypeDefinition.
- Attribute Namespace
+ Attribute Namespace
The value of Namespace is the namespace of the schema
5.1 Alias
@@ -843,32 +920,32 @@ 5.1 Alias
Aliases are document-global, so all schemas defined within or included into a document MUST have different aliases, and aliases MUST differ from the namespaces of all schemas defined within or included into a document. Aliases defined by a schema can be used throughout the containing document and are not restricted to the schema that defines them.
The alias MUST NOT be one of the reserved values Edm, odata, System, or Transient.
- Attribute Alias
+ Attribute Alias
The value of Alias is a simple identifier.
-Example 6: schema org.example with an alias and a description for the schema
-<Schema Namespace="org.example" Alias="self">
- <Annotation Term="Core.Description" String="Example schema" />
- ...
-</Schema>
+Example 11: schema org.example with an alias and a description for the schema
+<Schema Namespace="org.example" Alias="self">
+ <Annotation Term="Core.Description" String="Example schema" />
+ ...
+</Schema>
5.2 Annotations with External Targeting
- Element edm:Annotations
+ Element edm:Annotations
The edm:Annotations element is used to apply a group of annotations to a single model element. It MUST contain the Target attribute and it MAY contain the Qualifier attribute.
It MUST contain at least one edm:Annotation element.
- Attribute Target
+ Attribute Target
The value of Target is a path expression identifying the annotation target. It MUST resolve to a model element in scope.
- Attribute Qualifier
+ Attribute Qualifier
The value of Qualifier is a simple identifier.
-Example 7: annotations should only be applied to tablet devices
-<Annotations Target="org.example.Person" Qualifier="Tablet">
- <Annotation Term="Core.Description" String="Dummy" />
- ...
-</Annotations>
+Example 12: annotations should only be applied to tablet devices
+<Annotations Target="org.example.Person" Qualifier="Tablet">
+ <Annotation Term="Core.Description" String="Dummy" />
+ ...
+</Annotations>
6 Entity Type
@@ -877,40 +954,40 @@ 6 Entity Type
An entity type can define two types of properties. A structural property is a named reference to a primitive, complex, or enumeration type, or a collection of primitive, complex, or enumeration types. A navigation property is a named reference to another entity type or collection of entity types.
All properties MUST have a unique name within an entity type. Properties MUST NOT have the same name as the declaring entity type. They MAY have the same name as one of the direct or indirect base types or derived types.
- Element edm:EntityType
+ Element edm:EntityType
The edm:EntityType element MUST contain the Name attribute, and it MAY contain the BaseType, Abstract, OpenType, and HasStream attributes.
It MAY contain edm:Property and edm:NavigationProperty elements describing the properties of the entity type.
It MAY contain one edm:Key element.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the entity type's name.
-Example 8: a simple entity type
-<EntityType Name="Employee">
- <Key>
- <PropertyRef Name="ID" />
- </Key>
- <Property Name="ID" Type="Edm.String" Nullable="false" />
- <Property Name="FirstName" Type="Edm.String" Nullable="false" />
- <Property Name="LastName" Type="Edm.String" Nullable="false" />
- <NavigationProperty Name="Manager" Type="self.Manager" />
-</EntityType>
+Example 13: a simple entity type
+<EntityType Name="Employee">
+ <Key>
+ <PropertyRef Name="ID" />
+ </Key>
+ <Property Name="ID" Type="Edm.String" Nullable="false" />
+ <Property Name="FirstName" Type="Edm.String" Nullable="false" />
+ <Property Name="LastName" Type="Edm.String" Nullable="false" />
+ <NavigationProperty Name="Manager" Type="self.Manager" />
+</EntityType>
6.1 Derived Entity Type
An entity type can inherit from another entity type by specifying it as its base type.
An entity type inherits the key as well as structural and navigation properties of its base type.
An entity type MUST NOT introduce an inheritance cycle by specifying a base type.
- Attribute BaseType
+ Attribute BaseType
The value of BaseType is the qualified name of the base type.
-Example 9: a derived entity type based on the previous example
-<EntityType Name="Manager" BaseType="self.Employee">
- <Property Name="AnnualBudget" Type="Edm.Decimal" />
- <NavigationProperty Name="Employees" Type="Collection(self.Employee)" />
-</EntityType>
+Example 14: a derived entity type based on the previous example
+<EntityType Name="Manager" BaseType="self.Employee">
+ <Property Name="AnnualBudget" Type="Edm.Decimal" />
+ <NavigationProperty Name="Employees" Type="Collection(self.Employee)" />
+</EntityType>
Note: the derived type has the same name as one of the properties of its base type.
@@ -920,7 +997,7 @@ key or derive from a base type with a defined key.
An abstract entity type MUST NOT inherit from a non-abstract entity type.
- Attribute Abstract
+ Attribute Abstract
The value of Abstract is one of the Boolean literals true or false. Absence of the attribute means false.
6.3 Open Entity Type
@@ -928,7 +1005,7 @@ 6.3
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.
- Attribute OpenType
+ Attribute OpenType
The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.
6.4 Media Entity Type
@@ -936,7 +1013,7 @@
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.
- Attribute HasStream
+ Attribute HasStream
The value of HasStream is one of the Boolean literals true or false. Absence of the attribute means false.
6.5 Key
@@ -968,57 +1045,57 @@ 6.5 Key
An alias MUST NOT be defined if the key property is a primitive property of the entity type itself.
For key properties that are a property of a complex or navigation property, the alias MUST be used in the key predicate of URLs instead of the path to the property because the required percent-encoding of the forward slash separating segments of the path to the property would make URL construction and parsing rather complicated. The alias MUST NOT be used in the query part of URLs, where paths to properties don't require special encoding and are a standard constituent of expressions anyway.
- Element edm:Key
+ Element edm:Key
The edm:Key element MUST contain at least one edm:PropertyRef element.
- Element edm:PropertyRef
+ Element edm:PropertyRef
The edm:PropertyRef element MUST contain the Name attribute and MAY contain the Alias attribute.
- Attribute Name
+ Attribute Name
The value of Name is a path expression leading to a primitive property. The names of the properties in the path are joined together by forward slashes.
- Attribute Alias
+ Attribute Alias
The value of Alias is a simple identifier.
-Example 10: entity type with a simple key
-<EntityType Name="Category">
- <Key>
- <PropertyRef Name="ID" />
- </Key>
- <Property Name="ID" Type="Edm.Int32" Nullable="false" />
- <Property Name="Name" Type="Edm.String" />
-</EntityType>
-
-
-Example 11: entity type with a simple key referencing a property of a complex type
-<EntityType Name="Category">
- <Key>
- <PropertyRef Name="Info/ID" Alias="EntityInfoID" />
- </Key>
- <Property Name="Info" Type="Sales.EntityInfo" Nullable="false" />
- <Property Name="Name" Type="Edm.String" />
-</EntityType>
-
-<ComplexType Name="EntityInfo">
- <Property Name="ID" Type="Edm.Int32" Nullable="false" />
- <Property Name="Created" Type="Edm.DateTimeOffset" />
-</ComplexType>
-
-
-Example 12: entity type with a composite key
-<EntityType Name="OrderLine">
- <Key>
- <PropertyRef Name="OrderID" />
- <PropertyRef Name="LineNumber" />
- </Key>
- <Property Name="OrderID" Type="Edm.Int32" Nullable="false" />
- <Property Name="LineNumber" Type="Edm.Int32" Nullable="false" />
-</EntityType>
+Example 15: entity type with a simple key
+<EntityType Name="Category">
+ <Key>
+ <PropertyRef Name="ID" />
+ </Key>
+ <Property Name="ID" Type="Edm.Int32" Nullable="false" />
+ <Property Name="Name" Type="Edm.String" />
+</EntityType>
+
+
+Example 16: entity type with a simple key referencing a property of a complex type
+<EntityType Name="Category">
+ <Key>
+ <PropertyRef Name="Info/ID" Alias="EntityInfoID" />
+ </Key>
+ <Property Name="Info" Type="Sales.EntityInfo" Nullable="false" />
+ <Property Name="Name" Type="Edm.String" />
+</EntityType>
+
+<ComplexType Name="EntityInfo">
+ <Property Name="ID" Type="Edm.Int32" Nullable="false" />
+ <Property Name="Created" Type="Edm.DateTimeOffset" />
+</ComplexType>
+
+
+Example 17: entity type with a composite key
+<EntityType Name="OrderLine">
+ <Key>
+ <PropertyRef Name="OrderID" />
+ <PropertyRef Name="LineNumber" />
+ </Key>
+ <Property Name="OrderID" Type="Edm.Int32" Nullable="false" />
+ <Property Name="LineNumber" Type="Edm.Int32" Nullable="false" />
+</EntityType>
-Example 13 (based on example 11): requests to an entity set Categories of type Category must use the alias
+Example 18 (based on example 16): requests to an entity set Categories of type Category must use the alias
GET http://host/service/Categories(EntityInfoID=1)
-Example 14 (based on example 11): in a query part the value assigned to the name attribute must be used
+Example 19 (based on example 16): in a query part the value assigned to the name attribute must be used
GET http://example.org/OData.svc/Categories?$filter=Info/ID le 100
@@ -1034,121 +1111,50 @@ simple identifier. It is used when referencing, serializing or deserializing the property. It MUST be unique within the set of structural and navigation properties of the declaring structured type, and MUST NOT match the name of any navigation property in any of its base types. If a structural property with the same name is defined in any of this type's base types, then the property's type MUST be a type derived from the type specified for the property of the base type and constrains this property to be of the specified subtype for instances of this structured type. The name MUST NOT match the name of any structural or navigation property of any of this type's base types for OData 4.0 responses.
Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
- Element edm:Property
-The edm:Property element MUST contain the Name and the Type attribute, and it MAY contain the facet attributes Nullable, MaxLength, Unicode, Precision, Scale, SRID, and DefaultValue.
+ Element edm:Property
+The edm:Property element MUST contain the Name and the Type attribute, and it MAY contain the attributes Nullable, MaxLength, Unicode, Precision, Scale, SRID, and DefaultValue.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the property's name.
-Example 15: complex type with two properties
-<ComplexType Name="Measurement">
- <Property Name="Dimension" Type="Edm.String" Nullable="false" MaxLength="50"
- DefaultValue="Unspecified" />
- <Property Name="Length" Type="Edm.Decimal" Nullable="false" Precision="18"
- Scale="2" />
-</ComplexType>
+Example 20: complex type with two properties
+<ComplexType Name="Measurement">
+ <Property Name="Dimension" Type="Edm.String" Nullable="false" MaxLength="50"
+ DefaultValue="Unspecified" />
+ <Property Name="Length" Type="Edm.Decimal" Nullable="false" Precision="18"
+ Scale="2" />
+</ComplexType>
7.1 Type
The property's type MUST be a primitive type, complex type, or enumeration type in scope, or a collection of one of these types.
A collection-valued property MAY be annotated with the Core.Ordered term, defined in OData-VocCore, to specify that it supports a stable ordering.
A collection-valued property MAY be annotated with the Core.PositionalInsert term, defined in OData-VocCore, to specify that it supports inserting items into a specific ordinal position.
- Attribute Type
+ Attribute Type
For single-valued properties the value of Type is the qualified name of the property's type.
For collection-valued properties the value of Type is the character sequence Collection( followed by the qualified name of the property's item type, followed by a closing parenthesis ).
-Example 16: property Units that can have zero or more strings as its value
-<Property Name="Units" Type="Collection(Edm.String)" />
+Example 21: property Units that can have zero or more strings as its value
+<Property Name="Units" Type="Collection(Edm.String)" />
-7.2 Type Facets
-Facets modify or constrain the acceptable values of a property.
-For single-valued properties the facets apply to the value of the property. For collection-valued properties the facets apply to the items in the collection.
-7.2.1 Nullable
+7.2 Nullable
A Boolean value specifying whether the property can have the value null.
- Attribute Nullable
+ Attribute Nullable
The value of Nullable is one of the Boolean literals true or false.
For single-valued properties the value true means that the property allows the null value.
-For collection-valued properties the property value 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 properties the value 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.
If no value is specified for a single-valued property, the Nullable attribute defaults to true.
In OData 4.01 responses a collection-valued property MUST specify a value for the Nullable attribute.
If no value is specified for a collection-valued property, the client cannot assume any default value. Clients SHOULD be prepared for this situation even in OData 4.01 responses.
-7.2.2 MaxLength
-A positive integer value specifying the maximum length of a binary, stream or string value. For binary or stream values this is the octet length of the binary data, for string values it is the character length (number of code points for Unicode).
-If no maximum length is specified, clients SHOULD expect arbitrary length.
-
- Attribute MaxLength
-The value of MaxLength is a positive integer or the symbolic value max as a shorthand for the maximum length supported for the type by the service.
-Note: the symbolic value max is only allowed in OData 4.0 responses; it is deprecated in OData 4.01. While clients MUST be prepared for this symbolic value, OData 4.01 and greater services MUST NOT return the symbolic value max and MAY instead specify the concrete maximum length supported for the type by the service or omit the attribute entirely.
-
-7.2.3 Precision
-For a decimal value: the maximum number of significant decimal digits of the property's value; it MUST be a positive integer.
-For a temporal value (datetime-with-timezone-offset, duration, or time-of-day): the number of decimal places allowed in the seconds portion of the value; it MUST be a non-negative integer between zero and twelve.
-Note: service authors SHOULD be aware that some clients are unable to support a precision greater than 28 for decimal properties and 7 for temporal properties. Client developers MUST be aware of the potential for data loss when round-tripping values of greater precision. Updating via PATCH and exclusively specifying modified properties will reduce the risk for unintended data loss.
-Note: duration properties supporting a granularity less than seconds (e.g. minutes, hours, days) can be annotated with term Measures.DurationGranularity, see OData-VocMeasures.
-
- Attribute Precision
-The value of Precision is a number.
-If not specified for a decimal property, the decimal property has arbitrary precision.
-If not specified for a temporal property, the temporal property has a precision of zero.
-
-
-Example 17: Precision facet applied to the DateTimeOffset type
-<Property Name="SuggestedTimes" Type="Collection(Edm.DateTimeOffset)"
- Precision="6" />
-
-7.2.4 Scale
-A non-negative integer value specifying the maximum number of digits allowed to the right of the decimal point, or one of the symbolic values floating or variable.
-The value floating means that the decimal property represents a decimal floating-point number whose number of significant digits is the value of the Precision facet. OData 4.0 responses MUST NOT specify the value floating.
-The value variable means that the number of digits to the right of the decimal point can vary from zero to the value of the Precision facet.
-An integer value means that the number of digits to the right of the decimal point may vary from zero to the value of the Scale facet, and the number of digits to the left of the decimal point may vary from one to the value of the Precision facet minus the value of the Scale facet. If Precision is equal to Scale, a single zero MUST precede the decimal point.
-The value of Scale MUST be less than or equal to the value of Precision.
-Note: if the underlying data store allows negative scale, services may use a Precision with the absolute value of the negative scale added to the actual number of significant decimal digits, and client-provided values may have to be rounded before being stored.
-
- Attribute Scale
-The value of Scale is a number or one of the symbolic values floating or variable.
-Services SHOULD use lower-case values; clients SHOULD accept values in a case-insensitive manner.
-If not specified, the Scale facet defaults to zero.
-
-
-Example 18: Precision=3 and Scale=2. Allowed values: 1.23, 0.23, 3.14 and 0.7, not allowed values: 123, 12.3
-<Property Name="Amount32" Type="Edm.Decimal" Precision="3" Scale="2" />
-
-
-Example 19: Precision=2 equals Scale. Allowed values: 0.23, 0.7, not allowed values: 1.23, 1.2
-<Property Name="Amount22" Type="Edm.Decimal" Precision="2" Scale="2" />
-
-
-Example 20: Precision=3 and a variable Scale. Allowed values: 0.123, 1.23, 0.23, 0.7, 123 and 12.3, not allowed values: 12.34, 1234 and 123.4 due to the limited precision.
-<Property Name="Amount3v" Type="Edm.Decimal" Precision="3" Scale="variable" />
-
-
-Example 21: Precision=7 and a floating Scale. Allowed values: -1.234567e3, 1e-101, 9.999999e96, not allowed values: 1e-102 and 1e97 due to the limited precision.
-<Property Name="Amount7f" Type="Edm.Decimal" Precision="7" Scale="floating" />
-
-7.2.5 Unicode
-For a string property the Unicode facet indicates whether the property might contain and accept string values with Unicode characters (code points) beyond the ASCII character set. The value false indicates that the property will only contain and accept string values with characters limited to the ASCII character set.
-If no value is specified, the Unicode facet defaults to true.
-
- Attribute Unicode
-The value of Unicode is one of the Boolean literals true or false. Absence of the attribute means true.
-
-7.2.6 SRID
-For a geometry or geography property the SRID facet identifies which spatial reference system is applied to values of the property on type instances.
-The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.
-The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.
-
- Attribute SRID
-The value of SRID is a number or the symbolic value variable.
-
-7.2.7 Default Value
-A primitive or enumeration property MAY define a default value that is used if the property is not explicitly represented in an annotation or the body of a request or response.
+7.3 Default Value
+A primitive- or enumeration-typed property MAY define a default value that is used if the property is not explicitly represented in an annotation or the body of a request or response.
If no value is specified, the client SHOULD NOT assume a default value.
- Attribute DefaultValue
+ Attribute DefaultValue
Default values of type Edm.String MUST be represented according to the XML escaping rules for character data in attribute values. Values of other primitive types MUST be represented according to the appropriate alternative in the primitiveValue rule defined in OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.
@@ -1157,11 +1163,11 @@ simple identifier. It is used when referencing, serializing or deserializing the navigation property. It MUST be unique within the set of structural and navigation properties of the declaring structured type, and MUST NOT match the name of any structural property in any of its base types. If a navigation property with the same name is defined in any of this type's base types, then the navigation property's type MUST be a type derived from the type specified for the navigation property of the base type, and constrains this navigation property to be of the specified subtype for instances of this structured type. The name MUST NOT match the name of any structural or navigation property of any of this type's base types for OData 4.0 responses.
Names are case-sensitive, but service authors SHOULD NOT choose names that differ only in case.
- Element edm:NavigationProperty
+ Element edm:NavigationProperty
The edm:NavigationProperty element MUST contain the Name and Type attributes, and it MAY contain the attributes Nullable, Partner, and ContainsTarget.
It MAY contain child elements edm:ReferentialConstraint and at most one child element edm:OnDelete.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the navigation property's name.
@@ -1187,7 +1193,7 @@ Core.Ordered term, defined in OData-VocCore, to specify that it supports a stable ordering.
A collection-valued navigation property MAY be annotated with the Core.PositionalInsert term, defined in OData-VocCore, to specify that it supports inserting items into a specific ordinal position.
- Attribute Type
+ Attribute Type
For single-valued navigation properties the value of Type is the qualified name of the navigation property's type.
For collection-valued navigation properties the value of Type is the character sequence Collection( followed by the qualified name of the navigation property's item type, followed by a closing parenthesis ).
@@ -1195,7 +1201,7 @@ A Boolean value specifying whether the declaring type MAY have no related entity. If false, instances of the declaring structured type MUST always have a related entity.
Nullable MUST NOT be specified for a collection-valued navigation property, a collection is allowed to have zero items.
- Attribute Nullable
+ Attribute Nullable
The value of Nullable is one of the Boolean literals true or false. Absence of the attribute means true.
8.3 Partner Navigation Property
@@ -1205,7 +1211,7 @@ If no partner navigation property is specified, no assumptions can be made as to whether one of the navigation properties on the target type will lead back to the source entity.
If a partner navigation property is specified, this partner navigation property MUST either specify the current navigation property as its partner to define a bi-directional relationship or it MUST NOT specify a partner navigation property. The latter can occur if the partner navigation property is defined on a complex type, or if the current navigation property is defined on a type derived from the type of the partner navigation property.
- Attribute Partner
+ Attribute Partner
The value of Partner is the path to the of the partner navigation property.
8.4 Containment Navigation Property
@@ -1222,7 +1228,7 @@
- Attribute ContainsTarget
+ Attribute ContainsTarget
The value of ContainsTarget is one of the Boolean literals true or false. Absence of the attribute means false.
8.5 Referential Constraint
@@ -1232,12 +1238,12 @@
- Element edm:ReferentialConstraint
+ Element edm:ReferentialConstraint
The edm:ReferentialConstraint element MUST contain the attributes Property and ReferencedProperty.
It MAY contain edm:Annotation elements.
- Attribute Property
+ Attribute Property
The Property attribute specifies the property that takes part in the referential constraint on the dependent structured type. Its value MUST be a path expression resolving to a property of the dependent structured type itself or to a property of a complex property (recursively) of the dependent structured type. The names of the properties in the path are joined together by forward slashes. The path is relative to the dependent structured type declaring the navigation property.
- Attribute ReferencedProperty
+ Attribute ReferencedProperty
The ReferencedProperty attribute specifies the corresponding property of the principal entity type. Its value MUST be a path expression resolving to a property of the principal entity type itself or to a property of a complex property (recursively) of the principal entity type that MUST have the same type as the property of the dependent entity type. The path is relative to the entity type that is the target of the navigation property.
@@ -1275,10 +1281,10 @@ 8.6
If no on-delete action is specified, the action taken by the service is not predictable by the client and could vary per entity.
- Element edm:OnDelete
+ Element edm:OnDelete
The edm:OnDelete element MUST contain the Action attribute.
It MAY contain edm:Annotation elements.
- Attribute Action
+ Attribute Action
The value of Action is one of the values Cascade, None, SetNull, or SetDefault.
@@ -1300,11 +1306,11 @@ 9 Complex Type
A complex type can define two types of properties. A structural property is a named reference to a primitive, complex, or enumeration type, or a collection of primitive, complex, or enumeration types. A navigation property is a named reference to an entity type or a collection of entity types.
All properties MUST have a unique name within a complex type. Properties MUST NOT have the same name as the declaring complex type. They MAY have the same name as one of the direct or indirect base types or derived types.
- Element edm:ComplexType
+ Element edm:ComplexType
The edm:ComplexType element MUST contain the Name attribute, and it MAY contain the BaseType, Abstract, and OpenType attributes.
It MAY contain edm:Property and edm:NavigationProperty elements describing the properties of the complex type.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the complex type's name.
@@ -1332,13 +1338,13 @@ section 14.2.
- Attribute BaseType
+ Attribute BaseType
The value of BaseType is the qualified name of the base type.
9.2 Abstract Complex Type
A complex type MAY indicate that it is abstract and cannot have instances.
- Attribute Abstract
+ Attribute Abstract
The value of Abstract is one of the Boolean literals true or false. Absence of the attribute means false.
9.3 Open Complex Type
@@ -1346,7 +1352,7 @@
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.
- Attribute OpenType
+ Attribute OpenType
The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.
@@ -1356,11 +1362,11 @@ 1
Although enumeration types have an underlying numeric value, the preferred representation for an enumeration value is the member name. Discrete sets of numeric values should be represented as numeric values annotated with the AllowedValues annotation defined in OData-VocCore.
Enumeration types marked as flags allow values that consist of more than one enumeration member at a time.
- Element edm:EnumType
+ Element edm:EnumType
The edm:EnumType element MUST contain the Name attribute, and it MAY contain the UnderlyingType and IsFlags attributes.
It MUST contain one or more edm:Member elements defining the members of the enumeration type.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the enumeration type's name.
@@ -1376,14 +1382,14 @@
- Attribute UnderlyingType
+ Attribute UnderlyingType
The value of UnderlyingType is the qualified name of the underlying type.
10.2 Flags Enumeration Type
An enumeration type MAY indicate that the enumeration type allows multiple members to be selected simultaneously.
If not explicitly specified, only one enumeration type member MAY be selected simultaneously.
- Attribute IsFlags
+ Attribute IsFlags
The value of IsFlags is one of the Boolean literals true or false. Absence of the attribute means false.
@@ -1411,12 +1417,12 @@
- Element edm:Member
+ Element edm:Member
The edm:Member element MUST contain the Name attribute and it MAY contain the Value attribute.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the enumeration member's name.
- Attribute Value
+ Attribute Value
If the IsFlags attribute has a value of false, either all members MUST specify an integer value for the Value attribute, or all members MUST NOT specify a value for the Value attribute. If no values are specified, the members are assigned consecutive integer values in the order of their appearance, starting with zero for the first member. Client libraries MUST preserve elements in document order.
If the IsFlags attribute has a value of true, a non-negative integer value MUST be specified for the Value attribute. A combined value is equivalent to the bitwise OR of the discrete values.
@@ -1444,10 +1450,10 @@ 11 T
Type definitions can be used wherever a primitive type is used (other than as the underlying type in a new type definition) and are type-comparable with their underlying types and any type definitions defined using the same underlying type.
It is up to the definition of a term to specify whether and how annotations with this term propagate to places where the annotated type definition is used, and whether they can be overridden.
- Element edm:TypeDefinition
+ Element edm:TypeDefinition
The edm:TypeDefinition element MUST contain the Name and UnderlyingType attributes.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the type definition's name.
@@ -1470,7 +1476,7 @@ 11.1 Underlying Primitive Type
The underlying type of a type definition MUST be a primitive type that MUST NOT be another type definition.
- Attribute UnderlyingType
+ Attribute UnderlyingType
The value of UnderlyingType is the qualified name of the underlying type.
The type definition MAY specify facets applicable to the underlying type. Possible facets are: MaxLength, Unicode, Precision, Scale, or SRID.
@@ -1490,11 +1496,11 @@
Unbound actions do not support overloads. The names of all unbound actions MUST be unique within a schema.
An unbound action MAY have the same name as a bound action.
- Element edm:Action
+ Element edm:Action
The edm:Action element MUST contain the Name attribute and it MAY contain the IsBound and EntitySetPath attributes.
It MAY contain at most one edm:ReturnType element and MAY contain edm:Parameter elements.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the action's name.
12.3 Function
@@ -1519,20 +1525,20 @@ type definitions can be used to disambiguate overloads for both bound and unbound functions, even if they specify the same underlying type.
- Element edm:Function
+ Element edm:Function
The edm:Function element MUST contain the Name attribute and it MAY contain the IsBound and EntitySetPath attributes.
It MUST contain one edm:ReturnType element, and it MAY contain edm:Parameter elements.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the action's name.
12.5 Bound or Unbound Action or Function Overloads
An action or function overload MAY indicate that it is bound. If not explicitly indicated, it is unbound.
-Bound actions or functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and it MAY be nullable.
+Bound actions or functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and it MAY be nullable.
Unbound actions are invoked from the entity container through an action import.
Unbound functions are invoked as static functions within a common expression (see OData-URL, section 5.1.1), or from the entity container through a function import.
- Attribute IsBound
+ Attribute IsBound
The value of IsBound is one of the Boolean literals true or false. Absence of the attribute means false.
12.6 Entity Set Path
@@ -1541,28 +1547,28 @@ 12.6
The first segment of the entity set path MUST be the name of the binding parameter. The remaining segments of the entity set path MUST represent navigation segments or type casts.
A navigation segment names the simple identifier of the navigation property to be traversed. A type-cast segment names the qualified name of the entity type that should be returned from the type cast.
- Attribute EntitySetPath
+ Attribute EntitySetPath
The value of EntitySetPath is the entity set path.
12.7 Composable Function
A function MAY indicate that it is composable. If not explicitly indicated, it is not composable.
A composable function can be invoked with additional path segments or key predicates appended to the resource path that identifies the composable function, and with system query options as appropriate for the type returned by the composable function.
- Attribute IsComposable
+ Attribute IsComposable
The value of IsComposable is one of the Boolean literals true or false. Absence of the attribute means false.
12.8 Return Type
The return type of an action or function overload MAY be any type in scope, or a collection of any type in scope.
-The facets Nullable, MaxLength, Precision, Scale, and SRID can be used as appropriate to specify value restrictions of the return type, as well as the Unicode facet for 4.01 and greater payloads.
+The facets MaxLength, Precision, Scale, and SRID can be used as appropriate to specify value restrictions of the return type, as well as the Unicode facet for 4.01 and greater payloads.
For a single-valued return type the facets apply to the returned value. For a collection-valued return type the facets apply to the items in the returned collection.
- Element edm:ReturnType
+ Element edm:ReturnType
The edm:ReturnType element MUST contain the Type attribute, and it MAY contain the attributes Nullable, MaxLength, Unicode, Precision, Scale, and SRID.
It MAY contain edm:Annotation elements.
- Attribute Type
+ Attribute Type
For single-valued return types the value of Type is the qualified name of the return type.
For 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
+ 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.
@@ -1576,15 +1582,15 @@ 12.9 Parameter<
The facets MaxLength, Precision, Scale, or SRID can be used as appropriate to specify value restrictions of the parameter, as well as the Unicode facet for 4.01 and greater payloads.
For single-valued parameters the facets apply to the parameter value. If the parameter value is a collection, the facets apply to the items in the collection.
- Element edm:Parameter
+ Element edm:Parameter
The edm:Parameter element MUST contain the Name and the Type attribute, and it MAY contain the attributes Nullable, MaxLength, Unicode, Precision, Scale, and SRID.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the parameter's name.
- Attribute Type
+ Attribute Type
For single-valued parameters the value of Type is the qualified name of the parameter.
For collection-valued parameters the value of Type is the character sequence Collection( followed by the qualified name of the parameter's type, followed by a closing parenthesis ).
- Attribute Nullable
+ Attribute Nullable
The value of Nullable is one of the Boolean literals true or false. Absence of the attribute means true.
The value true means that the parameter accepts a null value.
@@ -1623,10 +1629,10 @@ 1
A singleton allows addressing a single entity directly from the entity container without having to know its key, and without requiring an entity set.
A function import or an action import is used to expose a function or action defined in an entity model as a top level resource.
- Element edm:EntityContainer
+ Element edm:EntityContainer
The edm:EntityContainer MUST contain one or more edm:EntitySet, edm:Singleton, edm:ActionImport, or edm:FunctionImport elements.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the entity container's name.
@@ -1653,7 +1659,7 @@ If the "extending" entity container defines an entity set with the same name as defined in any of its "base" containers, then the entity set's type MUST specify an entity type derived from the entity type specified for the identically named entity set in the "base" container. The same holds for singletons. Action imports and function imports cannot be redefined, nor can the "extending" container define a child with the same name as a child of a different kind in a "base" container.
Note: services should not introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.
- Attribute Extends
+ Attribute Extends
The value of Extends is the qualified name of the entity container to be extended.
@@ -1670,15 +1676,15 @@ 13.2 Entity SetAn entity set MAY indicate whether it is included in the service document. If not explicitly indicated, it is included.
Entity sets that cannot be queried without specifying additional query options SHOULD NOT be included in the service document.
- Element edm:EntitySet
+ Element edm:EntitySet
The edm:EntitySet element MUST contain the attributes Name and EntityType, and it MAY contain the IncludeInServiceDocument attribute.
It MAY contain edm:NavigationPropertyBinding elements.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the entity set's name.
- Attribute EntityType
+ Attribute EntityType
The value of EntityType is the qualified name of an entity type in scope.
- Attribute IncludeInServiceDocument
+ Attribute IncludeInServiceDocument
The value of IncludeInServiceDocument is one of the Boolean literals true or false. Absence of the attribute means true.
13.3 Singleton
@@ -1687,15 +1693,15 @@ 13.3 Singleton<
A singleton MUST specify a type that MUST be an entity type in scope.
A singleton MUST reference an instance its entity type.
- Element edm:Singleton
+ Element edm:Singleton
The edm:Singleton element MUST include the attributes Name and Type, and it MAY contain the Nullable attribute.
It MAY contain edm:NavigationPropertyBinding elements.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the singleton's name.
- Attribute Type
+ Attribute Type
The value of Type is whose value is the qualified name of an entity type in scope.
- Attribute Nullable
+ Attribute Nullable
The value of Nullable is one of the Boolean literals true or false.
If no value is specified, the Nullable attribute defaults to false.
In OData 4.0 responses this attribute MUST NOT be specified.
@@ -1716,11 +1722,11 @@ 13.4.
If the target is a simple identifier, it MUST resolve to an entity set or singleton defined in the same entity container.
If the target is a target path, it MUST resolve to an entity set, singleton, or direct or indirect containment navigation property of a singleton in scope. The path can traverse single-valued containment navigation properties or single-valued complex properties before ending in a containment navigation property, and there MUST NOT be any non-containment navigation properties prior to the final segment.
- Element edm:NavigationPropertyBinding
+ Element edm:NavigationPropertyBinding
The edm:NavigationPropertyBinding element MUST contain the attributes Path and Target.
- Attribute Path
+ Attribute Path
The value of Path is a path expression.
- Attribute Target
+ Attribute Target
The value of Target is a target path.
@@ -1750,14 +1756,14 @@ 13.5 Acti
An action import MUST specify the name of an unbound action in scope.
If the imported action returns an entity or a collection of entities, a simple identifier or target path value MAY be specified to identify the entity set that contains the returned entities. If a simple identifier is specified, it MUST resolve to an entity set defined in the same entity container. If a target path is specified, it MUST resolve to an entity set in scope.
- Element edm:ActionImport
+ Element edm:ActionImport
The edm:ActionImport element MUST contain the attributes Name and Action, and it MAY contain the EntitySet attribute.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the action import's name.
- Attribute Action
+ Attribute Action
The value of Action is the qualified name of an unbound action.
- Attribute EntitySet
+ Attribute EntitySet
The value of EntitySet is either the unqualified name of an entity set in the same entity container or a path to an entity set in a different entity container.
13.6 Function Import
@@ -1767,15 +1773,15 @@ 13.
If the imported function returns an entity or a collection of entities, a simple identifier or target path value MAY be specified to identify the entity set that contains the returned entities. If a simple identifier is specified, it MUST resolve to an entity set defined in the same entity container. If a target path is specified, it MUST resolve to an entity set in scope.
A function import for a parameterless function MAY indicate whether it is included in the service document. If not explicitly indicated, it is not included.
- Element edm:FunctionImport
+ Element edm:FunctionImport
The edm:FunctionImport element MUST contain the attributes Name and Function, and it MAY contain the attributes EntitySet and IncludeInServiceDocument.
- Attribute Name
+ Attribute Name
The value of Name is the function import's name.
- Attribute Function
+ Attribute Function
The value of Function is the qualified name of an unbound function.
- Attribute EntitySet
+ Attribute EntitySet
The value of EntitySet is either the unqualified name of an entity set in the same entity container or a path to an entity set in a different entity container.
- Attribute IncludeInServiceDocument
+ Attribute IncludeInServiceDocument
The value of IncludeInServiceDocument is one of the Boolean literals true or false. Absence of the attribute means false.
@@ -1821,17 +1827,24 @@ 14.1 Term
The term's name is a simple identifier that MUST be unique within its schema.
The term's type MUST be a type in scope, or a collection of a type in scope.
- Element edm:Term
-The edm:Term element MUST contain the attributes Name and Type. It MAY contain the attributes BaseTerm and AppliesTo.
-It MAY specify values for the Nullable, [ ]{.apple-converted-space}MaxLength, Precision, Scale, or SRID facet attributes, as well as the Unicode facet attribute for 4.01 and greater payloads. These facets and their implications are described in section 7.2.
+ Element edm:Term
+The edm:Term element MUST contain the attributes Name and Type. It MAY contain the attributes Nullable, DefaultValue, BaseTerm and AppliesTo.
+The facets MaxLength, Precision, Scale, and SRID can be used as appropriate, as well as the Unicode facet attribute for 4.01 and greater payloads.
A edm:Term element whose Type attribute specifies a primitive or enumeration type MAY define a value for the DefaultValue attribute.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the term's name.
- Attribute Type
-For single-valued properties the value of Type is the qualified name of the property's type.
+ Attribute Type
+For single-valued terms the value of Type is the qualified name of the term's type.
For collection-valued properties the value of Type is the character sequence Collection( followed by the qualified name of the property's item type, followed by a closing parenthesis ).
- Attribute DefaultValue
+ Attribute Nullable
+The value of Nullable is one of the Boolean literals true or false.
+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 the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.
+If no value is specified for a single-valued term, the Nullable attribute defaults to true.
+In OData 4.01 responses a collection-valued term MUST specify a value for the Nullable attribute.
+If no value is specified for a collection-valued term, the client cannot assume any default value. Clients SHOULD be prepared for this situation even in OData 4.01 responses.
+ Attribute DefaultValue
The value of this attribute determines the value of the term when applied in an edm:Annotation without providing an expression.
Default values of type Edm.String MUST be represented according to the XML escaping rules for character data in attribute values. Values of other primitive types MUST be represented according to the appropriate alternative in the primitiveValue rule defined in OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.
If no value is specified, the DefaultValue attribute defaults to null.
@@ -1840,7 +1853,7 @@ A term MAY specialize another term in scope by specifying it as its base term.
When applying a specialized term, the base term MUST also be applied with the same qualifier, and so on until a term without a base term is reached.
- Attribute BaseTerm
+ Attribute BaseTerm
The value of BaseTerm is the qualified name of the base term.
14.1.2 Applicability
@@ -1988,7 +2001,7 @@ 14.1.2
- Attribute AppliesTo
+ Attribute AppliesTo
The value of AppliesTo is a whitespace-separated list of symbolic values from the table above that identify model elements the term is intended to be applied to.
@@ -2007,13 +2020,13 @@ 14.2 Annotation<
An annotation applies a term to a model element and defines how to calculate a value for the term application. Both term and model element MUST be in scope. Section 14.1.2 specifies which model elements MAY be annotated with a term.
The value of an annotation is specified as an annotation expression, which is either a constant expression representing a constant value, or a dynamic expression. The most common construct for assigning an annotation value is a path expression that refers to a property of the same or a related structured type.
- Element edm:Annotation
+ Element edm:Annotation
The edm:Annotation element MUST contain the attribute Term, and it MAY contain the attribute Qualifier.
The value of the annotation MAY be a constant expression or dynamic expression.
If no expression is specified for a term with a primitive type, the annotation evaluates to the default value of the term definition. If no expression is specified for a term with a complex type, the annotation evaluates to a complex instance with default values for its properties. If no expression is specified for a collection-valued term, the annotation evaluates to an empty collection.
An edm:Annotation element can be used as a child of the model element it annotates, or as the child of an edm:Annotations element that targets the model element to be annotated.
An edm:Annotation element MAY contain edm:Annotation elements that annotate the annotation.
- Attribute Term
+ Attribute Term
The value of Term is the qualified name of a term in scope.
@@ -2036,7 +2049,7 @@ 14.2.1 QualifierA term can be applied multiple times to the same model element by providing a qualifier to distinguish the annotations. The qualifier is a simple identifier.
The combination of target model element, term, and qualifier uniquely identifies an annotation.
- Attribute Qualifier
+ Attribute Qualifier
Annotation elements that are children of an edm:Annotations element MUST NOT provide a value for the qualifier attribute if the parent edm:Annotations element provides a value for the qualifier attribute.
@@ -2187,7 +2200,7 @@ 14.3.1 Binary
- Expression edm:Binary
+ Expression edm:Binary
The edm:Binary expression evaluates to a primitive binary value. A binary expression MUST be assigned a value conforming to the rule binaryValue in OData-ABNF.
The binary expression MAY be provided using element notation or attribute notation.
@@ -2201,7 +2214,7 @@ Expression
14.3.2 Boolean
- Expression edm:Bool
+ Expression edm:Bool
The edm:Bool expression evaluates to a primitive Boolean value. A Boolean expression MUST be assigned a Boolean value.
The Boolean expression MAY be provided using element notation or attribute notation.
@@ -2215,7 +2228,7 @@ Expression
14.3.3 Date
- Expression edm:Date
+ Expression edm:Date
The edm:Date expression evaluates to a primitive date value. A date expression MUST be assigned a value of type xs:date, see XML-Schema-2, section 3.3.9. The value MUST also conform to rule dateValue in OData-ABNF, i.e. it MUST NOT contain a time-zone offset.
The date expression MAY be provided using element notation or attribute notation.
@@ -2229,7 +2242,7 @@ Expression
14.3.4 DateTimeOffset
- Expression edm:DateTimeOffset
+ Expression edm:DateTimeOffset
The edm:DateTimeOffset expression evaluates to a primitive datetimestamp value with a time-zone offset. A datetimestamp expression MUST be assigned a value of type xs:dateTimeStamp, see XML-Schema-2, section 3.4.28. The value MUST also conform to rule dateTimeOffsetValue in OData-ABNF, i.e. it MUST NOT contain an end-of-day fragment (24:00:00).
The datetimestamp expression MAY be provided using element notation or attribute notation.
@@ -2245,7 +2258,7 @@ 14.3.5 Decimal
- Expression edm:Decimal
+ Expression edm:Decimal
The edm:Decimal expression evaluates to a primitive decimal value. A decimal expression MUST be assigned a value conforming to the rule decimalValue in OData-ABNF.
The decimal expression MAY be provided using element notation or attribute notation.
@@ -2261,7 +2274,7 @@ Expression
14.3.6 Duration
- Expression edm:Duration
+ Expression edm:Duration
The edm:Duration expression evaluates to a primitive duration value. A duration expression MUST be assigned a value of type xs:dayTimeDuration, see XML-Schema-2, section 3.4.27.
The duration expression MAY be provided using element notation or attribute notation.
@@ -2275,7 +2288,7 @@ Expressio
14.3.7 Enumeration Member
@@ -2299,7 +2312,7 @@ Expre
14.3.8 Floating-Point Number
- Expression edm:Float
+ Expression edm:Float
The edm:Float expression evaluates to a primitive floating point (or double) value. A float expression MUST be assigned a value conforming to the rule doubleValue in OData-ABNF.
The float expression MAY be provided using element notation or attribute notation.
@@ -2313,7 +2326,7 @@ Expression
14.3.9 Guid
- Expression edm:Guid
+ Expression edm:Guid
The edm:Guid expression evaluates to a primitive guid value. A guid expression MUST be assigned a value conforming to the rule guidValue in OData-ABNF.
The guid expression MAY be provided using element notation or attribute notation.
@@ -2328,7 +2341,7 @@ Expression
14.3.10 Integer
- Expression edm:Int
+ Expression edm:Int
The edm:Int expression evaluates to a primitive integer value. An integer MUST be assigned a value conforming to the rule int64Value in OData-ABNF.
The integer expression MAY be provided using element notation or attribute notation.
@@ -2344,7 +2357,7 @@ Expression ed
14.3.11 String
- Expression edm:String
+ Expression edm:String
The edm:String expression evaluates to a primitive string value. A string expression MUST be assigned a value of the type xs:string, see XML-Schema-2, section 3.3.1.
The string expression MAY be provided using element notation or attribute notation.
@@ -2358,7 +2371,7 @@ Expression
14.3.12 Time of Day
- Expression edm:TimeOfDay
+ Expression edm:TimeOfDay
The edm:TimeOfDay expression evaluates to a primitive time value. A time-of-day expression MUST be assigned a value conforming to the rule timeOfDayValue in OData-ABNF.
The time-of-day expression MAY be provided using element notation or attribute notation.
@@ -2503,7 +2516,7 @@ 1
A term or term property of type Edm.AnnotationPath can be annotated with term Validation.AllowedTerms (see OData-VocValidation) if its intended value is an annotation path that ends in a term cast with one of the listed terms.
The value of the annotation path expression is the path itself, not the value of the annotation identified by the path. This is useful for terms that reuse or refer to other terms.
- Expression edm:AnnotationPath
+ Expression edm:AnnotationPath
The edm:AnnotationPath expression MAY be provided using element notation or attribute notation.
@@ -2522,7 +2535,7 @@ built-in type Edm.ModelElementPath. Its argument is a model path.
The value of the model element path expression is the path itself, not the instance(s) identified by the path.
- Expression edm:ModelElementPath
+ Expression edm:ModelElementPath
The edm:ModelElementPath expression MAY be provided using element notation or attribute notation.
@@ -2541,7 +2554,7 @@
- Expression edm:NavigationPropertyPath
+ Expression edm:NavigationPropertyPath
The edm:NavigationPropertyPath expression MAY be provided using element notation or attribute notation.
@@ -2566,7 +2579,7 @@ 14.4.1.
The value of the property path expression is the path itself, not the value of the structural property or the value of the term cast identified by the path.
- Expression edm:PropertyPath
+ Expression edm:PropertyPath
The edm:PropertyPath MAY be provided using either element notation or attribute notation.
@@ -2588,7 +2601,7 @@ 14.4.1.7 Value P
The value path expression allows assigning a value by traversing an object graph. It can be used in annotations that target entity containers, entity sets, entity types, complex types, navigation properties of structured types, and structural properties of structured types. Its argument is an instance path.
The value of the path expression is the instance or collection of instances identified by the path.
- Expression edm:Path
+ Expression edm:Path
The edm:Path expression MAY be provided using element notation or attribute notation.
@@ -2621,13 +2634,13 @@ OData-URL.
The other comparison operators require two operand expressions that evaluate to comparable values.
- Expressions edm:And and edm:Or
+ Expressions edm:And and edm:Or
The And and Or logical expressions are represented as elements edm:And and edm:Or that MUST contain two annotation expressions.
It MAY contain edm:Annotation elements.
- Expression edm:Not
+ Expression edm:Not
Negation expressions are represented as an element edm:Not that MUST contain a single annotation expression.
It MAY contain edm:Annotation elements.
- Expressions edm:Eq, edm:Ne, edm:Gt, edm:Ge, edm:Lt, edm:Le, edm:Has, and edm:In
+ Expressions edm:Eq, edm:Ne, edm:Gt, edm:Ge, edm:Lt, edm:Le, edm:Has, and edm:In
All comparison expressions are represented as an element that MUST contain two annotation expressions.
They MAY contain edm:Annotation elements.
@@ -2722,10 +2735,10 @@
- Expression edm:Neg
+ Expression edm:Neg
Negation expressions are represented as an element edm:Neg that MUST contain a single annotation expression.
It MAY contain edm:Annotation elements.
- Expressions edm:Add, edm:Sub, edm:Mul, edm:Div, edm:DivBy, and edm:Mod
+ Expressions edm:Add, edm:Sub, edm:Mul, edm:Div, edm:DivBy, and edm:Mod
These arithmetic expressions are represented as an element that MUST contain two annotation expressions.
They MAY contain edm:Annotation elements.
@@ -2762,10 +2775,10 @@ 14.4.4 Apply Client-Side Functions
The apply expression enables a value to be obtained by applying a client-side function. The apply expression MAY have operand expressions. The operand expressions are used as parameters to the client-side function.
- Expression edm:Apply
+ Expression edm:Apply
The edm:Apply element MUST contain the Function attribute and MAY contain annotation expressions as operands for the applied function.
It MAY contain more edm:Annotation elements.
- Attribute Function
+ Attribute Function
The value of Function is the qualified name of the client-side function to apply.
OData defines the following functions. Services MAY support additional functions that MUST be qualified with a namespace other than odata. Function names qualified with odata are reserved for this specification and its future versions.
@@ -2788,7 +2801,7 @@ 14.4.4.2 Function odata.fillUriTemplate
-The odata.fillUriTemplate client-side function takes two or more expressions as arguments and returns a value of type Edm.String.
+The odata.fillUriTemplate client-side function takes two or more expressions as arguments and returns a value of type Edm.String.
The first argument MUST be of type Edm.String and specifies a URI template according to RFC6570, the other arguments MUST be labeled element expressions. Each labeled element expression specifies the template parameter name as its name and evaluates to the template parameter value.
RFC6570 defines three kinds of template parameters: simple values, lists of values, and key-value maps.
Simple values are represented as labeled element expressions that evaluate to a single primitive value. The literal representation of this value according to OData-ABNF is used to fill the corresponding template parameter.
@@ -2828,10 +2841,10 @@ 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.
- Expression edm:Cast
+ Expression edm:Cast
The edm:Cast element MUST contain the Type attribute and MUST contain exactly one expression.
It MAY contain edm:Annotation elements.
- Attribute Type
+ Attribute Type
The value of Type is a qualified type name in scope, or the character sequence Collection( followed by the qualified name of a type in scope, followed by a closing parenthesis ).
If the specified type is a primitive type or a collection of a primitive type, the facet attributes MaxLength, Unicode, Precision, Scale, and SRID MAY be specified if applicable to the specified primitive type. If the facet attributes are not specified, their values are considered unspecified.
@@ -2846,7 +2859,7 @@ 14.4.6 Collection
The collection expression enables a value to be obtained from zero or more item expressions. The value calculated by the collection expression is the collection of the values calculated by each of the item expressions. The values of the child expressions MUST all be type compatible.
- Expression edm:Collection
+ Expression edm:Collection
The edm:Collection element contains zero or more child expressions.
@@ -2865,7 +2878,7 @@ 14.4.7 If-The
The second and third child expressions are evaluated conditionally. The result MUST be type compatible with the type expected by the surrounding expression.
If the first expression evaluates to true, the second expression MUST be evaluated and its value MUST be returned as the result of the if-then-else expression. If the first expression evaluates to false and a third child element is present, it MUST be evaluated and its value MUST be returned as the result of the if-then-else expression. If no third expression is present, nothing is added to the surrounding collection.
- Expression edm:If
+ Expression edm:If
The edm:If element MUST contain two or three child expressions that MUST use element notation.
It MAY contain edm:Annotation elements.
@@ -2882,7 +2895,7 @@ Expression edm:
14.4.8 Is-Of
The is-of expression checks whether the value obtained from its single child expression is compatible with the specified type. It returns true if the child expression returns a type that is compatible with the specified type, and false otherwise.
- Expression edm:UrlRef
+ Expression edm:UrlRef
The edm:UrlRef expression MAY be provided using element notation or attribute notation.
Relative URLs are relative to the xml:base attribute, see XML-Base.
In element notation it MAY contain edm:Annotation elements.
@@ -2900,11 +2913,11 @@ 14
A labeled element expression MUST contain exactly one child expression. The value of the child expression is also the value of the labeled element expression.
A labeled element expression MUST provide a simple identifier value as its name that MUST be unique within the schema containing the expression.
- Expression edm:LabeledElement
+ Expression edm:LabeledElement
The edm:LabeledElement element MUST contain the Name attribute.
It MUST contain a child expression written either in attribute notation or element notation.
It MAY contain edm:Annotation elements.
- Attribute Name
+ Attribute Name
The value of Name is the labeled element's name.
@@ -2922,7 +2935,7 @@ 14.4.10 Labeled Element Reference
The labeled element reference expression MUST specify the qualified name of a labeled element expression in scope and returns the value of the identified labeled element expression as its value.
- Expression edm:LabeledElementReference
+ Expression edm:LabeledElementReference
The edm:LabeledElementReference element MUST contain the qualified name of a labeled element expression in its body.
@@ -2934,7 +2947,7 @@ 14.4.11 Null
The null expression indicates the absence of a value. The null expression MAY be annotated.
- Expression edm:Null
+ Expression edm:Null
The edm:Null element MAY contain edm:Annotation elements.
@@ -2957,19 +2970,19 @@ 14.4.12 Record
A record expression contains zero or more property value expressions. For each single-valued structural or navigation property of the record expression's type that is neither nullable nor specifies a default value a property value expression MUST be provided. The only exception is if the record expression is the value of an annotation for a term that has a base term whose type is structured and directly or indirectly inherits from the type of its base term. In this case, property values that already have been specified in the annotation for the base term or its base term etc. need not be specified again.
For collection-valued properties the absence of a property value expression is equivalent to specifying an empty collection as its value.
- Expression edm:Record
+ Expression edm:Record
The edm:Record element MAY contain the Type attribute and MAY contain edm:PropertyValue elements.
It MAY contain edm:Annotation elements.
- Attribute Type
+ Attribute Type
The value of Type is the qualified name of a structured type in scope.
- Element edm:PropertyValue
+ Element edm:PropertyValue
The edm:PropertyValue element MUST contain the Property attribute, and it MUST contain exactly one expression that MAY be provided using either element notation or attribute notation.
It MAY contain edm:Annotation elements.
- Attribute Property
+ Attribute Property
The value of Property is the name of a property of the type of the enclosing edm:Record expression.
-Example 87: this annotation "morphs" the entity type from example 8 into a structured type with two structural properties GivenName and Surname and two navigation properties DirectSupervisor and CostCenter. The first three properties simply rename properties of the annotated entity type, the fourth adds a calculated navigation property that is pointing to a different service
+Example 87: this annotation "morphs" the entity type from example 13 into a structured type with two structural properties GivenName and Surname and two navigation properties DirectSupervisor and CostCenter. The first three properties simply rename properties of the annotated entity type, the fourth adds a calculated navigation property that is pointing to a different service
<Annotation Term="org.example.person.Employee">
<Record>
<Annotation Term="Core.Description" String="Annotation on record" />
@@ -2995,7 +3008,7 @@ 14.4.13
The URL reference expression MUST contain exactly one expression of type Edm.String. Its value is treated as a URL that MAY be relative or absolute; relative URLs are relative to the URL of the document containing the URL reference expression, or relative to a base URL specified in a format-specific way.
The response body of the GET request MUST be returned as the result of the URL reference expression. The result of the URL reference expression MUST be type compatible with the type expected by the surrounding expression.
- Expression edm:UrlRef
+ Expression edm:UrlRef
The edm:UrlRef expression MAY be provided using element notation or attribute notation.
Relative URLs are relative to the xml:base attribute, see XML-Base.
In element notation it MAY contain edm:Annotation elements.
@@ -3297,239 +3310,243 @@ [OpenUI5]
Appendix B. Table of XML Elements and Attributes
-- Element
edmx:Edmx
+ - Type Facet Attributes
-- Element
edmx:DataServices
-- Element
edmx:Reference
+ - Element
edmx:Edmx
-- Element
edmx:Include
+ - Element
edmx:DataServices
+- Element
edmx:Reference
-- Element
edmx:IncludeAnnotations
+ - Element
edmx:Include
-- Element
edm:Schema
+ - Element
edmx:IncludeAnnotations
-- Element
edm:Annotations
+ - Element
edm:Schema
-- Element
edm:EntityType
+ - Element
edm:Annotations
-- Element
edm:Key
-- Element
edm:PropertyRef
+ - Element
edm:EntityType
-- Element
edm:Property
+ - Element
edm:Key
+- Element
edm:PropertyRef
-- Element
edm:NavigationProperty
+ - Element
edm:Property
-- Element
edm:ReferentialConstraint
+ - Element
edm:NavigationProperty
-- Element
edm:OnDelete
+ - Element
edm:ReferentialConstraint
-- Element
edm:ComplexType
+ - Element
edm:OnDelete
-- Element
edm:EnumType
+ - Element
edm:ComplexType
-- Element
edm:Member
+ - Element
edm:EnumType
-- Element
edm:TypeDefinition
+ - Element
edm:Member
-- Element
edm:Action
+ - Element
edm:TypeDefinition
-- Element
edm:Function
+ - Element
edm:Action
-- Element
edm:ReturnType
+ - Element
edm:Function
-- Element
edm:Parameter
+ - Element
edm:ReturnType
-- Element
edm:EntityContainer
+ - Element
edm:Parameter
-- Element
edm:EntitySet
+ - Element
edm:EntityContainer
-- Element
edm:Singleton
+ - Element
edm:EntitySet
-- Element
edm:NavigationPropertyBinding
+ - Element
edm:Singleton
-- Element
edm:ActionImport
+ - Element
edm:NavigationPropertyBinding
-- Element
edm:FunctionImport
+ - Element
edm:ActionImport
-- Element
edm:Term
+ - Element
edm:FunctionImport
+- Element
edm:Term
+
-- Element
edm:Annotation
+ - Element
edm:Annotation
-- Expression
edm:Binary
-- Expression
edm:Bool
-- Expression
edm:Date
-- Expression
edm:DateTimeOffset
-- Expression
edm:Decimal
-- Expression
edm:Duration
-- Expression
edm:EnumMember
-- Expression
edm:Float
-- Expression
edm:Guid
-- Expression
edm:Int
-- Expression
edm:String
-- Expression
edm:TimeOfDay
-- Expression
edm:AnnotationPath
-- Expression
edm:ModelElementPath
-- Expression
edm:NavigationPropertyPath
-- Expression
edm:PropertyPath
-- Expression
edm:Path
-- Expressions
edm:And
+ - Expression
edm:Binary
+- Expression
edm:Bool
+- Expression
edm:Date
+- Expression
edm:DateTimeOffset
+- Expression
edm:Decimal
+- Expression
edm:Duration
+- Expression
edm:EnumMember
+- Expression
edm:Float
+- Expression
edm:Guid
+- Expression
edm:Int
+- Expression
edm:String
+- Expression
edm:TimeOfDay
+- Expression
edm:AnnotationPath
+- Expression
edm:ModelElementPath
+- Expression
edm:NavigationPropertyPath
+- Expression
edm:PropertyPath
+- Expression
edm:Path
+- Expressions
edm:And
-- Expression
edm:Not
-- Expressions
edm:Eq
+ - Expression
edm:Not
+- Expressions
edm:Eq
-- Expression
edm:Neg
-- Expressions
edm:Add
+ - Expression
edm:Neg
+- Expressions
edm:Add
-- Expression
edm:Apply
+ - Expression
edm:Apply
-- Expression
edm:Cast
+ - Expression
edm:Cast
-- Expression
edm:Collection
-- Expression
edm:If
-- Expression
edm:UrlRef
-- Expression
edm:LabeledElement
+ - Expression
edm:Collection
+- Expression
edm:If
+- Expression
edm:UrlRef
+- Expression
edm:LabeledElement
-- Expression
edm:LabeledElementReference
-- Expression
edm:Null
-- Expression
edm:Record
+ - Expression
edm:LabeledElementReference
+- Expression
edm:Null
+- Expression
edm:Record
-- Element
edm:PropertyValue
+ - Element
edm:PropertyValue
-- Expression
edm:UrlRef
+- Expression
edm:UrlRef
diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md
index 9b70b1e11..54781c677 100644
--- a/docs/odata-csdl-xml/odata-csdl-xml.md
+++ b/docs/odata-csdl-xml/odata-csdl-xml.md
@@ -111,9 +111,15 @@ For complete copyright information please see the full Notices section in an App
- [3.1 Nominal Types](#NominalTypes)
- [3.2 Structured Types](#StructuredTypes)
- [3.3 Primitive Types](#PrimitiveTypes)
- - [3.4 Built-In Abstract Types](#BuiltInAbstractTypes)
- - [3.5 Built-In Types for defining Vocabulary Terms](#BuiltInTypesfordefiningVocabularyTerms)
- - [3.6 Annotations](#Annotations)
+ - [3.4 Type Facets](#TypeFacets)
+ - [3.4.1 MaxLength](#MaxLength)
+ - [3.4.2 Precision](#Precision)
+ - [3.4.3 Scale](#Scale)
+ - [3.4.4 Unicode](#Unicode)
+ - [3.4.5 SRID](#SRID)
+ - [3.5 Built-In Abstract Types](#BuiltInAbstractTypes)
+ - [3.6 Built-In Types for defining Vocabulary Terms](#BuiltInTypesfordefiningVocabularyTerms)
+ - [3.7 Annotations](#Annotations)
- [4 CSDL XML Document](#CSDLXMLDocument)
- [4.1 Reference](#Reference)
- [4.2 Included Schema](#IncludedSchema)
@@ -129,14 +135,8 @@ For complete copyright information please see the full Notices section in an App
- [6.5 Key](#Key)
- [7 Structural Property](#StructuralProperty)
- [7.1 Type](#Type)
- - [7.2 Type Facets](#TypeFacets)
- - [7.2.1 Nullable](#Nullable)
- - [7.2.2 MaxLength](#MaxLength)
- - [7.2.3 Precision](#Precision)
- - [7.2.4 Scale](#Scale)
- - [7.2.5 Unicode](#Unicode)
- - [7.2.6 SRID](#SRID)
- - [7.2.7 Default Value](#DefaultValue)
+ - [7.2 Nullable](#Nullable)
+ - [7.3 Default Value](#DefaultValue)
- [8 Navigation Property](#NavigationProperty)
- [8.1 Navigation Property Type](#NavigationPropertyType)
- [8.2 Nullable Navigation Property](#NullableNavigationProperty)
@@ -558,7 +558,207 @@ representation of primitive type values in URLs and
[OData-JSON](#ODataJSON) for the representation in requests and
responses.
-## 3.4 Built-In Abstract Types
+## 3.4 Type Facets
+
+The facets in the following subsections modify or constrain the acceptable values of primitive typed model elements,
+for example a [structural property](#StructuralProperty),
+action or function [parameter](#Parameter), action or function [return type](#ReturnType), or [term](#Term).
+
+For single-valued model elements the facets apply to the value of the
+model element. For collection-valued model elements the facets apply to the items
+in the collection.
+
+### 3.4.1 MaxLength
+
+A positive integer value specifying the maximum length of a binary,
+stream or string value. For binary or stream values this is the octet
+length of the binary data, for string values it is the character length
+(number of code points for Unicode).
+
+If no maximum length is specified, clients SHOULD expect arbitrary
+length.
+
+
+::: {.varxml .rep}
+### Type Facet Attributes
+### Attribute `MaxLength`
+
+The value of `MaxLength` is a positive integer or the symbolic value
+`max` as a shorthand for the maximum length supported for the type by
+the service.
+
+Note: the symbolic value `max` is only allowed in OData 4.0 responses;
+it is deprecated in OData 4.01. While clients MUST be prepared for this
+symbolic value, OData 4.01 and greater services MUST NOT return the
+symbolic value `max` and MAY instead specify the concrete maximum length
+supported for the type by the service or omit the attribute entirely.
+:::
+
+### 3.4.2 Precision
+
+For a decimal value: the maximum number of significant decimal digits of
+the model element's value; it MUST be a positive integer.
+
+For a temporal value (datetime-with-timezone-offset, duration, or
+time-of-day): the number of decimal places allowed in the seconds
+portion of the value; it MUST be a non-negative integer between zero and
+twelve.
+
+Note: service authors SHOULD be aware that some clients are unable to
+support a precision greater than 28 for decimal values and 7 for
+temporal values. Client developers MUST be aware of the potential
+for data loss when round-tripping values of greater precision. Updating
+via `PATCH` and exclusively specifying modified values will reduce
+the risk for unintended data loss.
+
+Note: model elements with duration values and a granularity less than seconds
+(e.g. minutes, hours, days) can be annotated with term
+[`Measures.DurationGranularity`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Measures.V1.md#DurationGranularity),
+see [OData-VocMeasures](#ODataVocMeasures).
+
+
+
+::: {.varxml .rep}
+### Attribute `Precision`
+
+The value of `Precision` is a number.
+
+If not specified for a decimal value, the decimal value has
+arbitrary precision.
+
+If not specified for a temporal value, the temporal value has a
+precision of zero.
+:::
+
+::: {.varxml .example}
+Example 2: [`Precision`](#Precision) facet applied to the
+`DateTimeOffset` type
+```xml
+
@@ -703,7 +903,7 @@ referenced schema document.
::: {.varxml .rep}
-### Element `edmx:Reference`
+### Element `edmx:Reference`
The `edmx:Reference` element specifies external CSDL documents
referenced by the referencing document. The child elements
@@ -718,7 +918,7 @@ MUST contain at least one [`edmx:Include`](#IncludedSchema) or
It MAY contain [`edm:Annotation`](#Annotation) elements.
-### Attribute `Uri`
+### Attribute `Uri`
The value of `Uri` is an absolute or relative URI; relative URIs are
relative to the `xml:base` attribute, see
@@ -726,7 +926,7 @@ relative to the `xml:base` attribute, see
:::
::: {.varxml .example}
-Example 3: references to other CSDL documents
+Example 8: references to other CSDL documents
```xml
Element `edmx:Include`
+### Element `edmx:Include`
The `edmx:Include` element specifies a schema to include from the
referenced CSDL document. It MUST provide the `Namespace` attribute and
@@ -793,19 +993,19 @@ it MAY provide the `Alias` attribute.
It MAY contain [`edm:Annotation`](#Annotation) elements.
-### Attribute `Namespace`
+### Attribute `Namespace`
The value of `Namespace` is the namespace of a schema defined in the
referenced CSDL document.
-### Attribute `Alias`
+### Attribute `Alias`
The value of `Alias` is a [simple identifier](#SimpleIdentifier) that
can be used in qualified names instead of the namespace.
:::
::: {.varxml .example}
-Example 4: references to entity models containing definitions of
+Example 9: references to entity models containing definitions of
vocabulary terms
```xml
@@ -868,7 +1068,7 @@ not to inspect the referenced document.
::: {.varxml .rep}
-### Element `edmx:IncludeAnnotations`
+### Element `edmx:IncludeAnnotations`
The `edmx:IncludeAnnotations` element specifies the annotations to
include from the referenced CSDL document. If no
@@ -880,21 +1080,21 @@ The `edmx:IncludeAnnotations` element MUST provide the `TermNamespace`
attribute, and it MAY provide the `Qualifier` and `TargetNamespace`
attribute.
-### Attribute `TermNamespace`
+### Attribute `TermNamespace`
The value of `TermNamespace` is a namespace.
-### Attribute `Qualifier`
+### Attribute `Qualifier`
The value of `Qualifier` is a [simple identifier](#SimpleIdentifier).
-### Attribute `TargetNamespace`
+### Attribute `TargetNamespace`
The value of `TargetNamespace` is a namespace.
:::
::: {.varxml .example}
-Example 5: reference documents that contain annotations
+Example 10: reference documents that contain annotations
```xml
Element `edm:Schema`
+### Element `edm:Schema`
The `edm:Schema` element defines a
schema. It MUST contain the `Namespace` attribute and it MAY
@@ -969,7 +1169,7 @@ It MAY contain elements [`edm:Action`](#Action),
[`edm:Function`](#Function), [`edm:Term`](#Term), or
[`edm:TypeDefinition`](#TypeDefinition).
-### Attribute `Namespace`
+### Attribute `Namespace`
The value of `Namespace` is the namespace of the schema
:::
@@ -1000,13 +1200,13 @@ The alias MUST NOT be one of the reserved values `Edm`, `odata`,
::: {.varxml .rep}
-### Attribute `Alias`
+### Attribute `Alias`
The value of `Alias` is a [simple identifier](#SimpleIdentifier).
:::
::: {.varxml .example}
-Example 6: schema `org.example` with an alias and a description for the
+Example 11: schema `org.example` with an alias and a description for the
schema
```xml
@@ -1021,7 +1221,7 @@ schema
::: {.varxml .rep}
-### Element `edm:Annotations`
+### Element `edm:Annotations`
The `edm:Annotations` element is used to apply a group of annotations to
a single model element. It MUST contain the `Target` attribute and it
@@ -1029,18 +1229,18 @@ MAY contain the `Qualifier` attribute.
It MUST contain at least one [`edm:Annotation`](#Annotation) element.
-### Attribute `Target`
+### Attribute `Target`
The value of `Target` is a path expression identifying the [annotation
target](#Target). It MUST resolve to a model element in scope.
-### Attribute `Qualifier`
+### Attribute `Qualifier`
The value of `Qualifier` is a [simple identifier](#SimpleIdentifier).
:::
::: {.varxml .example}
-Example 7: annotations should only be applied to tablet devices
+Example 12: annotations should only be applied to tablet devices
```xml
@@ -1125,13 +1325,13 @@ base type.
::: {.varxml .rep}
-### Attribute `BaseType`
+### Attribute `BaseType`
The value of `BaseType` is the qualified name of the base type.
:::
::: {.varxml .example}
-Example 9: a derived entity type based on the previous example
+Example 14: a derived entity type based on the previous example
```xml
@@ -1334,7 +1534,7 @@ Example 10: entity type with a simple key
:::
::: {.varxml .example}
-Example 11: entity type with a simple key referencing a property of a
+Example 16: entity type with a simple key referencing a property of a
[complex type](#ComplexType)
```xml
@@ -1353,7 +1553,7 @@ Example 11: entity type with a simpl
:::
::: {.varxml .example}
-Example 12: entity type with a composite key
+Example 17: entity type with a composite key
```xml
@@ -1367,7 +1567,7 @@ Example 12: entity type with a composite key
:::
::: example
-Example 13 (based on [example 11](#complexkey)): requests to an entity set `Categories`
+Example 18 (based on [example 16](#complexkey)): requests to an entity set `Categories`
of type `Category` must use the alias
```
GET http://host/service/Categories(EntityInfoID=1)
@@ -1375,7 +1575,7 @@ GET http://host/service/Categories(EntityInfoID=1)
:::
::: example
-Example 14 (based on [example 11](#complexkey)): in a query part the value assigned to
+Example 19 (based on [example 16](#complexkey)): in a query part the value assigned to
the name attribute must be used
```
GET http://example.org/OData.svc/Categories?$filter=Info/ID le 100
@@ -1415,23 +1615,23 @@ that differ only in case.
::: {.varxml .rep}
-### Element `edm:Property`
+### Element `edm:Property`
The `edm:Property` element MUST contain the `Name` and the `Type`
-attribute, and it MAY contain the facet attributes
+attribute, and it MAY contain the attributes
[`Nullable`](#Nullable), [`MaxLength`](#MaxLength),
[`Unicode`](#Unicode), [`Precision`](#Precision), [`Scale`](#Scale),
[`SRID`](#SRID), and [`DefaultValue`](#DefaultValue).
It MAY contain [`edm:Annotation`](#Annotation) elements.
-### Attribute `Name`
+### Attribute `Name`
The value of `Name` is the property's name.
:::
::: {.varxml .example}
-Example 15: complex type with two properties
+Example 20: complex type with two properties
```xml
Attribute `Type`
+### Attribute `Type`
For single-valued properties the value of `Type` is the qualified name
of the property's type.
@@ -1473,29 +1673,21 @@ item type, followed by a closing parenthesis `)`.
:::
::: {.varxml .example}
-Example 16: property `Units` that can have zero or more strings as its
+Example 21: property `Units` that can have zero or more strings as its
value
```xml
4.1 Header Content-Type
Requests and responses with a JSON message body MUST have a Content-Type header value of application/json.
-Requests MAY add the charset parameter to the content type. Allowed values are UTF-8, UTF-16, and UTF-32. If no charset parameter is present, UTF-8 MUST be assumed.
+Requests MAY add the charset parameter to the content type. Allowed values are UTF-8, UTF-16, and UTF-32. If no charset parameter is present, UTF-8 MUST be assumed.
Responses MUST include the metadata parameter to specify the amount of metadata included in the response.
Requests and responses MUST include the IEEE754Compatible parameter if Edm.Int64 and Edm.Decimal numbers are represented as strings.
Requests and responses MAY add the streaming parameter with a value of true or false, see section "Payload Ordering Constraints".
@@ -530,7 +530,7 @@ }
-Example 6: entity of type Model.VipCustomer defined in the metadata document of a different service
+Example 6: entity of type Model.VipCustomer defined in the metadata document of a different service
{
"@context": "http://host/service/$metadata#Customers/$entity",
"@type": "http://host/alternate/$metadata#Model.VipCustomer",
@@ -974,7 +974,7 @@ 9 Str
See OData-Protocol 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, 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 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.
Example 24:
@@ -1256,7 +1256,7 @@ 15.3 D
In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value:
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. For ordered payloads, the control information removed MUST immediately follow the context control information, if present, otherwise it MUST be the first property in the deleted entity.
Control information id or all of the entity's key fields. The id control information MUST appear if any of the entity's key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. For ordered payloads, the control information id, if present, MUST immediately follow the control information removed.
Control information id or all of the entity's key fields. The id control information MUST appear if any of the entity's key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. For ordered payloads, the control information id, if present, MUST immediately follow the control information removed.
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.
@@ -1512,7 +1512,7 @@ 19.1 Batc
Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol.
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.
+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.
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index fd7860882..539712cc3 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/docs/odata-json-format/odata-json-format.md
@@ -551,7 +551,7 @@ Requests and responses with a JSON message body MUST have a
`Content-Type` header value of `application/json`.
Requests MAY add the `charset` parameter to the content type.
-Allowed values are `UTF-8`,` UTF-16`, and
+Allowed values are `UTF-8`, `UTF-16`, and
`UTF-32`. If no `charset` parameter is present,
`UTF-8` MUST be assumed.
@@ -876,10 +876,8 @@ metadata document of the same service with a dynamic property of type
:::
::: example
-Example 6: entity of type
-`Model.VipCustomer` defined in the
-metadata` `document of a different
-service
+Example 6: entity of type `Model.VipCustomer` defined in the
+metadata document of a different service
```json
{
"@context": "http://host/service/$metadata#Customers/$entity",
@@ -1808,7 +1806,8 @@ If the actual stream data is included inline, the control information
MUST be present to indicate how the included stream property value is
represented. Stream property values of media type `application/json` or
one of its subtypes, optionally with format parameters, are represented
-as native JSON. Values of top-level type `text`, for example
+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
@@ -2384,7 +2383,7 @@ following properties, regardless of the specified
from the response _or_ the entity-id is not identical to the canonical
URL of the entity. For [ordered
payloads](#PayloadOrderingConstraints), the control information
- `id,` if present, MUST immediately follow the control
+ `id`, if present, MUST immediately follow the control
information
[`removed`](#ControlInformationremovedodataremoved).
@@ -2872,7 +2871,7 @@ 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,`
+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
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index d315181aa..45e6e3b05 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -306,7 +306,8 @@ Table of Contents
- 11.2.3 Requesting the Media Stream of a Media Entity using
$value
- 11.2.4 Requesting Individual Properties
- 11.2.5 Specifying Properties to Return
@@ -691,7 +692,7 @@ 8.2.4 Header If-Match
As defined in RFC9110, a client MAY include an If-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-Match request header MUST be an ETag value previously retrieved for the resource, or * to match any value.
-If an operation on an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.
+If an operation on an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.
If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending ETag headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from RFC9110.
If the value does not match the current ETag value of the resource for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request. In the case of an upsert, if the addressed entity does not exist the provided ETag value is considered not to match.
An If-Match header with a value of * in a PUT or PATCH request results in an upsert request being processed as an update and not an insert.
@@ -808,14 +809,14 @@ RFC7240.
In OData, return=representation or return=minimal is defined for use with a POST, PUT, or PATCH Data Modification Request, or with an Action Request. Specifying a preference of return=representation or return=minimal in a GET or DELETE request does not have any effect.
A preference of return=representation or return=minimal is allowed on an individual Data Modification Request or Action Request within a batch, subject to the same restrictions, but SHOULD return a 4xx Client Error if specified on the batch request itself.
-A preference of return=minimal requests that the service invoke the request but does not return content in the response. The service MAY apply this preference by returning 204 No Content in which case it MAY include a Preference-Applied response header containing the return=minimal preference.
+A preference of return=minimal requests that the service invoke the request but does not return content in the response. The service MAY apply this preference by returning 204 No Content in which case it MAY include a Preference-Applied response header containing the return=minimal preference.
A preference of return=representation requests that the service invokes the request and returns the modified resource. The service MAY apply this preference by returning the representation of the successfully modified resource in the body of the response, formatted according to the rules specified for the requested format. In this case the service MAY include a Preference-Applied response header containing the return=representation preference.
The return preference SHOULD NOT be applied to a batch request, but MAY be applied to individual requests within a batch.
8.2.8.8 Preference respond-async
The respond-async preference, as defined in RFC7240, allows clients to request that the service process the request asynchronously.
If the client has specified respond-async in the request, the service MAY process the request asynchronously and return a 202 Accepted response.
The respond-async preference MAY be used for batch requests, in which case it applies to the batch request as a whole and not to individual requests within the batch request.
-In the case that the service applies the respond-async preference it MUST include a Preference-Applied response header containing the respond-async preference.
+In the case that the service applies the respond-async preference it MUST include a Preference-Applied response header containing the respond-async preference.
A service MAY specify the support for the respond-async preference using an annotation with term Capabilities.AsynchronousRequestsSupported, see OData-VocCap.
Example 9: a service receiving the following header might choose to respond
@@ -1257,13 +1258,13 @@ 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 set of structural or navigation properties to return may be specified through $select or $expandsystem 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, for example due to permissions, are not returned. In this case, the Core.Permissions annotation, defined in OData-VocCore MUST be returned for the property with a value of None.
+Properties that are not available, for example due to permissions, are not returned. In this case, the Core.Permissions annotation, defined in OData-VocCore MUST be returned for the property with a value of None.
If no entity exists with the specified request URL, the service responds with 404 Not Found.
11.2.3 Requesting the Media Stream of a Media Entity using $value
A media entity is an entity that represents an out-of-band stream, such as a photograph.
Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just structured additional information attached to the stream. Use a normal entity with one or more stream properties 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.
-To address the media stream represented by a media entity, clients append /$value to the resource path of the media entity URL. Services may redirect from this canonical URL to the source URL of the media stream.
-Appending /$value to an entity that is not a media entity returns 400 Bad Request.
+To address the media stream represented by a media entity, clients append /$value to the resource path of the media entity URL. The media type of the response is the media type of the stream, subject to content type negotiation based on the Accept header of the request. The response body is the octet-stream that represents the raw value of the media stream with that media type. Alternatively, services MAY redirect from this canonical URL to the source URL of the media stream.
+Appending /$value to an entity that is not a media entity returns 400 Bad Request.
Attempting to retrieve the media stream from a single-valued navigation property referencing a media entity whose value is null returns 404 Not Found.
11.2.4 Requesting Individual Properties
To retrieve an individual property, the client issues a GET request to the property URL. The property URL is the entity read URL with "/" and the property name appended.
@@ -1275,7 +1276,10 @@ 11.2.4.1 Requesting a Property's Raw Value using $value
+11.2.4.1 Requesting Stream Properties
+
If the property being requested has type Edm.Stream (see OData-URL, section 9), the media type of the response is the media type of the stream, subject to content type negotiation based on the Accept header of the request. The response body is the octet-stream that represents the raw value of the stream property with that media type.
+Note this response format disregards any $format system query option.
+11.2.4.2 Requesting a Property's Raw Value using $value
To retrieve the raw value of a primitive type property, the client sends a GET request to the property value URL. See the OData-URL document 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 of this property (see OData-VocCore) if this annotation is present. If not annotated, the format cannot be predicted by the client.
@@ -1283,6 +1287,7 @@ OData-ABNF.
A $value request for a property that is null results in a 204 No Content response.
If the property is not available, for example due to permissions, the service responds with 404 Not Found.
+Appending /$value to the property URL of a property of type Edm.Stream returns 400 Bad Request.
Example 32:
GET http://host/service/Products(1)/Name/$value
@@ -1475,7 +1480,7 @@ 11.2.6.1.3 Parameter Aliases
-Parameter aliases can be used in place of literal values in entity keys, function parameters, or within a $compute, $filter or $orderby expression. Parameters aliases are names beginning with an at sign (@).
+Parameter aliases can be used in place of literal values in entity keys, 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"
@@ -1668,7 +1673,7 @@ GET http://host/service/Orders?$format=json
is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON.
-In metadata document requests, the values application/xml and application/json, along with their subtypes and parameterized variants, as well as the format-specific abbreviations xml and json, are reserved for this specification.
+In metadata document requests, the values application/xml and application/json, along with their subtypes and parameterized variants, as well as the format-specific abbreviations xml and json, are reserved for this specification.
11.2.12 System Query Option $schemaversion
The $schemaversion system query option MAY be included in any request. For a metadata document request the value of the $schemaversion system query option addresses a specific schema version. For all other request types the value specifies the version of the schema against which the request is made. The syntax of the $schemaversion system query option is defined in OData-ABNF.
The value of the $schemaversion system query option MUST be a version of the schema as returned in the Core.SchemaVersion annotation, defined in OData-VocCore, of a previous request to the metadata document, or * in order to specify the current version of the metadata.
@@ -1678,9 +1683,9 @@ 404 Not Found. The response body SHOULD provide additional information.
11.3 Requesting Changes
-
Services advertise their change-tracking capabilities by annotating entity sets with the Capabilities.ChangeTracking term defined in OData-VocCap.
+Services advertise their change-tracking capabilities by annotating entity sets with the Capabilities.ChangeTracking term defined in OData-VocCap.
Any GET request to retrieve one or more entities MAY allow change-tracking.
-Clients request that the service track changes to a result by specifying the track-changes preference on a request. If supported for the request, the service includes a Preference-Applied header in the response containing the track-changes preference and includes a delta link in a result for a single entity, and on the last page of results for a collection of entities in place of the next link.
+Clients request that the service track changes to a result by specifying the track-changes preference on a request. If supported for the request, the service includes a Preference-Applied header in the response containing the track-changes preference and includes a delta link in a result for a single entity, and on the last page of results for a collection of entities in place of the next link.
11.3.1 Delta Links
Delta links are opaque, service-generated links that the client uses to retrieve subsequent changes to a result.
Delta links are based on a defining query that describes the set of results for which changes are being tracked; for example, the request that generated the results containing the delta link. The delta link encodes the collection of entities for which changes are being tracked, along with a starting point from which to track changes. OData services may use the reserved system query option $deltatoken when building delta links. Its content is opaque, service-specific, and must only follow the rules for URL query parts.
@@ -1712,7 +1717,7 @@ 11.4.1.1 Use of ETags for Avoiding Update Conflicts
Each entity has its own ETag value that MUST change when structural properties or links from that entity have changed. In addition, modifying, adding, or deleting a contained entity MAY change the ETag of the parent entity.
Collections of entities (including collections of related entities) MAY have their own ETag value whose semantics is service-specific. It typically changes if entities are added to or removed from the collection, or if an entity in the collection is changed. The ETag of a collection of related entities reached via a navigation property MAY differ from the ETag of the entity containing the navigation property.
-A Data Modification Request on an existing resource or an Action Request invoking an action bound to an existing resource MAY require optimistic concurrency control. Services SHOULD announce this via annotations with the terms Core.OptimisticConcurrency in OData-VocCore and Capabilities.NavigationRestrictions (nested property OptimisticConcurrencyControl) in OData-VocCap.
+A Data Modification Request on an existing resource or an Action Request invoking an action bound to an existing resource MAY require optimistic concurrency control. Services SHOULD announce this via annotations with the terms Core.OptimisticConcurrency in OData-VocCore and Capabilities.NavigationRestrictions (nested property OptimisticConcurrencyControl) in OData-VocCap.
If optimistic concurrency control is required for a resource, the service MUST include an ETag header in a response to a GET request to the resource, and MAY include the ETag in a format-specific manner in responses containing that resource.
The presence of an ETag header in a response does not imply in itself that the resource requires optimistic concurrency control; the ETag may just be used for caching and/or conditional GET requests.
If an ETag value is specified in an If-Match or If-None-Match header of a Data Modification Request or Action Request, the operation MUST only be invoked if the If-Match or If-None-Match condition is satisfied.
@@ -1789,7 +1794,7 @@ 11.4.3 Update an Entity
To update an individual entity, the client makes a PATCH or PUT request to a URL that identifies the entity. Services MAY restrict updates only to requests addressing the edit URL of the entity.
Services SHOULD support PATCH as the preferred means of updating an entity. PATCH provides more resiliency between clients and services by directly modifying only those values specified by the client.
-The semantics of PATCH, as defined in RFC5789, is to merge the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of the corresponding property in the entity or complex type. Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties.
+The semantics of PATCH, as defined in RFC5789, is to merge the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of the corresponding property in the entity or complex type. Complex properties are updated by applying PATCH semantics recursively, see also section 11.4.9.3. Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties.
Services MAY additionally support PUT but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance, such as open or added properties, or properties not specified in metadata. Services that support PUT MUST replace all values of structural properties with those specified in the request body. Missing non-key, updatable structural properties not defined as dependent properties within a referential constraint MUST be set to their default values. Omitting a non-nullable property with no service-generated or default value from a PUT request results in a 400 Bad Request error. Missing dynamic structural properties MUST be removed or set to null.
For requests with an OData-Version header with a value of 4.01 or greater, the media stream of a media entity can be updated by specifying the base64url-encoded representation of the media stream as a virtual property $value.
Updating a dependent property that is tied to a key property of the principal entity through a referential constraint updates the relationship to point to the entity with the specified key value. If there is no such entity, the update fails.
@@ -1805,16 +1810,16 @@ delta payload representing the related entities that have been added, removed, or changed. Such a request is referred to as a "deep update". If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.
-Example 78: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
+Example 78: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
{
"@type":"#Northwind.Manager",
"FirstName" : "Patricia",
"DirectReports": [
{
- "@id": "Employees(5}"
+ "@id": "Employees(5)"
},
{
- "@id": "Employees(6}",
+ "@id": "Employees(6)",
"LastName": "Smith"
},
{
@@ -1908,7 +1913,7 @@ 11.4.7.1 Create a Media Entity
A POST request to a media entity's entity set creates a new media entity. The request body MUST contain the media value (for example, the photograph) whose media type MUST be specified in a Content-Type header. The request body is always interpreted as the media value, even if it has the media type of an OData format supported by the service. It is not possible to set the structural properties of the media entity when creating the media entity.
Upon successful completion, the response MUST contain Location header that contains the edit URL of the created media entity.
-Upon successful completion the service responds with either 201 Created, or 204 No Contentif the request included a Prefer header with a value of return=minimal.
+Upon successful completion the service responds with either 201 Created, or 204 No Content if the request included a Prefer header with a value of return=minimal.
11.4.7.2 Update a Media Entity Stream
A successful PUT request to the media edit URL of a media entity changes the media stream of the entity.
If the entity includes an ETag value for the media stream, the client MUST include an If-Match header with the ETag value.
@@ -1938,7 +1943,7 @@
Example 81: directly read a stream property of an entity
GET http://host/service/Products(1)/Thumbnail
-can return 200 OK and the stream data, or a 3xx Redirect to the media read link of the stream property.
+can return 200 OK and the stream data (see section 11.2.4.1), or a 3xx Redirect to the media read link of the stream property.
Note: for scenarios in which the media value can only be inlined, the property should instead be modeled with type Edm.Binary.
11.4.8.1 Update Stream Values
@@ -1971,8 +1976,9 @@ Updating a primitive property or a complex property with a null value also sets the property to null.
11.4.9.3 Update a Complex Property
-
A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the target complex type.
+A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the declared type of the complex property or one of its derived types.
The service MUST directly modify only those properties of the complex type specified in the payload of the PATCH request.
+If a complex-typed property is set to a different type in a PATCH request, properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.
The service MAY additionally support clients sending a PUT request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the request body and set all unspecified properties to their default value.
Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.
Services MUST return an error if the property is not updatable.
@@ -2114,7 +2120,7 @@ 11.5.4 FunctionsFunctions are operations exposed by an OData service that MUST return data and MUST have no observable side effects.
11.5.4.1 Invoking a Function
To invoke a function bound to a resource, the client issues a GET request to a function URL. A function URL may be obtained from a previously returned entity representation or constructed by appending the namespace- or alias-qualified function name to a URL that identifies a resource whose type is the same as, or derived from, the type of the binding parameter of the function. The value for the binding parameter is the value of the resource identified by the URL prior to appending the function name, and additional parameter values are specified using inline parameter syntax. If the function URL is obtained from a previously returned entity representation, parameter aliases that are identical to the parameter name preceded by an at (@) sign MUST be used. Clients MUST check if the obtained URL already contains a query part and appropriately precede the parameters either with an ampersand (&) or a question mark (?).
-Services MAY additionally support invoking functions using the unqualified function name by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore.
+Services MAY additionally support invoking functions using the unqualified function name by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore.
Functions can be used within $filter or $orderby system query options. Such functions can be bound to a resource, as described above, or called directly by specifying the namespace- (or alias-) qualified function name. Parameter values for functions within $filter or $orderby are specified according to the inline parameter syntax.
To invoke a function through a function import the client issues a GET request to a URL identifying the function import and passing parameter values using inline parameter syntax. The canonical URL for a function import is the service root, followed by the name of the function import. Services MAY support omitting the parentheses when invoking a function import with no parameters, but for maximum interoperability MUST also support invoking the function import with empty parentheses.
If the function is composable, additional path segments may be appended to the URL that identifies the composable function (or function import) as appropriate for the type returned by the function (or function import). The last path segment determines the system query options and HTTP verbs that can be used with this this URL, e.g. if the last path segment is a multi-valued navigation property, a POST request may be used to create a new entity in the identified collection.
@@ -2124,6 +2130,7 @@ requesting stream properties.
Parameter values passed to functions MUST be specified either as a URL literal (for primitive values) or as a JSON formatted OData object (for complex values, or collections of primitive or complex values). Entity typed values are passed as JSON formatted entities that MAY include a subset of the properties, or just the entity reference, as appropriate to the function.
If a collection-valued function has no result for a given parameter value combination, the response is the format-specific representation of an empty collection. If a single-valued function with a nullable return-type has no result, the service returns 204 No Content.
If a single-valued function with a non-nullable return type has no result, the service returns 4xx. For functions that return a single entity 404 Not Found is the appropriate response code.
@@ -2151,7 +2158,7 @@ Core.OptionalParameter defined in OData-VocCore MAY be omitted. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter.
+
Non-binding parameters annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter.
11.5.4.2 Function overload resolution
The same function name may be used multiple times within a schema, each with a different set of parameters. For unbound overloads the combination of the function name and the unordered set of parameter names MUST identify a particular function overload. For bound overloads the combination of the function name, the binding parameter type, and the unordered set of names of the non-binding parameters MUST identify a particular function overload.
All unbound overloads MUST have the same return type. Also, all bound overloads with a given binding parameter type MUST have the same return type.
@@ -2164,16 +2171,17 @@
Services SHOULD avoid ambiguity, i.e. the combination of the function name, the unordered set of non-optional non-binding parameter names, plus the binding parameter type for bound overloads SHOULD identify a particular function overload. If there is ambiguity, then services MAY return 400 Bad Request with an error response body stating that the request was ambiguous.
11.5.5 Actions
-Actions are operations exposed by an OData service that MAY have side effects when invoked. Actions MAY return data but MUST NOT be further composed with additional path segments.
+Actions are operations exposed by an OData service that MAY have side effects when invoked. Actions MAY return data but MUST NOT be further composed with additional path segments.
11.5.5.1 Invoking an Action
To invoke an action bound to a resource, the client issues a POST request to an action URL. An action URL may be obtained from a previously returned entity representation or constructed by appending the namespace- or alias-qualified action name to a URL that identifies a resource whose type is the same as, or derives from, the type of the binding parameter of the action. The value for the binding parameter is the resource identified by the URL preceding the action name, and only the non-binding parameter values are passed in the request body according to the particular format.
-Services MAY additionally support invoking actions using the unqualified action name by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore.
+Services MAY additionally support invoking actions using the unqualified action name by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore.
To invoke an action through an action import, the client issues a POST request to a URL identifying the action import. The canonical URL for an action import is the service root, followed by the name of the action import. When invoking an action through an action import all parameter values MUST be passed in the request body according to the particular format.
-Non-binding parameters that are nullable or annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the null value. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of null.
+Non-binding parameters that are nullable or annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the null value. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of null.
4.01 services MUST support invoking actions with no non-binding parameters and parameterless action imports both without a request body and with a request body representing no parameters, according to the particular format. Interoperable clients SHOULD always include a request body, even when invoking actions with no non-binding parameters and parameterless action imports.
If the action returns results, the client SHOULD use content type negotiation to request the results in the desired format, otherwise the default content type will be used.
The client can request whether any results from the action be returned using the return Prefer header.
Actions that create and return a single entity follow the rules for entity creation and return a Location header that contains the edit URL or read URL of the created entity.
+If the action returns a value of type Edm.Stream, the response to the POST request follows the rules for requesting stream properties.
Actions without a return type respond with 204 No Content on success.
To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.
@@ -2244,7 +2252,7 @@ 11.7.4 Referencing Returned Entities
Entities created by an insert request can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. If the Location header in the response contains a relative URL, clients MUST be able to resolve it relative to the request's URL even if that contains such a reference.
-If the $-prefixed request identifier is 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 the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.
+If the $-prefixed request identifier is 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 the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.
Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the ReferencesInRequestBodiesSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.
11.7.5 Referencing the ETag of an Entity
Services MAY support the use of an ETag returned from a previous operation in an If-Match or If-None-Match header of a subsequent statement. Services SHOULD advertise this support by specifying the EtagReferencesSupported property in the Capabilities.BatchSupport annotation term applied to the entity container, see OData-VocCap.
@@ -2432,7 +2440,7 @@ continue-on-error preference is specified with an explicit or implicit value of true.
All requests in a change set represent a single change unit so a service MUST successfully process and apply all the requests in the change set or else apply none of them. It is up to the service implementation to define rollback semantics to undo any requests within a change set that may have been applied before another request in that same change set failed and thereby apply this all-or-nothing requirement. The service MAY execute the requests within a change set in any order and MAY return the responses to the individual requests in any order. If a request specifies a request identifier, the service MUST include the Content-ID header with the request identifier in the corresponding response so clients can correlate requests and responses.
11.7.7.5 Multipart Batch Response
-A multipart response to a batch request MUST contain a Content-Type header with value multipart/mixed.
+A multipart response to a batch request MUST contain a Content-Type header with value multipart/mixed.
The body of a multipart response to a multipart batch request MUST structurally match one-to-one with the multipart batch request body, such that the same multipart message structure defined for requests is used for responses. There are three exceptions to this rule:
- When a request within a change set fails, the change set response is not represented using the
multipart/mixed media type. Instead, a single response, using the application/http media type, is returned that applies to all requests in the change set and MUST be a valid OData error response.
@@ -2628,7 +2636,7 @@ section 11.2.5.1)
- MUST support casting to a derived type according to OData-URL if derived types are present in the model
- MUST support
$top (section 11.2.6.3)
-- MUST support
/$value on media entities (section 11.1.2) and individual properties (section 11.2.4.1)
+- MUST support
/$value on media entities (section 11.1.2) and individual properties (section 11.2.4.2)
- MUST support
$filter (section 11.2.6.1)
- MUST support
eq, ne filter operations on properties of entities in the requested entity set (section 11.2.6.1.1)
@@ -2658,13 +2666,13 @@ OData-URL)
- MUST support the
$skip system query option (section 11.2.6.4)
- MUST support the
$count system query option (section 11.2.6.5)
-- MUST support
$orderby asc and desc on individual properties (section 11.2.6.2)
+- MUST support
$orderby with asc and desc on individual properties (section 11.2.6.2)
- MUST support
$expand (section 11.2.5.2)
- MUST support returning references for expanded properties
- MUST support
$filter on expanded collection-valued properties
- MUST support cast segment in expand with derived types
-- SHOULD support
$orderby asc and desc on expanded collection-valued properties
+- SHOULD support
$orderby with asc and desc on expanded collection-valued properties
- SHOULD support
$count on expanded collection-valued properties
- SHOULD support
$top and $skip on expanded collection-valued properties
- SHOULD support
$search on expanded collection-valued properties
@@ -2740,7 +2748,7 @@ OData 4.01 Minimal Conformance Level
- MUST conform to the OData 4.0 Intermediate Conformance Level
- MUST support
eq/ne null comparison for navigation properties with a maximum cardinality of one
-- MUST support the
in operator
+- MUST support the
in operator
- MUST support the
$select option nested within $select
- SHOULD support the count of a filtered collection in a common expression
- SHOULD support equal and non-equal structural comparison
@@ -2759,7 +2767,7 @@
- MUST support
$filter on selected collection-valued properties
-- SHOULD support
$orderby asc and desc on selected collection-valued properties
+- SHOULD support
$orderby with asc and desc on selected collection-valued properties
- SHOULD support the
$count on selected collection-valued properties
- SHOULD support
$top and $skip on selected collection-valued properties
- SHOULD support
$search on selected collection-valued properties
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 5971c1bd9..cbe3a58ac 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -204,7 +204,8 @@ For complete copyright information please see the full Notices section in an App
- [11.2.2 Requesting Individual Entities](#RequestingIndividualEntities)
- [11.2.3 Requesting the Media Stream of a Media Entity using `$value`](#RequestingtheMediaStreamofaMediaEntityusingvalue)
- [11.2.4 Requesting Individual Properties](#RequestingIndividualProperties)
- - [11.2.4.1 Requesting a Property's Raw Value using `$value`](#RequestingaPropertysRawValueusingvalue)
+ - [11.2.4.1 Requesting Stream Properties](#RequestingStreamProperties)
+ - [11.2.4.2 Requesting a Property's Raw Value using `$value`](#RequestingaPropertysRawValueusingvalue)
- [11.2.5 Specifying Properties to Return](#SpecifyingPropertiestoReturn)
- [11.2.5.1 System Query Option `$select`](#SystemQueryOptionselect)
- [11.2.5.2 System Query Option `$expand`](#SystemQueryOptionexpand)
@@ -1044,7 +1045,7 @@ As defined in [RFC9110](#rfc9110), a client MAY include an
value previously retrieved for the resource, or `*` to match any value.
If an operation on an existing resource requires an ETag, (see term
-[`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency)` `in
+[`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in
[OData-VocCore](#ODataVocCore) and property
`OptimisticConcurrencyControl` of type
[`Capabilities.NavigationPropertyRestriction`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#NavigationPropertyRestriction)
@@ -1516,7 +1517,7 @@ A preference of `return=minimal` requests that the service invoke the
request but does not return content in the response. The service MAY
apply this preference by returning
[`204 No Content`](#ResponseCode204NoContent) in which case it MAY
-include a [`Preference-Applied`](#HeaderPreferenceApplied)` `response
+include a [`Preference-Applied`](#HeaderPreferenceApplied) response
header containing the `return=minimal `preference.
A preference of `return=representation` requests that the service
@@ -1547,7 +1548,7 @@ requests within the batch request.
In the case that the service applies the `respond-async` preference it
MUST include a
-[`Preference-Applied`](#HeaderPreferenceApplied)` `response header
+[`Preference-Applied`](#HeaderPreferenceApplied) response header
containing the `respond-async` preference.
A service MAY specify the support for the `respond-async` preference
@@ -2692,7 +2693,7 @@ Properties that are not available, for example due to permissions, are
not returned. In this case, the
[`Core.Permissions`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#Permissions)
annotation, defined in [OData-VocCore](#ODataVocCore) MUST be returned
-for the property with a value of `None.`
+for the property with a value of `None`.
If no entity exists with the specified request URL, the service responds
with [`404 Not Found`](#ResponseCode404NotFound).
@@ -2710,12 +2711,17 @@ entity is the main topic of interest and the stream data is just
additional information attached to the structured data.
To address the media stream represented by a media entity, clients
-append `/$value` to the resource path of the media entity URL. Services
-may redirect from this canonical URL to the source URL of the media
+append `/$value` to the resource path of the media entity URL.
+The media type of the response is the
+media type of the stream, subject to content type negotiation based on the
+[`Accept`](#HeaderAccept) header of the request.
+The response body is the octet-stream that represents the raw
+value of the media stream with that media type. Alternatively, services
+MAY redirect from this canonical URL to the source URL of the media
stream.
Appending `/$value` to an entity that is not a media entity returns
-`400 Bad Request.`
+`400 Bad Request`.
Attempting to retrieve the media stream from a single-valued navigation
property referencing a media entity whose value is null returns
@@ -2745,7 +2751,19 @@ GET http://host/service/Products(1)/Name
```
:::
-#### 11.2.4.1 Requesting a Property's Raw Value using `$value`
+#### 11.2.4.1 Requesting Stream Properties
+
+If the property being requested has type `Edm.Stream` (see
+[OData-URL, section 9](#ODataURL)), the media type of the response is the
+media type of the stream, subject to content type negotiation based on the
+[`Accept`](#HeaderAccept) header of the request.
+The response body is the octet-stream that represents the raw
+value of the stream property with that media type.
+
+Note this response format disregards any [`$format`](#SystemQueryOptionformat)
+system query option.
+
+#### 11.2.4.2 Requesting a Property's Raw Value using `$value`
To retrieve the raw value of a primitive type property, the client sends
a `GET` request to the property value URL. See the
@@ -2784,6 +2802,9 @@ A `$value` request for a property that is `null` results in a
If the property is not available, for example due to permissions, the
service responds with [`404 Not Found`](#ResponseCode404NotFound).
+Appending `/$value` to the property URL of a property of type `Edm.Stream`
+returns `400 Bad Request`.
+
::: example
Example 32:
```
@@ -3191,7 +3212,7 @@ a `null` literal that can be used in comparisons.
Parameter aliases can be used in place of literal values in entity keys,
[function parameters](#InvokingaFunction), or within a
-[`$compute`](#SystemQueryOptioncompute)`,`
+[`$compute`](#SystemQueryOptioncompute),
[`$filter`](#SystemQueryOptionfilter) or
[`$orderby`](#SystemQueryOptionorderby) expression. Parameters aliases
are names beginning with an at sign (`@`).
@@ -3736,7 +3757,7 @@ using the JSON media type with minimal metadata, as defined in
In [metadata document requests](#MetadataDocumentRequest), the values
`application/xml` and `application/json`, along with their subtypes and
parameterized variants, as well as the format-specific abbreviations
-`xml` and `json,` are reserved for this specification.
+`xml` and `json`, are reserved for this specification.
### 11.2.12 System Query Option `$schemaversion`
@@ -3788,7 +3809,7 @@ body SHOULD provide additional information.
Services advertise their change-tracking capabilities by annotating
entity sets with the
-[`Capabilities`.`ChangeTracking`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#ChangeTracking)
+[`Capabilities.ChangeTracking`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#ChangeTracking)
term defined in [OData-VocCap](#ODataVocCap).
Any `GET` request to retrieve one or more entities MAY allow
@@ -3797,7 +3818,7 @@ change-tracking.
Clients request that the service track changes to a result by specifying
the [`track-changes`](#Preferencetrackchangesodatatrackchanges) preference
on a request. If supported for the request, the service includes a
-[`Preference-Applied`](#HeaderPreferenceApplied)` `header in the
+[`Preference-Applied`](#HeaderPreferenceApplied) header in the
response containing the `track-changes` preference and includes a *delta
link* in a result for a single entity, and on the last page of results
for a collection of entities in place of the next link.
@@ -3960,7 +3981,7 @@ A [Data Modification Request](#DataModification) on an existing resource
or an [Action Request](#Actions) invoking an action bound to an existing
resource MAY require optimistic concurrency control. Services SHOULD
announce this via annotations with the terms
-[`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency)` `in
+[`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in
[OData-VocCore](#ODataVocCore) and
[`Capabilities.NavigationRestrictions`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#NavigationRestrictions)
(nested property `OptimisticConcurrencyControl`) in
@@ -4241,8 +4262,10 @@ the content in the request payload with the entity's current state,
applying the update only to those components specified in the request
body. Collection properties and primitive properties provided in the
payload corresponding to updatable properties MUST replace the value of
-the corresponding property in the entity or complex type. Missing
-properties of the containing entity or complex property, including
+the corresponding property in the entity or complex type.
+Complex properties are updated by applying `PATCH` semantics recursively,
+see also [section 11.4.9.3](#UpdateaComplexProperty).
+Missing properties of the containing entity or complex property, including
dynamic properties, MUST NOT be directly altered unless as a side effect
of changes resulting from the provided properties.
@@ -4349,17 +4372,17 @@ NOT include added links, deleted links, or deleted entities.
Example 78: using the JSON format, a 4.01 `PATCH` request can update a
manager entity. Following the update, the manager has three direct
reports; two existing employees and one new employee named
-`Suzanne Brown`. The `LastName` of employee `6` is updated to `Smith.`
+`Suzanne Brown`. The `LastName` of employee 6 is updated to `Smith`.
```json
{
"@type":"#Northwind.Manager",
"FirstName" : "Patricia",
"DirectReports": [
{
- "@id": "Employees(5}"
+ "@id": "Employees(5)"
},
{
- "@id": "Employees(6}",
+ "@id": "Employees(6)",
"LastName": "Smith"
},
{
@@ -4619,8 +4642,8 @@ entity.
Upon successful completion the service responds with either
[`201 Created`](#ResponseCode201Created), or
-[`204 No Content`](#ResponseCode204NoContent)if the request included a
-[Prefer header](#Preferencereturnrepresentationandreturnminimal) with a value of
+[`204 No Content`](#ResponseCode204NoContent) if the request included a
+[`Prefer` header](#Preferencereturnrepresentationandreturnminimal) with a value of
[`return=minimal`](#Preferencereturnrepresentationandreturnminimal).
#### 11.4.7.2 Update a Media Entity Stream
@@ -4688,7 +4711,8 @@ Example 81: directly read a stream property of an entity
```
GET http://host/service/Products(1)/Thumbnail
```
-can return [`200 OK`](#ResponseCode200OK) and the stream data, or a [`3xx Redirect`](#ResponseCode3xxRedirection) to the media read link of the stream property.
+can return [`200 OK`](#ResponseCode200OK) and the stream data (see [section 11.2.4.1](#RequestingStreamProperties)),
+or a [`3xx Redirect`](#ResponseCode3xxRedirection) to the media read link of the stream property.
:::
Note: for scenarios in which the media value can only be inlined,
@@ -4802,11 +4826,15 @@ property to null.
A successful `PATCH` request to the edit URL for a complex typed
property updates that property. The request body MUST contain a single
-valid representation for the target complex type.
+valid representation for the declared type of the complex property or one of its derived types.
The service MUST directly modify only those properties of the complex
type specified in the payload of the `PATCH` request.
+If a complex-typed property is set to a different type in a `PATCH` request,
+properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload).
+Other properties of the original type are discarded.
+
The service MAY additionally support clients sending a `PUT` request to
a URL that specifies a complex type. In this case, the service MUST
replace the entire complex property with the values specified in the
@@ -5248,7 +5276,7 @@ ampersand (`&`) or a question mark (`?`).
Services MAY additionally support invoking functions using the
unqualified function name by defining one or more [default
namespaces](#DefaultNamespaces) through the
-[`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DefaultNamespace)` `term
+[`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term
defined in [OData-VocCore](#ODataVocCore).
Functions can be used within [`$filter`](#SystemQueryOptionfilter) or
@@ -5287,6 +5315,10 @@ POST http://host/service/MyShoppingCart()/Items
```
:::
+If the function returns a value of type `Edm.Stream` and no additional path
+segments follow the function invocation, the response to the `GET` request
+follows the rules for [requesting stream properties](#RequestingStreamProperties).
+
Parameter values passed to functions MUST be specified either as a URL
literal (for primitive values) or as a JSON formatted OData object (for
complex values, or collections of primitive or complex values). Entity
@@ -5374,7 +5406,7 @@ GET http://host/service/EmployeesByManager?ManagerID=3
:::
Non-binding parameters annotated with the term
-[`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter)` `defined
+[`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter) defined
in [OData-VocCore](#ODataVocCore) MAY be omitted. If it is annotated and
the annotation specifies a `DefaultValue`, the omitted parameter is
interpreted as having that default value. If omitted and the annotation
@@ -5424,7 +5456,7 @@ request was ambiguous.
### 11.5.5 Actions
Actions are operations exposed by an OData service that MAY have side
-effects when invoked. Actions MAY return data but` `MUST NOT be further
+effects when invoked. Actions MAY return data but MUST NOT be further
composed with additional path segments.
#### 11.5.5.1 Invoking an Action
@@ -5443,7 +5475,7 @@ according to the particular format.
Services MAY additionally support invoking actions using the unqualified
action name by defining one or more [default
namespaces](#DefaultNamespaces) through the
-[`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DefaultNamespace)` `term
+[`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term
defined in [OData-VocCore](#ODataVocCore).
To invoke an action through an action import, the client issues a `POST`
@@ -5454,7 +5486,7 @@ values MUST be passed in the request body according to the particular
format.
Non-binding parameters that are nullable or annotated with the term
-[`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter)` `defined
+[`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter) defined
in [OData-VocCore](#ODataVocCore) MAY be omitted from the request body.
If an omitted parameter is not annotated (and thus nullable), it MUST be
interpreted as having the `null` value. If it is annotated and the
@@ -5484,6 +5516,9 @@ Actions that create and return a single entity follow the rules for
header](#HeaderLocation) that contains the edit URL or read URL of the
created entity.
+If the action returns a value of type `Edm.Stream`, the response to the `POST` request
+follows the rules for [requesting stream properties](#RequestingStreamProperties).
+
Actions without a return type respond with
[`204 No Content`](#ResponseCode204NoContent) on success.
@@ -5713,7 +5748,7 @@ clients MUST be able to resolve it relative to the request's URL even if
that contains such a reference.
If the `$`-prefixed request identifier is identical to the name of a
-top-level system resource (`$batch`, `$crossjoin,` `$all,` `$entity`,
+top-level system resource (`$batch`, `$crossjoin`, `$all`, `$entity`,
`$root`, `$id`, `$metadata`, or other system resources defined according
to the [`OData-Version`](#HeaderODataVersion) of the protocol specified
in the request), then the reference to the top-level system resource is
@@ -6022,7 +6057,7 @@ response so clients can correlate requests and responses.
#### 11.7.7.5 Multipart Batch Response
A multipart response to a batch request MUST contain a `Content-Type`
-header with value `multipart/mixed.`
+header with value `multipart/mixed`.
The body of a multipart response to a multipart batch request MUST
structurally match one-to-one with the multipart batch request body,
@@ -6359,7 +6394,7 @@ unsupported functionality ([section 9.3.1](#ResponseCode501NotImplemented))
4. MUST support casting to a derived type according to
[OData-URL](#ODataURL) if derived types are present in the model
5. MUST support `$top` ([section 11.2.6.3](#SystemQueryOptiontop))
-6. MUST support `/$value` on media entities ([section 11.1.2](#MetadataDocumentRequest)) and individual properties ([section 11.2.4.1](#RequestingaPropertysRawValueusingvalue))
+6. MUST support `/$value` on media entities ([section 11.1.2](#MetadataDocumentRequest)) and individual properties ([section 11.2.4.2](#RequestingaPropertysRawValueusingvalue))
7. MUST support `$filter` ([section 11.2.6.1](#SystemQueryOptionfilter))
1. MUST support `eq`, `ne` filter operations on properties of entities
in the requested entity set ([section 11.2.6.1.1](#BuiltinFilterOperations))
@@ -6405,13 +6440,13 @@ collection-valued properties (section 5.1.1.10 in
[OData-URL](#ODataURL))
6. MUST support the `$skip` system query option ([section 11.2.6.4](#SystemQueryOptionskip))
7. MUST support the `$count` system query option ([section 11.2.6.5](#SystemQueryOptioncount))
-8. MUST support `$orderby` `asc` and `desc` on individual properties
+8. MUST support `$orderby` with `asc` and `desc` on individual properties
([section 11.2.6.2](#SystemQueryOptionorderby))
9. MUST support `$expand` ([section 11.2.5.2](#SystemQueryOptionexpand))
1. MUST support returning references for expanded properties
2. MUST support `$filter` on expanded collection-valued properties
3. MUST support cast segment in expand with derived types
- 4. SHOULD support `$orderby` `asc` and `desc` on expanded
+ 4. SHOULD support `$orderby` with `asc` and `desc` on expanded
collection-valued properties
5. SHOULD support `$count` on expanded collection-valued properties
6. SHOULD support `$top` and `$skip` on expanded collection-valued
@@ -6539,7 +6574,7 @@ Level](#OData401MinimalConformanceLevel)
Level](#OData40IntermediateConformanceLevel)
3. MUST support `eq/ne null` comparison for navigation properties with
a maximum cardinality of one
-4. MUST support the [`in`](#BuiltinFilterOperations)` `operator
+4. MUST support the [`in`](#BuiltinFilterOperations) operator
5. MUST support the `$select` option nested within `$select`
6. SHOULD support the count of a filtered collection in a common
expression
@@ -6564,7 +6599,7 @@ expression
4. MUST support `$compute` system query option
5. MUST support nested options in `$select`
1. MUST support `$filter` on selected collection-valued properties
- 2. SHOULD support `$orderby` `asc` and `desc` on selected
+ 2. SHOULD support `$orderby` with `asc` and `desc` on selected
collection-valued properties
3. SHOULD support the `$count` on selected collection-valued
properties
diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html
index 64222437b..f38c5e9b7 100644
--- a/docs/odata-url-conventions/odata-url-conventions.html
+++ b/docs/odata-url-conventions/odata-url-conventions.html
@@ -678,7 +678,7 @@ 4.5 Addressing Operations
The semantic rules for addressing and invoking actions and functions are defined in the OData-Protocol document.
-Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.
+Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.
4.5.1 Addressing Actions
The grammar for addressing and invoking actions is defined by the following syntax grammar rules in OData-ABNF:
@@ -798,7 +798,7 @@ 4.15 Addressing the Cross Join of Entity Sets
In addition to querying related entities through navigation properties defined in the entity model of a service, the cross join operator allows querying across unrelated entity sets.
The cross join is addressed by appending the path segment $crossjoin to the service root URL, followed by the parenthesized comma-separated list of joined entity sets. It returns the Cartesian product of all the specified entity sets, represented as a collection of instances of a virtual complex type. Each instance consists of one non-nullable, single-valued navigation property per joined entity set. Each such navigation property is named identical to the corresponding entity set, with a target type equal to the declared entity type of the corresponding entity set.
-The $filter and $orderby query options can be specified using properties of the entities in the selected entity sets, prepended with the entity set as the navigation property name.
+The $filter and $orderby query options can be specified using properties of the entities in the selected entity sets, prepended with the entity set as the navigation property name.
The $expand query option can be specified using the names of the selected entity sets as navigation property names. If a selected entity set is not expanded, it MUST be represented using the read URL of the related entity as a navigation link in the complex type instance.
The $count, $skip, and $top query options can also be used with no special semantics.
@@ -997,7 +997,7 @@ 5.1.1.2.2 S
For operands of type Edm.Decimal the scale of the result is \({\rm scaleof}(A {\ \tt sub\ } B) = \max({\rm scaleof}(A), {\rm scaleof}(B))\), or variable if any operand has variable scale.
The sub operator is also valid for the following time-related operands:
-DateTimeOffset sub Duration results in a DateTimeOffsetDateTimeOffset sub Duration results in a DateTimeOffsetDuration sub Duration results in a DurationDateTimeOffset sub DateTimeOffset results in a DurationDate sub Duration results in a DateCore.Messages annotation
http://host/service/Employees?$filter=@Core.Messages/any(m:m/severity eq 'error')
-Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.
+Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.
5.1.1.17 Operator Precedence
OData services MUST use the following operator precedence for supported operators when evaluating $filter and $orderby expressions. Operators are listed by category in order of precedence from highest to lowest. Operators in the same category have equal precedence: