Merge branch 'main' into ODATA-1435

README.md

@@ -28,7 +28,18 @@ Documents are generated from Markdown sources using Node.js modules described [h
 3. Download and install [git](https://git-scm.com/), verify via `git -v`
 4. Optionally download and install [GitHub Desktop](https://desktop.github.com/)
 5. Clone this repository
-6. In the local repository folder run `npm install`, verify via `npm test`
+6. In the local repository folder run `npm install`, verify via `npm test`  
+   Repeat this step if the test fails with an error message like the following after upgrading to a new Chrome version:
+   ```
+     1 failing
+   
+     1) OASIS doc build
+          Puppeteer:
+        Error: Could not find Chrome (ver. 116.0.5845.96). This can occur if either
+    1. you did not perform an installation before running the script (e.g. `npm install`) or
+    2. your cache path is incorrectly configured (which is: C:\Users\D024504\.cache\puppeteer).
+   For (2), check out our guide on configuring puppeteer at https://pptr.dev/guides/configuration.
+   ```
 
 ### Document preparation
 

docs/odata-json-format/odata-json-format.html

@@ -509,6 +509,7 @@ <h3 id="453-control-information-type-odatatype"><a name="ControlInformationtypeo
 <li>The type is derived from the type specified for the (collection of) entities or (collection of) complex type instances, or</li>
 <li>The type is for a property whose type is not declared in <code>$metadata</code>.</li>
 </ul>
+<p>It MAY appear in other cases in requests and responses if its value does not contradict the type declared in <code>$metadata</code>.</p>
 <p>The following heuristics are used to determine the primitive type of a dynamic property in the absence of the <code>type</code> control information:</p>
 <ul>
 <li>Boolean values have a first-class representation in JSON and do not need any additional control information.</li>
@@ -1577,7 +1578,7 @@ <h2 id="191-batch-request"><a name="BatchRequest" href="#BatchRequest">19.1 Batc
 <span id="cb52-39"><a href="#cb52-39" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
 </div>
 <h2 id="192-referencing-new-entities"><a name="ReferencingNewEntities" href="#ReferencingNewEntities">19.2 Referencing New Entities</a></h2>
-<p>The entity returned by a preceding request can be referenced in the request URL of subsequent requests.</p>
+<p>The entity returned by a preceding request can be referenced in the request URL of subsequent requests. If the <code>Location</code> header in the response contains a relative URL, clients MUST be able to resolve it relative to the request's URL even if that contains such a reference.</p>
 <div class="example">
 <p>Example 49: a batch request that contains the following operations in the order listed:</p>
 <ul>

docs/odata-json-format/odata-json-format.md

@@ -829,6 +829,8 @@ following is true:
 - The type is for a property whose type is not declared in
   `$metadata`.
 
+It MAY appear in other cases in requests and responses if its value does not contradict the type declared in `$metadata`.
+
 The following heuristics are used to determine the primitive type of a
 dynamic property in the absence of the `type` control
 information:
@@ -3007,7 +3009,9 @@ Content-Length: ###
 ## <a name="ReferencingNewEntities" href="#ReferencingNewEntities">19.2 Referencing New Entities</a>
 
 The entity returned by a preceding request can be referenced in the
-request URL of subsequent requests.
+request URL of subsequent requests. If the `Location` header in the response
+contains a relative URL, clients MUST be able to resolve it relative to the
+request's URL even if that contains such a reference.
 
 ::: example
 Example 49: a batch request that contains the following operations in

docs/odata-protocol/odata-protocol.html

@@ -1720,7 +1720,7 @@ <h4 id="11411-use-of-etags-for-avoiding-update-conflicts"><a name="UseofETagsfor
 <p>If the client does not specify an <a href="#HeaderIfMatch"><code>If-Match</code></a> request header in a <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a> on a resource that requires optimistic concurrency control, the service responds with a <code>428 Precondition Required</code> and MUST ensure that no observable change occurs as a result of the request. Clients can attempt to disable optimistic concurrency control by specifying <code>If-Match</code> with a value of <code>*</code>. Services MAY reject such requests.</p>
 <p>For requests including an <a href="#HeaderODataVersion"><code>OData-Version</code></a> header value of <code>4.01</code>, any ETag values specified in the request body of an <a href="#UpdateanEntity">update request</a> MUST be <code>*</code> or match the current value for the record being updated.</p>
 <h4 id="11412-handling-of-datetimeoffset-values"><a name="HandlingofDateTimeOffsetValues" href="#HandlingofDateTimeOffsetValues">11.4.1.2 Handling of DateTimeOffset Values</a></h4>
-<p>Services SHOULD preserve the offset of <code>Edm.DateTimeOffset</code> values, if possible. However, where the underlying storage does not support offset services may be forced to normalize the value to some common time zone (i.e. UTC) in which case the result would be returned with that time zone offset. If the service normalizes values, it MUST fail evaluation of the <a href="#BuiltinQueryFunctions">query functions</a> <code>year</code>, <code>month</code>, <code>day</code>, <code>hour</code>, and <code>time</code> for literal values that are not stated in the time zone of the normalized values.</p>
+<p>Services SHOULD preserve the offset of <code>Edm.DateTimeOffset</code> values, if possible. However, where the underlying storage does not support offset services may be forced to normalize the value to some common time zone (for example UTC) in which case the result would be returned with that time zone offset. If the service normalizes values, it MUST fail evaluation of the <a href="#BuiltinQueryFunctions">query functions</a> <code>year</code>, <code>month</code>, <code>day</code>, <code>hour</code>, and <code>time</code> for literal values that are not stated in the time zone of the normalized values.</p>
 <h4 id="11413-handling-of-properties-not-advertised-in-metadata"><a name="HandlingofPropertiesNotAdvertisedinMetadata" href="#HandlingofPropertiesNotAdvertisedinMetadata">11.4.1.3 Handling of Properties Not Advertised in Metadata</a></h4>
 <p>Clients MUST be prepared to receive additional properties in an entity or complex type instance that are not advertised in metadata, even for types not marked as open. By using <code>PATCH</code> when <a href="#UpdateanEntity">updating entities</a>, clients can ensure that such properties values are not lost if omitted from the update request.</p>
 <h4 id="11414-handling-of-integrity-constraints"><a name="HandlingofIntegrityConstraints" href="#HandlingofIntegrityConstraints">11.4.1.4 Handling of Integrity Constraints</a></h4>
@@ -2217,7 +2217,7 @@ <h3 id="1173-identifying-individual-requests"><a name="IdentifyingIndividualRequ
 <p>Each individual request within a batch request MAY have a request identifier assigned. The request identifier is case-sensitive, MUST be unique within the batch request, and MUST satisfy the rule <code>request-id</code> in <a href="#ODataABNF">OData-ABNF</a>.</p>
 <p>The representation of the request identifier is format-specific, as are the rules for which individual requests require an identifier.</p>
 <h3 id="1174-referencing-returned-entities"><a name="ReferencingReturnedEntities" href="#ReferencingReturnedEntities">11.7.4 Referencing Returned Entities</a></h3>
-<p>Entities created by an <a href="#CreateanEntity">insert</a> request can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL.</p>
+<p>Entities created by an <a href="#CreateanEntity">insert</a> request can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL. If the <a href="#HeaderLocation"><code>Location</code></a> header in the response contains a relative URL, clients MUST be able to resolve it relative to the request's URL even if that contains such a reference.</p>
 <p>If the <code>$</code>-prefixed request identifier is identical to the name of a top-level system resource (<code>$batch</code>, <code>$crossjoin,</code> <code>$all,</code> <code>$entity</code>, <code>$root</code>, <code>$id</code>, <code>$metadata</code>, or other system resources defined according to the <a href="#HeaderODataVersion"><code>OData-Version</code></a> of the protocol specified in the request), then the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.</p>
 <p>Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the <code>ReferencesInRequestBodiesSupported</code> property in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md#BatchSupport"><code>Capabilities.BatchSupport</code></a> term applied to the entity container, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
 <h3 id="1175-referencing-the-etag-of-an-entity"><a name="ReferencingtheETagofanEntity" href="#ReferencingtheETagofanEntity">11.7.5 Referencing the ETag of an Entity</a></h3>

docs/odata-protocol/odata-protocol.md

@@ -4004,7 +4004,7 @@ for the record being updated.
 Services SHOULD preserve the offset of `Edm.DateTimeOffset` values, if
 possible. However, where the underlying storage does not support offset
 services may be forced to normalize the value to some common time zone
-(i.e. UTC) in which case the result would be returned with that time
+(for example UTC) in which case the result would be returned with that time
 zone offset. If the service normalizes values, it MUST fail evaluation
 of the [query functions](#BuiltinQueryFunctions) `year`, `month`, `day`,
 `hour`, and `time` for literal values that are not stated in the time
@@ -5667,7 +5667,9 @@ the rules for which individual requests require an identifier.
 Entities created by an [insert](#CreateanEntity) request can be
 referenced in the request URL of subsequent requests by using the
 request identifier prefixed with a `$` character as the first segment of
-the request URL.
+the request URL. If the [`Location`](#HeaderLocation) header in the response contains a relative URL,
+clients MUST be able to resolve it relative to the request's URL even if
+that contains such a reference.
 
 If the `$`-prefixed request identifier is identical to the name of a
 top-level system resource (`$batch`, `$crossjoin,` `$all,` `$entity`,