OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL.
This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the "Latest stage" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical.
-TC members should send comments on this specification to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "Send A Comment" button on the TC's web page at https://www.oasis-open.org/committees/odata/.
-This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC's web page (https://www.oasis-open.org/committees/odata/ipr.php).
-Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
+This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the “Latest stage” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical.
+TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/odata/.
+This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/odata/ipr.php).
+Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product’s prose narrative document(s), the content in the separate plain text file prevails.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.
When referencing this specification the following citation format should be used:
[OData-CSDL-JSON-v4.02]
@@ -155,7 +155,7 @@Copyright © OASIS Open 2023. All Rights Reserved.
Distributed under the terms of the OASIS IPR Policy.
-The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.
+The name “OASIS” is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.
For complete copyright information please see the full Notices section in an Appendix below.
OData services are described in terms of an Entity Model. The Common Schema Definition Language (CSDL) defines a representation of the entity model exposed by an OData service using the JavaScript Object Notation (JSON), see RFC8259.
This format is based on the OpenUI5 OData V4 Metadata JSON Format, see OpenUI5, with some extensions and modifications made necessary to fully cover OData CSDL Version 4.01.
| Section | +Feature / Change | +Issue | +
|---|---|---|
| Section 14.4.1.2 | +New path evaluation rules for annotations targeting annotations and external targeting via container | +ODATA-1420 | +
All other text is normative unless otherwise labeled.
Here is a customized command line which will generate HTML from this markdown file (named odata-csdl-json-v4.02-csd01.md). Line breaks are added for readability only:
pandoc -f gfm+tex_math_dollars+fenced_divs
+pandoc -f gfm+tex_math_dollars+fenced_divs+smart
-t html
-o odata-csdl-json-v4.02-csd01.html
-c styles/markdown-styles-v1.7.3b.css
@@ -410,7 +426,7 @@ Representation-Specific Headline
2 JSON Representation
-OData CSDL JSON is a full representation of the OData Common Schema Definition Language in the JavaScript Object Notation (JSON) defined in RFC8259. It additionally follows the rules for "Internet JSON" (I-JSON) defined in RFC7493 for e.g. objects, numbers, date values, and duration values.
+OData CSDL JSON is a full representation of the OData Common Schema Definition Language in the JavaScript Object Notation (JSON) defined in RFC8259. It additionally follows the rules for “Internet JSON” (I-JSON) defined in RFC7493 for e.g. objects, numbers, date values, and duration values.
It is an alternative to the CSDL XML representation defined in OData-CSDLXML and neither adds nor removes features.
2.1 Requesting the JSON Representation
The OData CSDL JSON representation can be requested using the $format query option in the request URL with the media type application/json, optionally followed by media type parameters, or the case-insensitive abbreviation json which MUST NOT be followed by media type parameters.
@@ -447,7 +463,7 @@ 2.1.2.3 <
The metadata=none format parameter indicates that the service SHOULD omit all control information.
2.2 Design Considerations
CSDL JSON documents are designed for easy and efficient lookup of model constructs by their name without having to know or guess what kind of model element it is. Thus, all primary model elements (entity types, complex types, type definitions, enumeration types, terms, actions, functions, and the entity container) are direct members of their schema, using the schema-unique name as the member name. Similarly, child elements of primary model elements (properties, navigation properties, enumeration type members, entity sets, singletons, action imports, and function imports) are direct members of the objects describing their parent model element, using their locally unique name as the member name.
-To avoid name collisions, all fixed member names are prefixed with a dollar ($) sign and otherwise have the same name and capitalization as their counterparts in the CSDL XML representation OData-CSDLXML (with one exception: the counterpart of the EntitySet element's EntityType member is $Type, to harmonize it with all other type references).
+To avoid name collisions, all fixed member names are prefixed with a dollar ($) sign and otherwise have the same name and capitalization as their counterparts in the CSDL XML representation OData-CSDLXML (with one exception: the counterpart of the EntitySet element’s EntityType member is $Type, to harmonize it with all other type references).
Additional fixed members introduced by this specification and without counterpart in OData-CSDLXML are also prefixed with a dollar ($) sign and use upper-camel-case names. One of these is $Kind which represents the kind of model element. Its value is the upper-camel-case local name of the XML element representing this kind of model element in OData-CSDLXML, e.g. EntityType or NavigationProperty.
While the XML representation of CSDL allows referencing model elements with alias-qualified names as well as with namespace-qualified names, this JSON representation requires the use of alias-qualified names if an alias is specified for an included or document-defined schema. Aliases are usually shorter than namespaces, so this reduces text size of the JSON document. Text size matters even if the actual HTTP messages are sent in compressed form because the decompressed form needs to be reconstructed, and clients not using a streaming JSON parser have to materialize the full JSON document before parsing.
To further reduce size the member $Kind is optional for structural properties as these are more common than navigation properties, and the member $Type is optional for string properties, parameters, and return types, as this type is more common than other primitive types.
@@ -508,7 +524,7 @@ 3.3
Edm.DoubleIEEE 754 binary64 floating-point number (15-17 decimal digits)
+IEEE 754 binary64 floating-point number (15–17 decimal digits)
Edm.Duration3.3
Edm.SingleIEEE 754 binary32 floating-point number (6-9 decimal digits)
+IEEE 754 binary32 floating-point number (6–9 decimal digits)
Edm.Stream3.3
Edm.TimeOfDayClock time 00:00-23:59:59.999999999999
+Clock time 00:00–23:59:59.999999999999
Edm.Geography3.3
Edm.Date and Edm.DateTimeOffset follow XML-Schema-2 and use the proleptic Gregorian calendar, allowing the year 0000 (equivalent to 1 BCE) and negative years (year -0001 being equivalent to 2 BCE etc.). The supported date range is service-specific and typically depends on the underlying persistency layer, e.g. SQL only supports years 0001 to 9999.
Edm.Decimal with a Scale value of floating, Edm.Double, and Edm.Single allow the special numeric values -INF, INF, and NaN.
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".
+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 Members
+ $MaxLength
+The value of $MaxLength is a positive integer.
+Note: OData-CSDL-XML defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.
+
+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.
+
+ $Precision
+The value of $Precision is a number.
+Absence of $Precision means unspecified precision both for decimal and temporal values.
+
+
+Example 2: Precision facet applied to the DateTimeOffset type
+"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 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.
+
+ $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.
+
+
+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"
+}
+
+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.
+
+ $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.
+
+ $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.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
+
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” for details.
+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.
@@ -682,54 +790,54 @@
- Document Object
+ Document Object
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
+ $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.
-Example 2:
-{
- "$Version": "4.01",
- "$EntityContainer": "org.example.DemoService",
- ...
-}
+Example 7:
+{
+ "$Version": "4.01",
+ "$EntityContainer": "org.example.DemoService",
+ ...
+}
4.1 Reference
-A reference to an external CSDL document allows to bring part of the referenced document's content into the scope of the referencing document.
+A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.
A reference MUST specify a URI that uniquely identifies the referenced document, so two references MUST NOT specify the same URI. The URI SHOULD be a URL that locates the referenced document. If the URI is not dereferencable it SHOULD identify a well-known schema. The URI MAY be absolute or relative URI; relative URLs are relative to the URL of the document containing the reference, or relative to a base URL specified in a format-specific way.
A reference MAY be annotated.
The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined OData-Protocol, SHOULD be used when retrieving the referenced schema document.
- $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 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": {
+ ...
+ }
+ },
+ ...
+}
4.2 Included Schema
A reference MAY include zero or more schemas from the referenced document.
@@ -742,93 +850,93 @@ 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.
- $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.
- $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.
-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"
+ }
+ ]
+ }
+ },
+ ...
+}
4.3 Included Annotations
In addition to including whole schemas with all model constructs defined within that schema, a reference may include annotations.
-Annotations are selectively included by specifying the namespace of the annotations' term. Consumers can opt not to inspect the referenced document if none of the term namespaces is of interest for the consumer.
+Annotations are selectively included by specifying the namespace of the annotations’ term. Consumers can opt not to inspect the referenced document if none of the term namespaces is of interest for the consumer.
In addition, the qualifier of annotations to be included MAY be specified. For instance, a service author might want to supply a different set of annotations for various device form factors. If a qualifier is specified, only those annotations from the specified term namespace with the specified qualifier (applied to a model element of the target namespace, if present) SHOULD be included. If no qualifier is specified, all annotations within the referenced document from the specified term namespace (taking into account the target namespace, if present) SHOULD be included.
The qualifier also provides consumers insight about what qualifiers are present in the referenced document. If the consumer is not interested in that particular qualifier, the consumer can opt not to inspect the referenced document.
-In addition, the namespace of the annotations' 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.
+In addition, the namespace of the annotations’ 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.
- $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.
-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:
@@ -843,11 +951,11 @@ 5 Schema
One or more schemas describe the entity model exposed by an OData service. The schema acts as a namespace for elements of the entity model such as entity types, complex types, enumerations and terms.
A schema is identified by a namespace. Schema namespaces MUST be unique within the scope of a document and SHOULD be globally unique. A schema cannot span more than one document.
-The schema's namespace is combined with the name of elements in the schema to create unique qualified names, so identifiers that are used to name types MUST be unique within a namespace to prevent ambiguity.
+The schema’s namespace is combined with the name of elements in the schema to create unique qualified names, so identifiers that are used to name types MUST be unique within a namespace to prevent ambiguity.
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.
- 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 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.
@@ -858,92 +966,92 @@ 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.
- $Alias
+ $Alias
The 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",
+ ...
+ },
+ ...
+}
5.2 Annotations with External Targeting
- $Annotations
+ $Annotations
The 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",
+ ...
+ }
+ }
+}
6 Entity Type
Entity types are nominal structured types with a key that consists of one or more references to structural properties. An entity type is the template for an entity: any uniquely identifiable record such as a customer or order.
-The entity type's name is a simple identifier that MUST be unique within its schema.
+The entity type’s name is a simple identifier that MUST be unique within its schema.
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.
- 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 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"
+ }
+}
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.
- $BaseType
+ $BaseType
The 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.
@@ -953,7 +1061,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.
- $Abstract
+ $Abstract
The value of $Abstract is one of the Boolean literals true or false. Absence of the member means false.
6.3 Open Entity Type
@@ -961,7 +1069,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.
- $OpenType
+ $OpenType
The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.
6.4 Media Entity Type
@@ -969,15 +1077,15 @@
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
-The value of $HasStream is one of the Boolean literals true or false. Absence of the member means false.
+ $HasStream
+The value of $HasStream is one of the Boolean literals true or false. Absence of the member means false.
6.5 Key
An entity is uniquely identified within an entity set by its key. A key MAY be specified if the entity type does not specify a base type that already has a key declared.
In order to be specified as the type of an entity set or a collection-valued containment navigation property, the entity type MUST either specify a key or inherit its key from its base type.
In OData 4.01 responses entity types used for singletons or single-valued navigation properties do not require a key. In OData 4.0 responses entity types used for singletons or single-valued navigation properties MUST have a key defined.
-An entity type (whether or not it is marked as abstract) MAY define a key only if it doesn't inherit one.
-An entity type's key refers to the set of properties whose values uniquely identify an instance of the entity type within an entity set. The key MUST consist of at least one property.
+An entity type (whether or not it is marked as abstract) MAY define a key only if it doesn’t inherit one.
+An entity type’s key refers to the set of properties whose values uniquely identify an instance of the entity type within an entity set. The key MUST consist of at least one property.
Key properties MUST NOT be nullable and MUST be typed with an enumeration type, one of the following primitive types, or a type definition based on one of these primitive types:
Edm.Boolean6.5 Key
In OData 4.01 the key properties of a directly related entity type MAY also be part of the key if the navigation property is single-valued and not nullable. This includes navigation properties of non-nullable single-valued complex properties (recursively) of the entity type. If a key property of a related entity type is part of the key, all key properties of the related entity type MUST also be part of the key.
If the key property is a property of a complex property (recursively) or of a directly related entity type, the key MUST specify an alias for that property that MUST be a simple identifier and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.
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.
+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
+ $Key
The 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 100
@@ -1083,164 +1191,68 @@ type.
-
The property's name MUST be a 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.
+The property’s name MUST be a 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.
- Property Object
+ Property Object
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
+ }
+}
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.
+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
-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 qualified name of the property's item type, and the member $Collection MUST be present with the literal value true.
+ $Type and $Collection
+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 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
+}
-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.
- $Nullable
+ $Nullable
The 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.
-
-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.
-
- $MaxLength
-The value of $MaxLength is a positive integer.
-Note: OData-CSDL-XML defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.
-
-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.
-
- $Precision
-The 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
-}
-
-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.
-
- $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.
+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"
-}
-
-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.
-
- $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.
-
- $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 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.
- $DefaultValue
+ $DefaultValue
The value of $DefaultValue is the type-specific JSON representation of the default value of the property, see OData-JSON. For properties of type Edm.Decimal and Edm.Int64 the representation depends on the media type parameter IEEE754Compatible.
8 Navigation Property
A navigation property allows navigation to related entities. It MUST specify a unique name as well as a type.
-The navigation property's name MUST be a 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.
+The navigation property’s name MUST be a 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.
8.1 Navigation Property Type
-The navigation property's type MUST be an entity type in scope, the abstract type Edm.EntityType, or a collection of one of these types.
+The navigation property’s type MUST be an entity type in scope, the abstract type Edm.EntityType, or a collection of one of these types.
If the type is a collection, an arbitrary number of entities can be related. Otherwise there is at most one related entity.
The related entities MUST be of the specified entity type or one of its subtypes.
For a collection-valued containment navigation property the specified entity type MUST have a key defined.
A collection-valued navigation property MAY be annotated with the 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.
- $Type and $Collection
-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 qualified name of the navigation property's item type, and the member $Collection MUST be present with the literal value true.
+ $Type and $Collection
+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 qualified name of the navigation property’s item type, and the member $Collection MUST be present with the literal value true.
8.2 Nullable Navigation Property
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.
- $Nullable
+ $Nullable
The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
8.3 Partner Navigation Property
@@ -1303,7 +1315,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.
- $Partner
+ $Partner
The value of $Partner is a string containing the path to the partner navigation property.
8.4 Containment Navigation Property
@@ -1320,17 +1332,17 @@
- $ContainsTarget
+ $ContainsTarget
The value of $ContainsTarget is one of the Boolean literals true or false. Absence of the member means false.
8.5 Referential Constraint
A single-valued navigation property MAY define one or more referential constraints. A referential constraint asserts that the dependent property (the property defined on the structured type declaring the navigation property) MUST have the same value as the principal property (the referenced property declared on the entity type that is the target of the navigation).
The type of the dependent property MUST match the type of the principal property, or both types MUST be complex types.
-If the principle property references an entity, then the dependent property must reference the same entity.
-If the principle property's value is a complex type instance, then the dependent property's value must be a complex type instance with the same properties, each with the same values.
+If the principal property references an entity, then the dependent property must reference the same entity.
+If the principal property’s value is a complex type instance, then the dependent property’s value must be a complex type instance with the same properties, each with the same values.
If the navigation property on which the referential constraint is defined is nullable, or the principal property is nullable, then the dependent property MUST also be nullable. If both the navigation property and the principal property are not nullable, then the dependent property MUST NOT be nullable.
- $ReferentialConstraint
+ $ReferentialConstraint
The 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.
@@ -1375,7 +1387,7 @@ 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.
- $OnDelete
+ $OnDelete
The value of $OnDelete is a string with one of the values Cascade, None, SetNull, or SetDefault.
Annotations for $OnDelete are prefixed with $OnDelete.
@@ -1397,11 +1409,11 @@ $OnDelete
9 Complex Type
Complex types are keyless nominal structured types. The lack of a key means that instances of complex types cannot be referenced, created, updated or deleted independently of an entity type. Complex types allow entity models to group properties into common structures.
-The complex type's name is a simple identifier that MUST be unique within its schema.
+The complex type’s name is a simple identifier that MUST be unique within its schema.
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.
- 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 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.
@@ -1447,13 +1459,13 @@ section 14.2.
- $BaseType
+ $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.
- $Abstract
+ $Abstract
The value of $Abstract is one of the Boolean literals true or false. Absence of the member means false.
9.3 Open Complex Type
@@ -1461,17 +1473,17 @@
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
+ $OpenType
The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.
10 Enumeration Type
Enumeration types are nominal types that represent a non-empty series of related values. Enumeration types expose these related values as members of the enumeration.
-The enumeration type's name is a simple identifier that MUST be unique within its schema.
+The enumeration type’s name is a simple identifier that MUST be unique within its schema.
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.
- 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 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.
@@ -1494,14 +1506,14 @@
- $UnderlyingType
+ $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.
- $IsFlags
+ $IsFlags
The value of $IsFlags is one of the Boolean literals true or false. Absence of the member means false.
@@ -1532,7 +1544,7 @@
- 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 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.
@@ -1553,11 +1565,11 @@ Enumera
11 Type Definition
A type definition defines a specialization of one of the primitive types or of the built-in abstract type Edm.PrimitiveType.
-The type definition's name is a simple identifier that MUST be unique within its schema.
+The type definition’s name is a simple identifier that MUST be unique within its schema.
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.
- 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 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.
@@ -1588,7 +1600,7 @@ Type Defini
11.1 Underlying Primitive Type
The underlying type of a type definition MUST be a primitive type that MUST NOT be another type definition.
- $UnderlyingType
+ $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.
@@ -1599,7 +1611,7 @@ $UnderlyingTy
12 Action and Function
12.1 Action
Actions are service-defined operations that MAY have observable side effects and MAY return a single instance or a collection of instances of any type.
-The action's name is a simple identifier that MUST be unique within its schema.
+The action’s name is a simple identifier that MUST be unique within its schema.
Actions cannot be composed with additional path segments.
An action MAY specify a return type that MUST be a primitive, entity or complex type, or a collection of primitive, entity or complex types in scope.
An action MAY define parameters used during the execution of the action.
@@ -1608,14 +1620,14 @@
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.
- 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 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.
12.3 Function
Functions are service-defined operations that MUST NOT have observable side effects and MUST return a single instance or a collection of instances of any type.
-The function's name is a simple identifier that MUST be unique within its schema.
+The function’s name is a simple identifier that MUST be unique within its schema.
Functions MAY be composable.
The function MUST specify a return type which MUST be a primitive, entity or complex type, or a collection of primitive, entity or complex types in scope.
A function MAY define parameters used during the execution of the function.
@@ -1635,18 +1647,18 @@ type definitions can be used to disambiguate overloads for both bound and unbound functions, even if they specify the same underlying type.
- 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 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.
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.
- $IsBound
+ $IsBound
The value of $IsBound is one of the Boolean literals true or false. Absence of the member means false.
12.6 Entity Set Path
@@ -1655,29 +1667,29 @@ 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.
- $EntitySetPath
+ $EntitySetPath
The value of $EntitySetPath is a string containing 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.
- $IsComposable
+ $IsComposable
The value of $IsComposable is one of the Boolean literals true or false. Absence of the member 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.
- $ReturnType
+ $ReturnType
The 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 $Collection
For 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
+ $Nullable
The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
If the return type is a collection of entity types, the $Nullable member has no meaning and MUST NOT be specified.
For other collection-valued return types the result will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.
@@ -1691,18 +1703,18 @@ 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.
- $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, $MaxLength, $Unicode, $Precision, $Scale, and $SRID.
Parameter objects MAY also contain annotations.
- $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.
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
+ $Nullable
The 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.
@@ -1731,7 +1743,7 @@ $Nullabl
13 Entity Container
Each metadata document used to describe an OData service MUST define exactly one entity container.
-The entity container's name is a simple identifier that MUST be unique within its schema.
+The entity container’s name is a simple identifier that MUST be unique within its schema.
Entity containers define the entity sets, singletons, function and action imports exposed by the service.
Entity set, singleton, action import, and function import names MUST be unique within an entity container.
An entity set allows access to entity type instances. Simple entity models frequently have one entity set per entity type.
@@ -1773,7 +1785,7 @@ 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.
- 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 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.
@@ -1819,11 +1831,11 @@ Entity Co
}
13.1 Extending an Entity Container
-An entity container MAY specify that it extends another entity container in scope. All children of the "base" entity container are added to the "extending" entity container.
-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.
+An entity container MAY specify that it extends another entity container in scope. All children of the “base” entity container are added to the “extending” entity container.
+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.
- $Extends
+ $Extends
The value of $Extends is the qualified name of the entity container to be extended.
@@ -1842,15 +1854,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.
- 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.
The entity set object MUST contain the members $Collection and $Type.
It MAY contain the members $IncludeInServiceDocument and $NavigationPropertyBinding as well as annotations.
- $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.
13.3 Singleton
@@ -1859,21 +1871,21 @@ 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.
- 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.
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
+ $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 member MUST NOT be specified.
13.4 Navigation Property Binding
If the entity type of an entity set or singleton declares navigation properties, a navigation property binding allows describing which entity set or singleton will contain the related entities.
-An entity set or a singleton SHOULD specify a navigation property binding for each navigation property of its entity type, including navigation properties defined on complex typed properties or derived types.
+An entity set or a singleton SHOULD contain a navigation property binding for each non-containment navigation property that can be reached from the entity type through a sequence of type casts, complex properties, or containment navigation properties.
If omitted, clients MUST assume that the target entity set or singleton can vary per related entity.
13.4.1 Navigation Property Path Binding
-A navigation property binding MUST specify a path to a navigation property of the entity set's or singleton's declared entity type, or a navigation property reached through a chain of type casts, complex properties, or containment navigation properties. If the navigation property is defined on a subtype, the path MUST contain the qualified name of the subtype, followed by a forward slash, followed by the navigation property name. If the navigation property is defined on a complex type used in the definition of the entity set's entity type, the path MUST contain a forward-slash separated list of complex property names and qualified type names that describe the path leading to the navigation property.
+A navigation property binding MUST specify a path to a navigation property of the entity set’s or singleton’s declared entity type, or a navigation property reached through a chain of type casts, complex properties, or containment navigation properties. If the navigation property is defined on a subtype, the path MUST contain the qualified name of the subtype, followed by a forward slash, followed by the navigation property name. If the navigation property is defined on a complex type used in the definition of the entity set’s entity type, the path MUST contain a forward-slash separated list of complex property names and qualified type names that describe the path leading to the navigation property.
The path can traverse one or more containment navigation properties, but the last navigation property segment MUST be a non-containment navigation property and there MUST NOT be any non-containment navigation properties prior to the final navigation property segment.
If the path traverses collection-valued complex properties or collection-valued containment navigation properties, the binding applies to all items of these collections.
If the path contains a recursive sub-path (i.e. a path leading back to the same structured type, the binding applies recursively to any positive number of cycles through that sub-path.
@@ -1884,7 +1896,7 @@ 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.
@@ -1923,14 +1935,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.
- 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 object.
The action import object MUST contain the member $Action.
It MAY contain the member $EntitySet.
It MAY also contain annotations.
- $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 entity set in a different entity container.
13.6 Function Import
@@ -1940,16 +1952,16 @@ 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.
- 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 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
+ $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.
@@ -2005,19 +2017,23 @@ 14.1 Term
A term allows annotating a model element or OData resource representation with additional data.
-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.
+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.
- 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.
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
-For 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.
+ $Type and $Collection
+For 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
+ $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 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.
@@ -2025,7 +2041,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.
- $BaseTerm
+ $BaseTerm
The value of $BaseTerm is the qualified name of the base term.
14.1.2 Applicability
@@ -2173,7 +2189,7 @@ 14.1.2
- $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 term is intended to be applied to.
@@ -2194,7 +2210,7 @@ 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.
- 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 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.
@@ -2222,9 +2238,9 @@ Annotation Member "$MaxLength": 3
}
-If an entity type or complex type is annotated with a term that itself has a structured type, an instance of the annotated type may be viewed as an "instance" of the term, and the qualified term name may be used as a term-cast segment in path expressions.
-Structured types "inherit" annotations from their direct or indirect base types. If both the type and one of its base types is annotated with the same term and qualifier, the annotation on the type completely replaces the annotation on the base type; structured or collection-valued annotation values are not merged. Similarly, properties of a structured type inherit annotations from identically named properties of a base 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 model element is used, and whether they can be overridden. E.g. a "Label" annotation for a UI can propagate from a type definition to all properties using that type definition and may be overridden at each property with a more specific label, whereas an annotation marking a type definition as containing a phone number will propagate to all using properties but may not be overridden.
+If an entity type or complex type is annotated with a term that itself has a structured type, an instance of the annotated type may be viewed as an “instance” of the term, and the qualified term name may be used as a term-cast segment in path expressions.
+Structured types “inherit” annotations from their direct or indirect base types. If both the type and one of its base types is annotated with the same term and qualifier, the annotation on the type completely replaces the annotation on the base type; structured or collection-valued annotation values are not merged. Similarly, properties of a structured type inherit annotations from identically named properties of a base 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 model element is used, and whether they can be overridden. E.g. a “Label” annotation for a UI can propagate from a type definition to all properties using that type definition and may be overridden at each property with a more specific label, whereas an annotation marking a type definition as containing a phone number will propagate to all using properties but may not be overridden.
14.2.1 Qualifier
A 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.
@@ -2236,7 +2252,7 @@ 14.2.1 Qualifier
14.2.2 Target
The target of an annotation is the model element the term is applied to.
-The target of an annotation MAY be specified indirectly by "nesting" the annotation within the model element. Whether and how this is possible is described per model element in this specification.
+The target of an annotation MAY be specified indirectly by “nesting” the annotation within the model element. Whether and how this is possible is described per model element in this specification.
The target of an annotation MAY also be specified directly; this allows defining an annotation in a different schema than the targeted model element.
This external targeting is only possible for model elements that are uniquely identified within their parent, and all their ancestor elements are uniquely identified within their parent.
These are the direct children of a schema with a unique name (i.e. except actions and functions whose overloads to not possess a natural identifier), and all direct children of an entity container.
@@ -2416,7 +2432,7 @@ 14.3.5 Decimal
"@UI.Width": 3.14
-Example 48: "safe" representation as a string
+Example 48: “safe” representation as a string
"@UI.Width": "3.14"
14.3.6 Duration
@@ -2467,7 +2483,7 @@ 14.3.10 Integer
"@An.Int": 42
-Example 55: "safe" representation as a string
+Example 55: “safe” representation as a string
"@A.Very.Long.Int": "9007199254740992"
14.3.11 String
@@ -2502,7 +2518,7 @@ 14.4.1.1 Path
Example 58: absolute path to an entity set
/My.Schema.MyEntityContainer/MyEntitySet
-Paths not starting with a forward slash are interpreted relative to the annotation target, following the rules specified in section "Path Evaluation".
+Paths not starting with a forward slash are interpreted relative to the annotation target, following the rules specified in section “Path Evaluation”.
Example 59: relative path to a property
Address/City
@@ -2512,7 +2528,7 @@ 14.4.1.1 Path
Example 60: type-cast segment
.../self.Manager/...
-If a path segment starts with an at (@) character, it represents a term cast. The at (@) character MUST be followed by a qualified name that MAY be followed by a hash (#) character and a simple identifier. The qualified name preceding the hash character MUST resolve to a term that is in scope, the simple identifier following the hash sign is interpreted as a qualifier for the term. If the model element or instance identified by the preceding path part has not been annotated with that term (and if present, with that qualifier), the term cast evaluates to the null value. Four special terms are implicitly "annotated" for media entities and stream properties:
+If a path segment starts with an at (@) character, it represents a term cast. The at (@) character MUST be followed by a qualified name that MAY be followed by a hash (#) character and a simple identifier. The qualified name preceding the hash character MUST resolve to a term that is in scope, the simple identifier following the hash sign is interpreted as a qualifier for the term. If the model element or instance identified by the preceding path part has not been annotated with that term (and if present, with that qualifier), the term cast evaluates to the null value. Four special terms are implicitly “annotated” for media entities and stream properties:
odata.mediaEditLinkodata.mediaReadLink14.4.1.1 Path
14.4.1.2 Path Evaluation
Annotations MAY be embedded within their target, or specified separately, e.g. as part of a different schema, and specify a path to their target model element. The latter situation is referred to as targeting in the remainder of this section.
-For annotations embedded within or targeting an entity container, the path is evaluated starting at the entity container, i.e. an empty path resolves to the entity container, and non-empty paths MUST start with a segment identifying a container child (entity set, function import, action import, or singleton). The subsequent segments follow the rules for paths targeting the corresponding child element.
-For annotations embedded within or targeting an entity set or a singleton, the path is evaluated starting at the entity set or singleton, i.e. an empty path resolves to the entity set or singleton, and non-empty paths MUST follow the rules for annotations targeting the declared entity type of the entity set or singleton.
-For annotations embedded within or targeting an entity type or complex type, the path is evaluated starting at the type, i.e. an empty path resolves to the type, and the first segment of a non-empty path MUST be a structural or navigation property of the type, a type cast, or a term cast.
-For annotations embedded within a structural or navigation property of an entity type or complex type, the path is evaluated starting at the directly enclosing type. This allows e.g. specifying the value of an annotation on one property to be calculated from values of other properties of the same type. An empty path resolves to the enclosing type, and non-empty paths MUST follow the rules for annotations targeting the directly enclosing type.
-For annotations targeting a structural or navigation property of an entity type or complex type, the path is evaluated starting at the outermost entity type or complex type named in the target of the annotation, i.e. an empty path resolves to the outermost type, and the first segment of a non-empty path MUST be a structural or navigation property of the outermost type, a type cast, or a term cast.
-For annotations embedded within or targeting an action, action import, function, function import, parameter, or return type, the first segment of the path MUST be a parameter name or $ReturnType.
+The host of an annotation is the model element targeted by the annotation, unless that target is another annotation or a model element (collection, record or property value) directly or indirectly embedded within another annotation, in which case the host is the host of that other annotation.
+If the value of an annotation is expressed dynamically with a path expression, the path evaluation rules for this expression depend upon the model element by which the annotation is hosted.
+For annotations hosted by an entity container, the path is evaluated starting at the entity container, i.e. an empty path resolves to the entity container, and non-empty paths MUST start with a segment identifying a container child (entity set, function import, action import, or singleton). The subsequent segments follow the rules for path expressions targeting the corresponding child element.
+For annotations hosted by an entity set or a singleton, the path is evaluated starting at the entity set or singleton, i.e. an empty path resolves to the entity set or singleton, and non-empty paths MUST follow the rules for annotations targeting the declared entity type of the entity set or singleton.
+For annotations hosted by an entity type or complex type, the path is evaluated starting at the type, i.e. an empty path resolves to the type, and the first segment of a non-empty path MUST be a structural or navigation property of the type, a type cast, or a term cast.
+For annotations hosted by an action, action import, function, function import, parameter, or return type, the first segment of the path MUST be the name of a parameter of the action or function or $ReturnType.
+For annotations hosted by a structural or navigation property, the path evaluation rules additionally depend upon how the annotation target is specified, as follows:
+
+If the annotation is directly or indirectly embedded within the hosting property, the path is evaluated starting at the directly enclosing type of the hosting property. This allows e.g. specifying the value of an annotation on one property to be calculated from values of other properties of the same enclosing type. An empty path resolves to the enclosing type, and non-empty paths MUST follow the rules for annotations targeting the directly enclosing type.
If the annotation uses targeting and the target path starts with an entity container, or the annotation is directly or indirectly embedded within such an annotation, the path is evaluated starting at the declared type of the hosting property. An empty path resolves to the declared type of the property, and non-empty paths MUST follow the rules for annotations targeting the declared type of the property. If the type is primitive, the first segment of a non-empty path MUST be a type cast or a term cast.
If the annotation uses targeting and the target path does not start with an entity container, or the annotation is directly or indirectly embedded within such an annotation, the path is evaluated starting at the outermost entity type or complex type named in the target path. This allows e.g. specifying the value of an annotation on one property to be calculated from values of other properties of the outermost type. An empty path resolves to the outermost type, and the first segment of a non-empty path MUST be a structural or navigation property of the outermost type, a type cast, or a term cast.
+
+Example 67: Annotations hosted by property A2 in various modes
+Path evaluation for the annotations in the first block starts at the directly enclosing type self.A of the hosting property A2.
+
+"self": {
+ "A": {
+ "$Kind": "EntityType",
+ "A1": {
+ "$Type": "Edm.Boolean"
+ },
+ "A2": {
+ "$Type": "self.B"
+ "@Core.Description@Core.IsLanguageDependent": {
+ "$Path": "A1"
+ },
+ "@Core.Description": "..."
+ }
+ },
+ "B": {
+ "$Kind": "ComplexType",
+ "B1": {
+ "$Type": "Edm.Boolean"
+ }
+ },
+
+Path evaluation for the annotations in the next block starts at the declared type self.B of the hosting property A2.
+
+ "Container": {
+ "$Kind": "EntityContainer",
+ "SetA": {
+ "$Collection": true,
+ "$Type": "self.A"
+ }
+ },
+ "$Annotations": {
+ "self.Container/SetA/A2": {
+ "@Core.Description#viaset@Core.IsLanguageDependent": {
+ "$Path": "B1"
+ },
+ "@Core.Description#viaset": "..."
+ },
+ "self.Container/SetA/A2/@Core.Description#viaset": {
+ "@Core.IsLanguageDependent": {
+ "$Path": "B1"
+ }
+ },
+
+Path evaluation for the annotations in the final block starts at the outermost type self.A named in the target path.
+
+ "self.A/A2": {
+ "@Core.Description#external@Core.IsLanguageDependent": {
+ "$Path": "A1"
+ },
+ "@Core.Description#external": "..."
+ },
+ "self.A/A2/@Core.Description": {
+ "@Core.IsLanguageDependent": {
+ "$Path": "A1"
+ }
+ }
+ }
+}
+
+
14.4.1.3 Annotation Path
-The annotation path expression provides a value for terms or term properties that specify the built-in types Edm.AnnotationPath or Edm.ModelElementPath. Its argument is a model path with the following restriction:
+The annotation path expression provides a value for terms or term properties that specify the built-in types Edm.AnnotationPath or Edm.ModelElementPath. Its argument is a model path with the following restriction:
- A non-null path MUST resolve to an annotation.
@@ -2572,25 +2658,25 @@ 1
Annotation path expressions are represented as a string containing a path.
-Example 67:
-"@UI.ReferenceFacet": "Product/Supplier/@UI.LineItem",
-"@UI.CollectionFacet#Contacts": [
- "Supplier/@Communication.Contact",
- "Customer/@Communication.Contact"
-]
+Example 68:
+"@UI.ReferenceFacet": "Product/Supplier/@UI.LineItem",
+"@UI.CollectionFacet#Contacts": [
+ "Supplier/@Communication.Contact",
+ "Customer/@Communication.Contact"
+]
14.4.1.4 Model Element Path
-The model element path expression provides a value for terms or term properties that specify the built-in type Edm.ModelElementPath. Its argument is a model path.
+The model element path expression provides a value for terms or term properties that specify the 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.
Model element path expressions are represented as a string containing a path.
-Example 68:
-"@org.example.MyFavoriteModelElement": "/self.someAction"
+Example 69:
+"@org.example.MyFavoriteModelElement": "/self.someAction"
14.4.1.5 Navigation Property Path
-The navigation property path expression provides a value for terms or term properties that specify the built-in types Edm.NavigationPropertyPath, Edm.AnyPropertyPath, or Edm.ModelElementPath. Its argument is a model path with the following restriction:
+The navigation property path expression provides a value for terms or term properties that specify the built-in types Edm.NavigationPropertyPath, Edm.AnyPropertyPath, or Edm.ModelElementPath. Its argument is a model path with the following restriction:
- A non-null path MUST resolve to a model element whose type is an entity type, or a collection of entity types, e.g. a navigation property.
@@ -2599,18 +2685,18 @@
-Example 69:
-"@UI.HyperLink": "Supplier",
-
-"@Capabilities.UpdateRestrictions": {
- "NonUpdatableNavigationProperties": [
- "Supplier",
- "Category"
- ]
-}
+Example 70:
+"@UI.HyperLink": "Supplier",
+
+"@Capabilities.UpdateRestrictions": {
+ "NonUpdatableNavigationProperties": [
+ "Supplier",
+ "Category"
+ ]
+}
14.4.1.6 Property Path
-The property path expression provides a value for terms or term properties that specify one of the built-in types Edm.PropertyPath, Edm.AnyPropertyPath, or Edm.ModelElementPath. Its argument is a model path with the following restriction:
+The property path expression provides a value for terms or term properties that specify one of the built-in types Edm.PropertyPath, Edm.AnyPropertyPath, or Edm.ModelElementPath. Its argument is a model path with the following restriction:
- A non-null path MUST resolve to a model element whose type is a primitive or complex type, an enumeration type, a type definition, or a collection of one of these types.
@@ -2619,32 +2705,32 @@ 14.4.1.
Property path expressions are represented as a string containing a path.
-Example 70:
-"@UI.RefreshOnChangeOf": "ChangedAt",
-
-"@Capabilities.UpdateRestrictions": {
- "NonUpdatableProperties": [
- "CreatedAt",
- "ChangedAt"
- ]
-}
+Example 71:
+"@UI.RefreshOnChangeOf": "ChangedAt",
+
+"@Capabilities.UpdateRestrictions": {
+ "NonUpdatableProperties": [
+ "CreatedAt",
+ "ChangedAt"
+ ]
+}
14.4.1.7 Value Path
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
+ $Path
Path expressions are represented as an object with a single member $Path whose value is a string containing a path.
-Example 71:
-"@UI.DisplayName": {
- "$Path": "FirstName"
-},
-
-"@UI.DisplayName#second": {
- "$Path": "@vCard.Address#work/FullName"
-}
+Example 72:
+"@UI.DisplayName": {
+ "$Path": "FirstName"
+},
+
+"@UI.DisplayName#second": {
+ "$Path": "@vCard.Address#work/FullName"
+}
14.4.2 Comparison and Logical Operators
Annotations MAY use the following logical and comparison expressions which evaluate to a Boolean value. These expressions MAY be combined and they MAY be used anywhere instead of a Boolean expression.
@@ -2668,110 +2754,110 @@ OData-URL.
The other comparison operators require two operand expressions that evaluate to comparable values.
- $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. The member name is one of $And, or $Or.
It MAY contain annotations.
- $Not
+ $Not
Negation 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 $In
All 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.
-Example 72:
-{
- "$And": [
- {
- "$Path": "IsMale"
- },
- {
- "$Path": "IsMarried"
- }
- ]
-},
-{
- "$Or": [
- {
- "$Path": "IsMale"
- },
- {
- "$Path": "IsMarried"
- }
- ]
-},
-{
- "$Not": {
- "$Path": "IsMale"
- }
-},
-{
- "$Eq": [
- null,
- {
- "$Path": "IsMale"
- }
- ]
-},
-{
- "$Ne": [
- null,
- {
- "$Path": "IsMale"
- }
- ]
-},
-{
- "$Gt": [
- {
- "$Path": "Price"
- },
- 20
- ]
-},
-{
- "$Ge": [
- {
- "$Path": "Price"
- },
- 10
- ]
-},
-{
- "$Lt": [
- {
- "$Path": "Price"
- },
- 20
- ]
-},
-{
- "$Le": [
- {
- "$Path": "Price"
- },
- 100
- ]
-},
-{
- "$Has": [
- {
- "$Path": "Fabric"
- },
- "Red"
- ]
-},
-{
- "$In": [
- {
- "$Path": "Size"
- },
- [
- "XS",
- "S"
- ]
- ]
-} ```
+Example 73:
+{
+ "$And": [
+ {
+ "$Path": "IsMale"
+ },
+ {
+ "$Path": "IsMarried"
+ }
+ ]
+},
+{
+ "$Or": [
+ {
+ "$Path": "IsMale"
+ },
+ {
+ "$Path": "IsMarried"
+ }
+ ]
+},
+{
+ "$Not": {
+ "$Path": "IsMale"
+ }
+},
+{
+ "$Eq": [
+ null,
+ {
+ "$Path": "IsMale"
+ }
+ ]
+},
+{
+ "$Ne": [
+ null,
+ {
+ "$Path": "IsMale"
+ }
+ ]
+},
+{
+ "$Gt": [
+ {
+ "$Path": "Price"
+ },
+ 20
+ ]
+},
+{
+ "$Ge": [
+ {
+ "$Path": "Price"
+ },
+ 10
+ ]
+},
+{
+ "$Lt": [
+ {
+ "$Path": "Price"
+ },
+ 20
+ ]
+},
+{
+ "$Le": [
+ {
+ "$Path": "Price"
+ },
+ 100
+ ]
+},
+{
+ "$Has": [
+ {
+ "$Path": "Fabric"
+ },
+ "Red"
+ ]
+},
+{
+ "$In": [
+ {
+ "$Path": "Size"
+ },
+ [
+ "XS",
+ "S"
+ ]
+ ]
+}
14.4.3 Arithmetic Operators
Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL.
@@ -2815,85 +2901,85 @@
- $Neg
+ $Neg
Negation 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 $Mod
These 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.
-Example 73:
-{
- "$Add": [
- {
- "$Path": "StartDate"
- },
- {
- "$Path": "Duration"
- }
- ]
-},
-{
- "$Sub": [
- {
- "$Path": "Revenue"
- },
- {
- "$Path": "Cost"
- }
- ]
-},
-{
- "$Neg": {
- "$Path": "Height"
- }
-},
-{
- "$Mul": [
- {
- "$Path": "NetPrice"
- },
- {
- "$Path": "TaxRate"
- }
- ]
-},
-{
- "$Div": [
- {
- "$Path": "Quantity"
- },
- {
- "$Path": "QuantityPerParcel"
- }
- ]
-},
-{
- "$DivBy": [
- {
- "$Path": "Quantity"
- },
- {
- "$Path": "QuantityPerParcel"
- }
- ]
-},
-{
- "$Mod": [
- {
- "$Path": "Quantity"
- },
- {
- "$Path": "QuantityPerParcel"
- }
- ]
-}
+Example 74:
+{
+ "$Add": [
+ {
+ "$Path": "StartDate"
+ },
+ {
+ "$Path": "Duration"
+ }
+ ]
+},
+{
+ "$Sub": [
+ {
+ "$Path": "Revenue"
+ },
+ {
+ "$Path": "Cost"
+ }
+ ]
+},
+{
+ "$Neg": {
+ "$Path": "Height"
+ }
+},
+{
+ "$Mul": [
+ {
+ "$Path": "NetPrice"
+ },
+ {
+ "$Path": "TaxRate"
+ }
+ ]
+},
+{
+ "$Div": [
+ {
+ "$Path": "Quantity"
+ },
+ {
+ "$Path": "QuantityPerParcel"
+ }
+ ]
+},
+{
+ "$DivBy": [
+ {
+ "$Path": "Quantity"
+ },
+ {
+ "$Path": "QuantityPerParcel"
+ }
+ ]
+},
+{
+ "$Mod": [
+ {
+ "$Path": "Quantity"
+ },
+ {
+ "$Path": "QuantityPerParcel"
+ }
+ ]
+}
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.
- $Apply
+ $Apply
Apply 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.
@@ -2902,103 +2988,103 @@ OData-URL can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL.
For example, the odata.concat client-side function takes two or more expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type Edm.String that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than Edm.String are represented according to the appropriate alternative in the primitiveValue rule of OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.
-Example 74:
-"@UI.DisplayName": {
- "$Apply": [
- "Product: ",
- {
- "$Path": "ProductName"
- },
- " (",
- {
- "$Path": "Available/Quantity"
- },
- " ",
- {
- "$Path": "Available/Unit"
- },
- " available)"
- ],
- "$Function": "odata.concat"
-}
+Example 75:
+"@UI.DisplayName": {
+ "$Apply": [
+ "Product: ",
+ {
+ "$Path": "ProductName"
+ },
+ " (",
+ {
+ "$Path": "Available/Quantity"
+ },
+ " ",
+ {
+ "$Path": "Available/Unit"
+ },
+ " available)"
+ ],
+ "$Function": "odata.concat"
+}
ProductName is of type String, Quantity in complex type Available is of type Decimal, and Unit in Available is of type enumeration, so the result of the Path expression is represented as 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.
+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.
Lists of values are represented as labeled element expressions that evaluate to a collection of primitive values.
Key-value maps are represented as labeled element expressions that evaluate to a collection of complex types with two properties that are used in lexicographic order. The first property is used as key, the second property as value.
-Example 75: assuming there are no special characters in values of the Name property of the Actor entity
-{
- "$Apply": [
- "http://host/someAPI/Actors/{actorName}/CV",
- {
- "$LabeledElement": {
- "$Path": "Actor/Name"
- },
- "$Name": "self.actorName"
- }
- ],
- "$Function": "odata.fillUriTemplate"
-}
+Example 76: assuming there are no special characters in values of the Name property of the Actor entity
+{
+ "$Apply": [
+ "http://host/someAPI/Actors/{actorName}/CV",
+ {
+ "$LabeledElement": {
+ "$Path": "Actor/Name"
+ },
+ "$Name": "self.actorName"
+ }
+ ],
+ "$Function": "odata.fillUriTemplate"
+}
14.4.4.3 Function odata.matchesPattern
-The odata.matchesPattern client-side function takes two string expressions as arguments and returns a Boolean value.
+The odata.matchesPattern client-side function takes two string expressions as arguments and returns a Boolean value. It is the counterpart of the identically named URL function OData-URL, section 5.1.1.7.1.
The function returns true if the second expression evaluates to an ECMAScript (JavaScript) regular expression and the result of the first argument expression matches that regular expression, using syntax and semantics of ECMAScript regular expressions.
-Example 76: all non-empty FirstName values not containing the letters b, c, or d evaluate to true
-{
- "$Apply": [
- {
- "$Path": "FirstName"
- },
- "^[^b-d]+$"
- ],
- "$Function": "odata.matchesPattern"
-}
+Example 77: all non-empty FirstName values not containing the letters b, c, or d evaluate to true
+{
+ "$Apply": [
+ {
+ "$Path": "FirstName"
+ },
+ "^[^b-d]+$"
+ ],
+ "$Function": "odata.matchesPattern"
+}
14.4.4.4 Function odata.uriEncode
-The odata.uriEncode client-side function takes one argument of primitive type and returns the URL-encoded OData literal that can be used as a key value in OData URLs or in the query part of OData URLs.
+The odata.uriEncode client-side function takes one argument of primitive type and returns the URL-encoded OData literal that can be used as a key value in OData URLs or in the query part of OData URLs.
Note: string literals are surrounded by single quotes as required by the paren-style key syntax.
-Example 77:
-{
- "$Apply": [
- "http://host/service/Genres({genreName})",
- {
- "$LabeledElement": {
- "$Apply": [
- {
- "$Path": "NameOfMovieGenre"
- }
- ],
- "$Function": "odata.uriEncode"
- },
- "$Name": "self.genreName"
- }
- ],
- "$Function": "odata.fillUriTemplate"
-}
+Example 78:
+{
+ "$Apply": [
+ "http://host/service/Genres({genreName})",
+ {
+ "$LabeledElement": {
+ "$Apply": [
+ {
+ "$Path": "NameOfMovieGenre"
+ }
+ ],
+ "$Function": "odata.uriEncode"
+ },
+ "$Name": "self.genreName"
+ }
+ ],
+ "$Function": "odata.fillUriTemplate"
+}
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.
- $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 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.
-Example 78:
-"@UI.Threshold": {
- "$Cast": {
- "$Path": "Average"
- },
- "$Type": "Edm.Decimal"
-}
+Example 79:
+"@UI.Threshold": {
+ "$Cast": {
+ "$Path": "Average"
+ },
+ "$Type": "Edm.Decimal"
+}
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.
@@ -3006,12 +3092,12 @@ 14.4.6 Collecti
Collection expressions are represented as arrays with one array item per item expression within the collection expression.
-Example 79:
-"@seo.SeoTerms": [
- "Product",
- "Supplier",
- "Customer"
-]
+Example 80:
+"@seo.SeoTerms": [
+ "Product",
+ "Supplier",
+ "Customer"
+]
14.4.7 If-Then-Else
The if-then-else expression enables a value to be obtained by evaluating a condition expression. It MUST contain exactly three child expressions. There is one exception to this rule: if and only if the if-then-else expression is an item of a collection expression, the third child expression MAY be omitted, reducing it to an if-then expression. This can be used to conditionally add an element to a collection.
@@ -3019,68 +3105,68 @@ 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.
- $If
+ $If
Conditional 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.
-Example 80: the condition is a value path expression referencing the Boolean property IsFemale, whose value then determines the value of the $If expression (or so it was long ago)
-"@person.Gender": {
- "$If": [
- {
- "$Path": "IsFemale"
- },
- "Female",
- "Male"
- ]
-}
+Example 81: the condition is a value path expression referencing the Boolean property IsFemale, whose value then determines the value of the $If expression (or so it was long ago)
+"@person.Gender": {
+ "$If": [
+ {
+ "$Path": "IsFemale"
+ },
+ "Female",
+ "Male"
+ ]
+}
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.
- $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 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.
-Example 81:
-"@Self.IsPreferredCustomer": {
- "$IsOf": {
- "$Path": "Customer"
- },
- "$Type": "self.PreferredCustomer"
-}
+Example 82:
+"@Self.IsPreferredCustomer": {
+ "$IsOf": {
+ "$Path": "Customer"
+ },
+ "$Type": "self.PreferredCustomer"
+}
14.4.9 Labeled Element
The labeled element expression assigns a name to its single child expression. The value of the child expression can then be reused elsewhere with a labeled element reference expression.
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
-Labeled 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.
+ $LabeledElement
+Labeled 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.
-Example 82:
-"@UI.DisplayName": {
- "$LabeledElement": {
- "$Path": "FirstName"
- },
- "$Name": "CustomerFirstName"
-}
+Example 83:
+"@UI.DisplayName": {
+ "$LabeledElement": {
+ "$Path": "FirstName"
+ },
+ "$Name": "CustomerFirstName"
+}
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.
-Example 83:
-"@UI.DisplayName": {
- "$LabeledElementReference": "self.CustomerFirstName"
-}
+Example 84:
+"@UI.DisplayName": {
+ "$LabeledElementReference": "self.CustomerFirstName"
+}
14.4.11 Null
The null expression indicates the absence of a value. The null expression MAY be annotated.
@@ -3088,24 +3174,24 @@ 14.4.11 Null
Null expressions that do not contain annotations are represented as the literal null.
-Example 84:
-"@UI.DisplayName": null,
+Example 85:
+"@UI.DisplayName": null,
- $Null
+ $Null
Null expression containing annotations are represented as an object with a member $Null whose value is the literal null.
-Example 85:
-"@UI.Address": {
- "$Null": null,
- "@self.Reason": "Private"
-}
+Example 86:
+"@UI.Address": {
+ "$Null": null,
+ "@self.Reason": "Private"
+}
14.4.12 Record
The record expression enables a new entity type or complex type instance to be constructed.
-A record expression MAY specify the structured type of its result, which MUST be an entity type or complex type in scope. If not explicitly specified, the type is derived from the expression's context.
-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.
+A record expression MAY specify the structured type of its result, which MUST be an entity type or complex type in scope. If not explicitly specified, the type is derived from the expression’s context.
+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.
Record expressions are represented as objects with one member per property value expression. The member name is the property name, and the member value is the property value expression.
@@ -3113,70 +3199,70 @@ 14.4.12 Record
It MAY contain annotations for itself and its members. Annotations for record members are prefixed with the member name.
-Example 86: 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
-"@person.Employee": {
- "@type": "https://example.org/vocabs/person#org.example.person.Manager",
- "@Core.Description": "Annotation on record",
- "GivenName": {
- "$Path": "FirstName"
- },
- "GivenName@Core.Description": "Annotation on record member",
- "Surname": {
- "$Path": "LastName"
- },
- "DirectSupervisor": {
- "$Path": "Manager"
- },
- "CostCenter": {
- "$UrlRef": {
- "$Apply": [
- "http://host/anotherservice/CostCenters('{ccid}')",
- {
- "$LabeledElement": {
- "$Path": "CostCenterID"
- },
- "$Name": "ccid"
- }
- ],
- "$Function": "odata.fillUriTemplate"
- }
- }
-}
+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",
+ "GivenName": {
+ "$Path": "FirstName"
+ },
+ "GivenName@Core.Description": "Annotation on record member",
+ "Surname": {
+ "$Path": "LastName"
+ },
+ "DirectSupervisor": {
+ "$Path": "Manager"
+ },
+ "CostCenter": {
+ "$UrlRef": {
+ "$Apply": [
+ "http://host/anotherservice/CostCenters('{ccid}')",
+ {
+ "$LabeledElement": {
+ "$Path": "CostCenterID"
+ },
+ "$Name": "ccid"
+ }
+ ],
+ "$Function": "odata.fillUriTemplate"
+ }
+ }
+}
14.4.13 URL Reference
The URL reference expression enables a value to be obtained by sending a GET request.
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.
-Example 87:
-"@org.example.person.Supplier": {
- "$UrlRef": {
- "$Apply": [
- "http://host/service/Suppliers({suppID})",
- {
- "$LabeledElement": {
- "$Apply": [
- {
- "$Path": "SupplierId"
- }
- ],
- "$Function": "odata.uriEncode"
- },
- "$Name": "suppID"
- }
- ],
- "$Function": "odata.fillUriTemplate"
- }
-},
-
-"@Core.LongDescription#element": {
- "$UrlRef": "http://host/wiki/HowToUse"
-}
+Example 88:
+"@org.example.person.Supplier": {
+ "$UrlRef": {
+ "$Apply": [
+ "http://host/service/Suppliers({suppID})",
+ {
+ "$LabeledElement": {
+ "$Apply": [
+ {
+ "$Path": "SupplierId"
+ }
+ ],
+ "$Function": "odata.uriEncode"
+ },
+ "$Name": "suppID"
+ }
+ ],
+ "$Function": "odata.fillUriTemplate"
+ }
+},
+
+"@Core.LongDescription#element": {
+ "$UrlRef": "http://host/wiki/HowToUse"
+}
15 Identifier and Path Values
@@ -3186,8 +3272,8 @@
-- The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category "Letter (L)", "Letter number (Nl)", "Decimal number (Nd)", "Non-spacing mark (Mn)", "Combining spacing mark (Mc)", "Connector punctuation (Pc)", and "Other, format (Cf)".
+- The first character MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)” or “Letter number (Nl)”.
+- The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)”, “Letter number (Nl)”, “Decimal number (Nd)”, “Non-spacing mark (Mn)”, “Combining spacing mark (Mc)”, “Connector punctuation (Pc)”, and “Other, format (Cf)”.
Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.
15.3 Qualified Name
@@ -3201,7 +3287,7 @@ 15.4 Target Pat
- The target path of a container child followed by a forward slash and one or more forward-slash separated property, navigation property, or type-cast segments
-Example 88: Target expressions
+Example 89: Target expressions
MySchema.MyEntityContainer/MyEntitySet
MySchema.MyEntityContainer/MySingleton
MySchema.MyEntityContainer/MySingleton/MyContainmentNavigationProperty
@@ -3213,272 +3299,271 @@ 16 CSDL Ex
Following are two basic examples of valid EDM models as represented in CSDL JSON. These examples demonstrate many of the topics covered above.
16.1 Products and Categories Example
-Example 89:
-{
- "$Version": "4.0",
- "$EntityContainer": "ODataDemo.DemoService",
- "$Reference": {
- "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": {
- "$Include": [
- {
- "$Namespace": "Org.OData.Core.V1",
- "$Alias": "Core",
- "@Core.DefaultNamespace": true
- }
- ]
- },
- "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Measures.V1.json": {
- "$Include": [
- {
- "$Namespace": "Org.OData.Measures.V1",
- "$Alias": "Measures"
- }
- ]
- }
- },
- "ODataDemo": {
- "$Alias": "self",
- "@Core.DefaultNamespace": true,
- "Product": {
- "$Kind": "EntityType",
- "$HasStream": true,
- "$Key": [
- "ID"
- ],
- "ID": {},
- "Description": {
- "$Nullable": true,
- "@Core.IsLanguageDependent": true
- },
- "ReleaseDate": {
- "$Nullable": true,
- "$Type": "Edm.Date"
- },
- "DiscontinuedDate": {
- "$Nullable": true,
- "$Type": "Edm.Date"
- },
- "Rating": {
- "$Nullable": true,
- "$Type": "Edm.Int32"
- },
- "Price": {
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "@Measures.ISOCurrency": {
- "$Path": "Currency"
- }
- },
- "Currency": {
- "$Nullable": true,
- "$MaxLength": 3
- },
- "Category": {
- "$Kind": "NavigationProperty",
- "$Type": "self.Category",
- "$Partner": "Products"
- },
- "Supplier": {
- "$Kind": "NavigationProperty",
- "$Nullable": true,
- "$Type": "self.Supplier",
- "$Partner": "Products"
- }
- },
- "Category": {
- "$Kind": "EntityType",
- "$Key": [
- "ID"
- ],
- "ID": {
- "$Type": "Edm.Int32"
- },
- "Name": {
- "@Core.IsLanguageDependent": true
- },
- "Products": {
- "$Kind": "NavigationProperty",
- "$Partner": "Category",
- "$Collection": true,
- "$Type": "self.Product",
- "$OnDelete": "Cascade"
- }
- },
- "Supplier": {
- "$Kind": "EntityType",
- "$Key": [
- "ID"
- ],
- "ID": {},
- "Name": {
- "$Nullable": true
- },
- "Address": {
- "$Type": "self.Address"
- },
- "Concurrency": {
- "$Type": "Edm.Int32"
- },
- "Products": {
- "$Kind": "NavigationProperty",
- "$Partner": "Supplier",
- "$Collection": true,
- "$Type": "self.Product"
- }
- },
- "Country": {
- "$Kind": "EntityType",
- "$Key": [
- "Code"
- ],
- "Code": {
- "$MaxLength": 2
- },
- "Name": {
- "$Nullable": true
- }
- },
- "Address": {
- "$Kind": "ComplexType",
- "Street": {
- "$Nullable": true
- },
- "City": {
- "$Nullable": true
- },
- "State": {
- "$Nullable": true
- },
- "ZipCode": {
- "$Nullable": true
- },
- "CountryName": {
- "$Nullable": true
- },
- "Country": {
- "$Kind": "NavigationProperty",
- "$Nullable": true,
- "$Type": "self.Country",
- "$ReferentialConstraint": {
- "CountryName": "Name"
- }
- }
- },
- "ProductsByRating": [
- {
- "$Kind": "Function",
- "$Parameter": [
- {
- "$Name": "Rating",
- "$Nullable": true,
- "$Type": "Edm.Int32"
- }
- ],
- "$ReturnType": {
- "$Collection": true,
- "$Type": "self.Product"
- }
- }
- ],
- "DemoService": {
- "$Kind": "EntityContainer",
- "Products": {
- "$Collection": true,
- "$Type": "self.Product",
- "$NavigationPropertyBinding": {
- "Category": "Categories"
- }
- },
- "Categories": {
- "$Collection": true,
- "$Type": "self.Category",
- "$NavigationPropertyBinding": {
- "Products": "Products"
- },
- "@Core.Description": "Product Categories"
- },
- "Suppliers": {
- "$Collection": true,
- "$Type": "self.Supplier",
- "$NavigationPropertyBinding": {
- "Products": "Products",
- "Address/Country": "Countries"
- },
- "@Core.OptimisticConcurrency": [
- "Concurrency"
- ]
- },
- "Countries": {
- "$Collection": true,
- "$Type": "self.Country"
- },
- "MainSupplier": {
- "$Type": "self.Supplier",
- "$NavigationPropertyBinding": {
- "Products": "Products"
- },
- "@Core.Description": "Primary Supplier"
- },
- "ProductsByRating": {
- "$EntitySet": "Products",
- "$Function": "self.ProductsByRating"
- }
- }
- }
-}
+Example 90:
+{
+ "$Version": "4.0",
+ "$EntityContainer": "ODataDemo.DemoService",
+ "$Reference": {
+ "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": {
+ "$Include": [
+ {
+ "$Namespace": "Org.OData.Core.V1",
+ "$Alias": "Core",
+ "@Core.DefaultNamespace": true
+ }
+ ]
+ },
+ "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Measures.V1.json": {
+ "$Include": [
+ {
+ "$Namespace": "Org.OData.Measures.V1",
+ "$Alias": "Measures"
+ }
+ ]
+ }
+ },
+ "ODataDemo": {
+ "$Alias": "self",
+ "@Core.DefaultNamespace": true,
+ "Product": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "ID"
+ ],
+ "ID": {},
+ "Description": {
+ "$Nullable": true,
+ "@Core.IsLanguageDependent": true
+ },
+ "ReleaseDate": {
+ "$Nullable": true,
+ "$Type": "Edm.Date"
+ },
+ "DiscontinuedDate": {
+ "$Nullable": true,
+ "$Type": "Edm.Date"
+ },
+ "Rating": {
+ "$Nullable": true,
+ "$Type": "Edm.Int32"
+ },
+ "Price": {
+ "$Nullable": true,
+ "$Type": "Edm.Decimal",
+ "@Measures.ISOCurrency": {
+ "$Path": "Currency"
+ }
+ },
+ "Currency": {
+ "$Nullable": true,
+ "$MaxLength": 3
+ },
+ "Category": {
+ "$Kind": "NavigationProperty",
+ "$Type": "self.Category",
+ "$Partner": "Products"
+ },
+ "Supplier": {
+ "$Kind": "NavigationProperty",
+ "$Nullable": true,
+ "$Type": "self.Supplier",
+ "$Partner": "Products"
+ }
+ },
+ "Category": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "ID"
+ ],
+ "ID": {
+ "$Type": "Edm.Int32"
+ },
+ "Name": {
+ "@Core.IsLanguageDependent": true
+ },
+ "Products": {
+ "$Kind": "NavigationProperty",
+ "$Partner": "Category",
+ "$Collection": true,
+ "$Type": "self.Product",
+ "$OnDelete": "Cascade"
+ }
+ },
+ "Supplier": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "ID"
+ ],
+ "ID": {},
+ "Name": {
+ "$Nullable": true
+ },
+ "Address": {
+ "$Type": "self.Address"
+ },
+ "Concurrency": {
+ "$Type": "Edm.Int32"
+ },
+ "Products": {
+ "$Kind": "NavigationProperty",
+ "$Partner": "Supplier",
+ "$Collection": true,
+ "$Type": "self.Product"
+ }
+ },
+ "Country": {
+ "$Kind": "EntityType",
+ "$Key": [
+ "Code"
+ ],
+ "Code": {
+ "$MaxLength": 2
+ },
+ "Name": {
+ "$Nullable": true
+ }
+ },
+ "Address": {
+ "$Kind": "ComplexType",
+ "Street": {
+ "$Nullable": true
+ },
+ "City": {
+ "$Nullable": true
+ },
+ "State": {
+ "$Nullable": true
+ },
+ "ZipCode": {
+ "$Nullable": true
+ },
+ "CountryName": {
+ "$Nullable": true
+ },
+ "Country": {
+ "$Kind": "NavigationProperty",
+ "$Nullable": true,
+ "$Type": "self.Country",
+ "$ReferentialConstraint": {
+ "CountryName": "Name"
+ }
+ }
+ },
+ "ProductsByRating": [
+ {
+ "$Kind": "Function",
+ "$Parameter": [
+ {
+ "$Name": "Rating",
+ "$Nullable": true,
+ "$Type": "Edm.Int32"
+ }
+ ],
+ "$ReturnType": {
+ "$Collection": true,
+ "$Type": "self.Product"
+ }
+ }
+ ],
+ "DemoService": {
+ "$Kind": "EntityContainer",
+ "Products": {
+ "$Collection": true,
+ "$Type": "self.Product",
+ "$NavigationPropertyBinding": {
+ "Category": "Categories"
+ }
+ },
+ "Categories": {
+ "$Collection": true,
+ "$Type": "self.Category",
+ "$NavigationPropertyBinding": {
+ "Products": "Products"
+ },
+ "@Core.Description": "Product Categories"
+ },
+ "Suppliers": {
+ "$Collection": true,
+ "$Type": "self.Supplier",
+ "$NavigationPropertyBinding": {
+ "Products": "Products",
+ "Address/Country": "Countries"
+ },
+ "@Core.OptimisticConcurrency": [
+ "Concurrency"
+ ]
+ },
+ "Countries": {
+ "$Collection": true,
+ "$Type": "self.Country"
+ },
+ "MainSupplier": {
+ "$Type": "self.Supplier",
+ "$NavigationPropertyBinding": {
+ "Products": "Products"
+ },
+ "@Core.Description": "Primary Supplier"
+ },
+ "ProductsByRating": {
+ "$EntitySet": "Products",
+ "$Function": "self.ProductsByRating"
+ }
+ }
+ }
+}
16.2 Annotations for Products and Categories Example
-Example 90:
-{
- "$Version": "4.01",
- "$Reference": {
- "http://host/service/$metadata": {
- "$Include": [
- {
- "$Namespace": "ODataDemo",
- "$Alias": "target"
- }
- ]
- },
- "http://somewhere/Vocabulary/V1": {
- "$Include": [
- {
- "$Namespace": "Some.Vocabulary.V1",
- "$Alias": "Vocabulary1"
- }
- ]
- }
- },
- "External.Annotations": {
- "$Annotations": {
- "target.Supplier": {
- "@Vocabulary1.EMail": null,
- "@Vocabulary1.AccountID": {
- "$Path": "ID"
- },
- "@Vocabulary1.Title": "Supplier Info",
- "@Vocabulary1.DisplayName": {
- "$Apply": [
- {
- "$Path": "Name"
- },
- " in ",
- {
- "$Path": "Address/CountryName"
- }
- ],
- "$Function": "odata.concat"
- }
- },
- "target.Product": {
- "@Vocabulary1.Tags": [
- "MasterData"
- ]
- }
- }
- }
-} ```
+Example 91:
+{
+ "$Version": "4.01",
+ "$Reference": {
+ "http://host/service/$metadata": {
+ "$Include": [
+ {
+ "$Namespace": "ODataDemo",
+ "$Alias": "target"
+ }
+ ]
+ },
+ "http://somewhere/Vocabulary/V1": {
+ "$Include": [
+ {
+ "$Namespace": "Some.Vocabulary.V1",
+ "$Alias": "Vocabulary1"
+ }
+ ]
+ }
+ },
+ "External.Annotations": {
+ "$Annotations": {
+ "target.Supplier": {
+ "@Vocabulary1.EMail": null,
+ "@Vocabulary1.AccountID": {
+ "$Path": "ID"
+ },
+ "@Vocabulary1.Title": "Supplier Info",
+ "@Vocabulary1.DisplayName": {
+ "$Apply": [
+ {
+ "$Path": "Name"
+ },
+ " in ",
+ {
+ "$Path": "Address/CountryName"
+ }
+ ],
+ "$Function": "odata.concat"
+ }
+ },
+ "target.Product": {
+ "@Vocabulary1.Tags": [
+ "MasterData"
+ ]
+ }
+ }
+ }
+}
17 Conformance
@@ -3515,207 +3600,211 @@ [EPSG]
European Petroleum Survey Group (EPSG). http://www.epsg.org/.
[OData-ABNF]
OData ABNF Construction Rules Version 4.02.
-See link in "Additional artifacts" section on cover page.
+See link in “Additional artifacts” section on cover page.
[OData-CSDL]
OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02. This document.
-OData Common Schema Definition Language (CSDL) XML Representation Version 4.02. See link in "Related work" section on cover page.
+OData Common Schema Definition Language (CSDL) XML Representation Version 4.02. See link in “Related work” section on cover page.
[OData-CSDL-Schema]
OData CSDL JSON Schema.
-See link in "Additional artifacts" section on cover page.
+See link in “Additional artifacts” section on cover page.
[OData-JSON]
OData JSON Format Version 4.02.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[OData-Protocol]
OData Version 4.02 Part 1: Protocol.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[OData-URL]
OData Version 4.02 Part 2: URL Conventions.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[OData-VocCore]
OData Vocabularies Version 4.0: Core Vocabulary.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[OData-VocMeasures]
OData Vocabularies Version 4.0: Measures Vocabulary.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[OData-VocValidation]
OData Vocabularies Version 4.0: Validation Vocabulary.
-See link in "Related work" section on cover page.
+See link in “Related work” section on cover page.
[RFC2119]
-Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
+
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
https://www.rfc-editor.org/info/rfc2119.
[RFC6570]
-Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012.
-http://tools.ietf.org/html/rfc6570.
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, DOI 10.17487/RFC6570, March 2012.
+https://www.rfc-editor.org/info/rfc6570.
[RFC7493]
-Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015.
-https://tools.ietf.org/html/rfc7493.
+The I-JSON Message Format“, RFC 7493, DOI 10.17487/RFC7493, March 2015.
+https://www.rfc-editor.org/info/rfc7493.
[RFC8174]
-Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
-http://www.rfc-editor.org/info/rfc8174.
+Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
+https://www.rfc-editor.org/info/rfc8174.
[RFC8259]
-Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
-http://tools.ietf.org/html/rfc8259.
+Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”, STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017.
+https://www.rfc-editor.org/info/rfc8259.
[XML-Schema-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012.
http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/.
A.2 Informative References
[OpenUI5]
-OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format.
+
OpenUI5 Version 1.40.10 — OData V4 Metadata JSON Format.
https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html.
Appendix B. Table of JSON Objects and Members
-- Document Object
+
- Type Facet Members
-- Reference Object
-
-- Schema Object
+
- Document Object
+- Reference Object
+
-- Entity Type 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
-- Entity Container Object
+
- Action Overload Object
+- Function Overload 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
-
@@ -3828,14 +3917,14 @@ Appendix E. Notices
Copyright © OASIS Open 2023. All Rights Reserved.
-All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
+All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the “OASIS IPR Policy”). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
-This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
As stated in the OASIS IPR Policy, the following three paragraphs in brackets apply to OASIS Standards Final Deliverable documents (Committee Specification, Candidate OASIS Standard, OASIS Standard, or Approved Errata).
[OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this deliverable.]
[OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this OASIS Standards Final Deliverable. OASIS may include such claims on its website, but disclaims any obligation to do so.]
-[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this OASIS Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Standards Final Deliverable, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]
-The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark/ for above guidance.
+[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this OASIS Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS’ procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Standards Final Deliverable, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]
+The name “OASIS” is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark/ for above guidance.