Merge branch 'main' into ODATA-1626

docs/odata-csdl-json/odata-csdl-json.html

@@ -389,6 +389,11 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 <td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1420">ODATA-1420</a></td>
 </tr>
+<tr class="even">
+<td><a href="#PrimitiveTypes">Section 3.3</a></td>
+<td>Allow stream-valued non-binding parameters</td>
+<td><a href="https://issues.oasis-open.org/browse/ODATA-1481">ODATA-1481</a></td>
+</tr>
 </tbody>
 </table>
 <h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
@@ -639,7 +644,7 @@ <h2 id="33-primitive-types"><a name="PrimitiveTypes" href="#PrimitiveTypes">3.3
 </table>
 <p><code>Edm.Date</code> and <code>Edm.DateTimeOffset</code> follow <a href="#XML-Schema2">XML-Schema-2</a> and use the proleptic Gregorian calendar, allowing the year <code>0000</code> (equivalent to 1 BCE) and negative years (year <code>-0001</code> 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 <code>0001</code> to <code>9999</code>.</p>
 <p><code>Edm.Decimal</code> with a <a href="#Scale"><code>Scale</code></a> value of <code>floating</code>, <code>Edm.Double</code>, and <code>Edm.Single</code> allow the special numeric values <code>-INF</code>, <code>INF</code>, and <code>NaN</code>.</p>
-<p><code>Edm.Stream</code> is a primitive type that can be used as a property of an <a href="#EntityType">entity type</a> or <a href="#ComplexType">complex type</a>, the underlying type for a <a href="#TypeDefinition">type definition</a>, or the binding parameter or return type of an <a href="#Action">action</a> or <a href="#Function">function</a>. <code>Edm.Stream</code>, or a type definition whose underlying type is <code>Edm.Stream</code>, cannot be used in collections or for non-binding parameters to functions or actions.</p>
+<p><code>Edm.Stream</code> is a primitive type that can be used as a property of an <a href="#EntityType">entity type</a> or <a href="#ComplexType">complex type</a>, the underlying type for a <a href="#TypeDefinition">type definition</a>, or a binding or non-binding parameter or return type of an <a href="#Action">action</a> or <a href="#Function">function</a>. <code>Edm.Stream</code>, or a type definition whose underlying type is <code>Edm.Stream</code>, cannot be used in collections.</p>
 <p>Some of these types allow facets, defined in section “<a href="#TypeFacets">Type Facets</a>”.</p>
 <p>See rule <code>primitiveLiteral</code> in <a href="#ODataABNF">OData-ABNF</a> for the representation of primitive type values in URLs and <a href="#ODataJSON">OData-JSON</a> for the representation in requests and responses.</p>
 <h2 id="34-type-facets"><a name="TypeFacets" href="#TypeFacets">3.4 Type Facets</a></h2>

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

@@ -261,6 +261,7 @@ Section | Feature / Change | Issue
 --------|------------------|------
 [Section 14.2.2](#Target)| External targeting of bound action/function overloads via container or structured type| [ODATA-1626](https://issues.oasis-open.org/browse/ODATA-1626)
 [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [ODATA-1420](https://issues.oasis-open.org/browse/ODATA-1420)
+[Section 3.3](#PrimitiveTypes)| Allow stream-valued non-binding parameters| [ODATA-1481](https://issues.oasis-open.org/browse/ODATA-1481)
 
 ## <a name="Glossary" href="#Glossary">1.2 Glossary</a>
 
@@ -605,11 +606,11 @@ persistency layer, e.g. SQL only supports years `0001` to `9999`.
 
 `Edm.Stream` is a primitive type that can be used as a property of an
 [entity type](#EntityType) or [complex type](#ComplexType), the
-underlying type for a [type definition](#TypeDefinition), or the binding
+underlying type for a [type definition](#TypeDefinition), or a binding or non-binding
 parameter or return type of an [action](#Action) or
-[function](#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.
+[function](#Function).
+`Edm.Stream`, or a type definition whose
+underlying type is `Edm.Stream`, cannot be used in collections.
 
 Some of these types allow facets, defined in section
 "[Type Facets](#TypeFacets)".

docs/odata-csdl-xml/odata-csdl-xml.html

@@ -389,6 +389,11 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 <td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1420">ODATA-1420</a></td>
 </tr>
+<tr class="odd">
+<td><a href="#PrimitiveTypes">Section 3.3</a></td>
+<td>Allow stream-valued non-binding parameters</td>
+<td><a href="https://issues.oasis-open.org/browse/ODATA-1481">ODATA-1481</a></td>
+</tr>
 </tbody>
 </table>
 <h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
@@ -637,7 +642,7 @@ <h2 id="33-primitive-types"><a name="PrimitiveTypes" href="#PrimitiveTypes">3.3
 </table>
 <p><code>Edm.Date</code> and <code>Edm.DateTimeOffset</code> follow <a href="#XML-Schema2">XML-Schema-2</a> and use the proleptic Gregorian calendar, allowing the year <code>0000</code> (equivalent to 1 BCE) and negative years (year <code>-0001</code> 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 <code>0001</code> to <code>9999</code>.</p>
 <p><code>Edm.Decimal</code> with a <a href="#Scale"><code>Scale</code></a> value of <code>floating</code>, <code>Edm.Double</code>, and <code>Edm.Single</code> allow the special numeric values <code>-INF</code>, <code>INF</code>, and <code>NaN</code>.</p>
-<p><code>Edm.Stream</code> is a primitive type that can be used as a property of an <a href="#EntityType">entity type</a> or <a href="#ComplexType">complex type</a>, the underlying type for a <a href="#TypeDefinition">type definition</a>, or the binding parameter or return type of an <a href="#Action">action</a> or <a href="#Function">function</a>. <code>Edm.Stream</code>, or a type definition whose underlying type is <code>Edm.Stream</code>, cannot be used in collections or for non-binding parameters to functions or actions.</p>
+<p><code>Edm.Stream</code> is a primitive type that can be used as a property of an <a href="#EntityType">entity type</a> or <a href="#ComplexType">complex type</a>, the underlying type for a <a href="#TypeDefinition">type definition</a>, or a binding or non-binding parameter or return type of an <a href="#Action">action</a> or <a href="#Function">function</a>. <code>Edm.Stream</code>, or a type definition whose underlying type is <code>Edm.Stream</code>, cannot be used in collections.</p>
 <p>Some of these types allow facets, defined in section “<a href="#TypeFacets">Type Facets</a>”.</p>
 <p>See rule <code>primitiveLiteral</code> in <a href="#ODataABNF">OData-ABNF</a> for the representation of primitive type values in URLs and <a href="#ODataJSON">OData-JSON</a> for the representation in requests and responses.</p>
 <h2 id="34-type-facets"><a name="TypeFacets" href="#TypeFacets">3.4 Type Facets</a></h2>

docs/odata-csdl-xml/odata-csdl-xml.md

@@ -260,6 +260,7 @@ Section | Feature / Change | Issue
 [Section 13](#EntityContainer)| All children of `edm:EntityContainer` are optional| [ODATA-1571](https://issues.oasis-open.org/browse/ODATA-1571)
 [Section 14.2.2](#Target)| External targeting of bound action/function overloads via container or structured type| [ODATA-1626](https://issues.oasis-open.org/browse/ODATA-1626)
 [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [ODATA-1420](https://issues.oasis-open.org/browse/ODATA-1420)
+[Section 3.3](#PrimitiveTypes)| Allow stream-valued non-binding parameters| [ODATA-1481](https://issues.oasis-open.org/browse/ODATA-1481)
 
 ## <a name="Glossary" href="#Glossary">1.2 Glossary</a>
 
@@ -546,11 +547,11 @@ persistency layer, e.g. SQL only supports years `0001` to `9999`.
 
 `Edm.Stream` is a primitive type that can be used as a property of an
 [entity type](#EntityType) or [complex type](#ComplexType), the
-underlying type for a [type definition](#TypeDefinition), or the binding
+underlying type for a [type definition](#TypeDefinition), or a binding or non-binding
 parameter or return type of an [action](#Action) or
-[function](#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.
+[function](#Function).
+`Edm.Stream`, or a type definition whose
+underlying type is `Edm.Stream`, cannot be used in collections.
 
 Some of these types allow facets, defined in section
 "[Type Facets](#TypeFacets)".

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

@@ -1641,7 +1641,7 @@ <h1 id="17-bound-action"><a name="BoundAction" href="#BoundAction">17 Bound Acti
 <hr />
 <h1 id="18-action-invocation"><a name="ActionInvocation" href="#ActionInvocation">18 Action Invocation</a></h1>
 <p>Action parameter values are encoded in a single JSON object in the request body.</p>
-<p>Each non-binding parameter value is encoded as a separate name/value pair in this JSON object. The name is the name of the parameter. The value is the parameter value in the JSON representation appropriate for its type. Entity typed parameter values MAY include a subset of the properties, or just the <a href="#EntityReference">entity reference</a>, as appropriate to the action.</p>
+<p>Each non-binding parameter value is encoded as a separate name/value pair in this JSON object. The name is the name of the parameter. The value is the parameter value in the JSON representation appropriate for its type. Entity typed parameter values MAY include a subset of the properties, or just the <a href="#EntityReference">entity reference</a>, as appropriate to the action. Stream typed parameter values are represented following the same rules as inlined <a href="#StreamProperty">stream properties</a>.</p>
 <p>Non-binding parameters that are nullable or annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> defined in <a href="#ODataVocCore">OData-VocCore</a> MAY be omitted from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the <code>null</code> value. If it is annotated and the annotation specifies a <code>DefaultValue</code>, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of <code>null</code>.</p>
 <div class="example">
 <p>Example 46:</p>

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

@@ -2952,6 +2952,7 @@ value is the parameter value in the JSON representation appropriate for
 its type. Entity typed parameter values MAY include a subset of the
 properties, or just the [entity reference](#EntityReference), as
 appropriate to the action.
+Stream typed parameter values are represented following the same rules as inlined [stream properties](#StreamProperty).
 
 Non-binding parameters that are nullable or annotated with the term
 [`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#OptionalParameter) defined in

docs/odata-protocol/odata-protocol.html

@@ -498,6 +498,11 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1609">ODATA-1609</a></td>
 </tr>
 <tr class="even">
+<td><a href="#UpsertanEntity">Section 11.4.4</a></td>
+<td>Upserts to single-valued non-containment navigation properties</td>
+<td><a href="https://issues.oasis-open.org/browse/ODATA-1588">ODATA-1588</a></td>
+</tr>
+<tr class="odd">
 <td><a href="#UpdateaComplexProperty">Section 11.4.9.3</a></td>
 <td>Setting a complex property to a different type</td>
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1472">ODATA-1472</a></td>
@@ -1896,7 +1901,13 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a name="UpdateRe
 <p>On failure, the service MUST NOT apply any of the changes specified in the request.</p>
 <h3 id="1144-upsert-an-entity"><a name="UpsertanEntity" href="#UpsertanEntity">11.4.4 Upsert an Entity</a></h3>
 <p>An upsert occurs when the client sends an <a href="#UpdateanEntity">update request</a> to a valid URL that identifies a single entity that does not yet exist. In this case the service MUST handle the request as a <a href="#CreateanEntity">create entity request</a> or fail the request altogether.</p>
-<p>Upserts are not supported against <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entities</a>, single-valued non-containment navigation properties, or entities whose keys values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.</p>
+<p>Upserts to single-valued navigation properties are possible for</p>
+<ul>
+<li>containment navigation properties,</li>
+<li>non-containment navigation properties with a navigation property binding, or</li>
+<li>payloads including a context URL specifying the entity set or contained collection of entities in which the new entity is to be created.</li>
+</ul>
+<p>Upserts are not supported against <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entities</a> or entities whose keys values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.</p>
 <p>Singleton entities can be upserted if they are nullable. Services supporting this SHOULD advertise it by annotating the singleton with the term <code>Capabilities.UpdateRestrictions</code> (nested property <code>Upsertable</code> with value <code>true</code>) defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
 <p>Key and other non-updatable properties, as well as dependent properties that are not tied to key properties of the principal entity, MUST be ignored by the service in processing the Upsert request.</p>
 <p>To ensure that an update request is not treated as an insert, the client MAY specify an <a href="#HeaderIfMatch"><code>If-Match</code></a> header in the update request. The service MUST NOT treat an update request containing an <code>If-Match</code> header as an insert.</p>

docs/odata-protocol/odata-protocol.md

@@ -347,6 +347,7 @@ resource representations that are exchanged using OData.
 Section | Feature / Change | Issue
 --------|------------------|------
 [Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)
+[Section 11.4.4](#UpsertanEntity)|  Upserts to single-valued non-containment navigation properties| [ODATA-1588](https://issues.oasis-open.org/browse/ODATA-1588)
 [Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [ODATA-1472](https://issues.oasis-open.org/browse/ODATA-1472)
 
 ## <a name="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -4521,11 +4522,16 @@ that does not yet exist. In this case the service MUST handle the
 request as a [create entity request](#CreateanEntity) or fail the
 request altogether.
 
+Upserts to single-valued navigation properties are possible for
+- containment navigation properties,
+- non-containment navigation properties with a navigation property binding, or
+- payloads including a context URL specifying the entity set or
+  contained collection of entities in which the new entity is to be created.
+
 Upserts are not supported against [media
-entities](#RequestingtheMediaStreamofaMediaEntityusingvalue), single-valued
-non-containment navigation properties, or entities whose keys values are
-generated by the service. Services MUST fail an update request to a URL
-that would identify such an entity and the entity does not yet exist.
+entities](#RequestingtheMediaStreamofaMediaEntityusingvalue)
+or entities whose keys values are
+generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.
 
 Singleton entities can be upserted if they are nullable. Services
 supporting this SHOULD advertise it by annotating the singleton with the

docs/odata-url-conventions/odata-url-conventions.html

@@ -678,14 +678,15 @@ <h3 id="451-addressing-actions"><a name="AddressingActions" href="#AddressingAct
 <li>The <code>boundOperation</code> syntax rule (which encompasses the <code>boundActionCall</code> syntax rule), when used by the <code>resourcePath</code> syntax rule, illustrates how a <code>boundActionCall</code> can be appended to a <code>resourcePath</code>.</li>
 </ul>
 <h3 id="452-addressing-functions"><a name="AddressingFunctions" href="#AddressingFunctions">4.5.2 Addressing Functions</a></h3>
-<p>The grammar for addressing and invoking functions is defined by a number syntax grammar rules in <a href="#ODataABNF">OData-ABNF</a>, in particular:</p>
+<p>The grammar for addressing and invoking functions is defined by syntax rules in <a href="#ODataABNF">OData-ABNF</a>, in particular:</p>
 <ul>
 <li>The function import call syntax rules <code>complexFunctionImportCall</code>, <code>complexColFunctionImportCall</code>, <code>entityFunctionImportCall</code>, <code>entityColFunctionImportCall</code>, <code>primitiveFunctionImportCall</code>, and <code>primitiveColFunctionImportCall</code> define the grammar in the <code>resourcePath</code> for addressing and providing parameters for a function import directly from the service root.</li>
 <li>The bound function call syntax rules <code>boundComplexFunctionCall</code>, <code>boundComplexColFunctionCall</code>, <code>boundEntityFunctionCall</code>, <code>boundEntityColFunctionCall</code>, <code>boundPrimitiveFunctionCall</code> and <code>boundPrimitiveColFunctionCall</code> define the grammar in the <code>resourcePath</code> for addressing and providing parameters for a function that is appended to a <code>resourcePath</code> that identifies some resources that can be used as the binding parameter value when invoking the function.</li>
 <li>The <code>boundOperation</code> syntax rule (which encompasses the bound function call syntax rules), when used by the <code>resourcePath</code> syntax rule, illustrates how a bound function call can be appended to a <code>resourcePath</code>.</li>
 <li>The <code>functionExpr</code> and <code>boundFunctionExpr</code> syntax rules as used by the <code>commonExpr</code> syntax rule define the grammar for invoking functions, for example to help filter and order resources identified by the <code>resourcePath</code> of the URL.</li>
 <li>The <code>aliasAndValue</code> syntax rule defines the grammar for providing function parameter values using Parameter Alias Syntax, see <a href="#ODataProtocol">OData-Protocol</a>.</li>
 </ul>
+<p>Note: there is no literal representation for <code>Edm.Stream</code> values in URLs, so it is not possible to pass <code>Edm.Stream</code> values to parameters of function imports or to non-binding parameters of bound functions used in the resource path. Function expressions within query options can use <a href="#PathExpressions">path expressions</a> of type <code>Edm.Stream</code> as values of non-binding function parameters.</p>
 <h2 id="46-addressing-a-property"><a name="AddressingaProperty" href="#AddressingaProperty">4.6 Addressing a Property</a></h2>
 <p>To address an entity property clients append a path segment containing the property name to the URL of the entity. If the property has a complex type value, properties of that value can be addressed by further property name composition.</p>
 <h2 id="47-addressing-a-raw-value"><a name="AddressingaRawValue" href="#AddressingaRawValue">4.7 Addressing a Raw Value</a></h2>