Merge remote-tracking branch 'origin/main' into 2018/null-results

docs/odata-csdl-json/odata-csdl-json.md

@@ -268,10 +268,12 @@ Section | Feature / Change | Issue
 [Section 3.4.5](#SRID)| SRID value `variable` is deprecated| [1935](https://github.com/oasis-tcs/odata-specs/issues/1935)
 [Section 4](#CSDLJSONDocument) | Additional `$Version` value `4.02` |
 [Section 12](#ActionandFunction) | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348)
+[Section 12.8](#ReturnType) | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983)
 [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654)
 [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654)
 [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575)
 [Section 14.4.7](#IfThenElse)| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326)
+[Section 15.2](#SimpleIdentifier) | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375)
 [Section 17](#Conformance) | Additional conformance clauses for version 4.02 |
 
 ## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -672,7 +674,7 @@ length.
 
 The value of `$MaxLength` is a positive integer.
 
-Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic
+Note: [OData-CSDLXML, section 3.4.1](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#MaxLength) defines a symbolic
 value `max` that is only allowed in OData 4.0 responses. This symbolic
 value is not allowed in CDSL JSON documents at all. Services MAY instead
 specify the concrete maximum length supported for the type by the
@@ -992,8 +994,8 @@ The
 annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to
 indicate a particular version of the referenced document. If the
 [`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion)
-annotation is present, the `$schemaversion` system query option, defined
-[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the
+annotation is present, the `$schemaversion` system query option, defined in
+[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the
 referenced schema document.
 
 ::: {.varjson .rep}
@@ -1499,7 +1501,7 @@ Note: structural and navigation properties MAY be returned by the
 service on instances of any structured type, whether or not the type is
 marked as open. Clients MUST always be prepared to deal with additional
 properties on instances of any structured type, see
-[OData-Protocol](#ODataProtocol).
+[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel).
 
 ::: {.varjson .rep}
 ### <a id="OpenType.5.3" href="#OpenType.5.3">`$OpenType`</a>
@@ -1520,7 +1522,7 @@ entity with one or more properties of type `Edm.Stream` if the
 structured data of the entity is the main topic of interest and the
 stream data is just additional information attached to the structured
 data. For more information on media entities see
-[OData-Protocol](#ODataProtocol).
+[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue).
 
 An entity type derived from a media entity type MUST indicate that it is
 also a media entity type.
@@ -1581,7 +1583,7 @@ on one of these primitive types:
 
 Key property values MAY be language-dependent, but their values MUST be
 unique across all languages and the entity-ids (defined in
-[OData-Protocol](#ODataProtocol)) MUST be language independent.
+[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent.
 
 A key property MUST be a non-nullable primitive property of the entity
 type itself, including non-nullable primitive properties of non-nullable
@@ -1864,7 +1866,7 @@ If no value is specified, the client SHOULD NOT assume a default value.
 
 The value of `$DefaultValue` is the type-specific JSON representation of
 the default value of the property, see
-[OData-JSON](#ODataJSON). For properties of type
+[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). For properties of type
 `Edm.Decimal` and `Edm.Int64` the representation depends on the media
 type parameter
 [`IEEE754Compatible`](#ControllingtheRepresentationofNumbers).
@@ -2071,7 +2073,7 @@ the entities referenced by the containment navigation property. The
 canonical URL for contained entities is the canonical URL of the
 containing instance, followed by the path segment of the navigation
 property and the key of the contained entity, see
-[OData-URL](#ODataURL).
+[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities).
 
 Entity types used in collection-valued containment navigation properties
 MUST have a [key](#Key) defined.
@@ -2393,7 +2395,7 @@ Note: structural and navigation properties MAY be returned by the
 service on instances of any structured type, whether or not the type is
 marked as open. Clients MUST always be prepared to deal with additional
 properties on instances of any structured type, see
-[OData‑Protocol](#ODataProtocol).
+[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel).
 
 ::: {.varjson .rep}
 ### <a id="OpenType.8.3" href="#OpenType.8.3">`$OpenType`</a>
@@ -2895,10 +2897,7 @@ Absence of the `$Type` member means the type is `Edm.String`.
 The value of `$Nullable` is one of the Boolean literals `true` or
 `false`. Absence of the member means `false`.
 
-If the return type is a collection of entity types, the `$Nullable`
-member has no meaning and MUST NOT be specified.
-
-For other collection-valued return types the result will always be a
+For collection-valued return types the result will always be a
 collection that MAY be empty. In this case `$Nullable` applies to items
 of the collection and specifies whether the collection MAY contain
 `null` values.
@@ -3543,7 +3542,7 @@ Metadata annotations are applied in CSDL documents describing or
 referencing an entity model.
 
 *Instance annotations* are terms applied to a particular instance within
-an OData payload, such as described in [OData-JSON](#ODataJSON). An
+an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An
 instance annotation can be used to define additional information
 associated with a particular result, entity, property, or error. For
 example, whether a property is read-only for a particular instance.
@@ -3685,10 +3684,10 @@ of the collection and specifies whether the collection MAY contain
 
 The value of `$DefaultValue` is the type-specific JSON representation of
 the default value of the term, see
-[OData-JSON](#ODataJSON).
+[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue).
 
 Note: the `$DefaultValue` member is purely for documentation and
-isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in
+isomorphy to [OData-CSDLXML, section 7.3](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#DefaultValue). Annotations in
 CSDL JSON documents MUST always specify an explicit value.
 :::
 
@@ -4205,7 +4204,7 @@ Example 57:
 ### <a id="GeoValues" href="#GeoValues">14.3.13 Geo Values</a>
 
 ::: {.varjson .rep}
-Values are represented as GeoJSON, see [OData-JSON](#ODataJSON).
+Values are represented as GeoJSON, see [RFC7946](#rfc7946).
 :::
 
 ::: {.varjson .example}
@@ -4220,7 +4219,7 @@ Example 58:
 ### <a id="StreamValues" href="#StreamValues">14.3.14 Stream Values</a>
 
 ::: {.varjson .rep}
-Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted.
+Constant values of type `Edm.Stream` are represented according to [OData-JSON, section 9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#StreamProperty) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted.
 :::
 
 
@@ -4268,7 +4267,7 @@ than the `Edm.*Path` types.
 #### <a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a>
 
 Model paths and instance paths share a common syntax which is derived
-from the path expression syntax of URLs, see [OData-URL](#ODataURL).
+from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions).
 
 A path MUST be composed of zero or more path segments joined together by
 forward slashes (`/`).
@@ -4404,7 +4403,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati
 An instance path MAY contain path segments starting with an entity set
 or a collection-valued navigation property, then followed by a key
 predicate using parentheses-style convention, see
-[OData-URL](#ODataURL). The key values are either primitive literals or
+[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or
 instance paths. If the key value is a relative instance path, it is
 interpreted according to the same rule below as the instance path it is
 part of, *not* relative to the instance identified by the preceding path
@@ -4776,7 +4775,7 @@ they MAY be used anywhere instead of a Boolean expression.
 The `And` and `Or` operators require two operand expressions that
 evaluate to Boolean values. The `Not` operator requires a single operand
 expression that evaluates to a Boolean value. For details on null
-handling for comparison operators see [OData-URL](#ODataURL).
+handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators).
 
 The other comparison operators require two operand expressions that
 evaluate to comparable values.
@@ -4914,7 +4913,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be
 used anywhere instead of a numeric expression of the appropriate type.
 The semantics and evaluation rules for each arithmetic expression is
 identical to the corresponding arithmetic operator defined in
-[OData-URL](#ODataURL).
+[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators).
 
 Operator|Description
 --------|-----------
@@ -5047,10 +5046,10 @@ specification and its future versions.
 
 #### <a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a>
 
-All canonical functions defined in [OData-URL](#ODataURL) can be used as
+All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as
 client-side functions, qualified with the namespace `odata`. The
 semantics of these client-side functions is identical to their
-counterpart function defined in [OData-URL](#ODataURL).
+counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions).
 
 For example, the `odata.concat` client-side function takes two
 expressions as arguments. Each argument MUST evaluate to a primitive or
@@ -5232,7 +5231,7 @@ Example 80:
 The cast expression casts the value obtained from its single child
 expression to the specified type. The cast expression follows the same
 rules as the `cast` canonical function defined in
-[OData-URL](#ODataURL).
+[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast).
 
 ::: {.varjson .rep}
 ### <a id="Cast.21.22" href="#Cast.21.22">`$Cast`</a>
@@ -5560,7 +5559,7 @@ property value expression. The member name is the property name, and the
 member value is the property value expression.
 
 The type of a record expression is represented as the `type` control
-information, see  [OData-JSON](#ODataJSON).
+information, see [OData-JSON, section 4.6.3](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationtypeodatatype).
 
 It MAY contain [annotations](#Annotation) for itself and its members.
 Annotations for record members are prefixed with the member name.
@@ -5697,6 +5696,10 @@ restrictions:
 Non-normatively speaking it starts with a letter or underscore, followed
 by at most 127 letters, underscores or digits.
 
+For maximum interoperability services SHOULD use simple identifiers
+that additionally only consist of characters from the Basic Latin code block
+and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`.
+
 ## <a id="QualifiedName" href="#QualifiedName">15.3 Qualified Name</a>
 
 For model elements that are direct children of a schema: the namespace
@@ -6073,9 +6076,10 @@ In addition, OData 4.01 or greater services:
 schema, a structural type, or an entity container) that differ only by
 case
 
-In addition, OData 4.01 services:
+In addition, OData 4.02 or greater services:
 
 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations
+16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$`
 
 Conforming clients MUST be prepared to consume a model that uses any or
 all constructs defined in this specification, including custom
@@ -6155,6 +6159,10 @@ https://www.rfc-editor.org/info/rfc6570.
 _The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_.  
 https://www.rfc-editor.org/info/rfc7493.
 
+###### [RFC7946]{id=rfc7946}
+_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_.
+https://www.rfc-editor.org/info/rfc7946.
+
 ###### [RFC8174]{id=rfc8174}
 _Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_.  
 https://www.rfc-editor.org/info/rfc8174.
@@ -6316,7 +6324,7 @@ especially the contributions of
 - Patric Ksinsik (SAP SE)
 
 The contributions of the OASIS OData Technical Committee members,
-enumerated in [ODataProtocol](#ODataProtocol), are gratefully
+enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully
 acknowledged.
 
 ## <a id="Participants" href="#Participants">C.2 Participants</a>