From 2960cabb804ec22d83b3af307c3971de07f0b74f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 25 Jul 2023 17:10:04 +0200 Subject: [PATCH] Chapters 16 to 18 --- docs/odata-json-format/odata-json-format.html | 118 +++++++ docs/odata-json-format/odata-json-format.md | 254 ++++++++++++++++ odata-json-format/16 Bound Function.md | 254 ++++++++++++++++ .../temp/odata-json-format-v4.01-os.md | 287 ------------------ 4 files changed, 626 insertions(+), 287 deletions(-) diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index a980a1df0..13f9fc826 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -1368,10 +1368,128 @@

16 Bound Function

+

A bound function is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule qualifiedFunctionName in OData-ABNF.

+

A function that is bound to a single structured type MAY be advertised within the JSON object representing that structured type.

+

Functions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the function advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the function advertisement is prepended with the name of the collection-valued property and is placed next to the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise functions prefixed with property names.

+

If the function is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the function with the value null.

+

If metadata=full is requested, each value object MUST have at least the two name/value pairs title and target. It MAY contain annotations. The order of the name/value pairs MUST be considered insignificant.

+

The target name/value pair contains a URL. Clients MUST be able to invoke the function or the specific function overload by passing the parameter values via query options for parameter aliases that are identical to the parameter name preceded by an at (@) sign. Clients MUST check if the obtained URL already contains a query part and appropriately precede the parameters either with an ampersand (&) or a question mark (?).

+

The title name/value pair contains the function or action title as a string.

+

If metadata=minimal is requested, the target name/value pair MUST be included if its value differs from the canonical function or action URL.

+
+

Example 40: minimal representation of a function where all overloads are applicable

+
{
+  "@context": "http://host/service/$metadata#Employees/$entity",
+  "#Model.RemainingVacation": {},
+  ...
+}
+
+
+

Example 41: full representation of a specific overload with parameter alias for the Year parameter

+
{
+  "@context": "http://host/service/$metadata#Employees/$entity",
+  "#Model.RemainingVacation(Year)": {
+    "title": "Remaining vacation from year.",
+    "target": "Employees(2)/RemainingVacation(Year=@Year)"
+  },
+  ...
+}
+
+
+

Example 42: full representation in a collection

+
{
+  "@context": "http://host/service/$metadata#Employees",
+  "#Model.RemainingVacation": {
+    "title": "Remaining Vacation",
+    "target": "Managers(22)/Employees/RemainingVacation"
+  },
+  "value": [ ... ]
+}
+
+
+

Example 43: full representation in a nested collection

+
{
+  "@context": "http://host/service/$metadata#Employees/$entity",
+  "@type": "Model.Manager",
+  "ID":22,
+  ...
+  "Employees#RemainingVacation": {
+    "title": "RemainingVacation",
+    "target": "Managers(22)/Employees/RemainingVacation"
+  }
+}
+

17 Bound Action

+

A bound action is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML

+

An action that is bound to a single structured type is advertised within the JSON object representing that structured type.

+

Actions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the action advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the action advertisement is prepended with the name of the collection-valued property and is placed next to the name/value pair representing the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise actions prefixed with property names.

+

If the action is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the action with the value null.

+

If metadata=full is requested, each value object MUST have at least the two name/value pairs title and target. It MAY contain annotations. The order of these name/value pairs MUST be considered insignificant.

+

The target name/value pair contains a bound function or action URL.

+

The title name/value pair contains the function or action title as a string.

+

If metadata=minimal is requested, the target name/value pair MUST be included if its value differs from the canonical function or action URL.

+
+

Example 44: minimal representation in an entity

+
{
+  "@context": "http://host/service/$metadata#LeaveRequests/$entity",
+  "#Model.Approve": {},
+  ...
+}
+
+
+

Example 45: full representation in an entity:

+
{
+  "@context": "http://host/service/$metadata#LeaveRequests/$entity",
+  "#Model.Approve": {
+    "title": "Approve Leave Request",
+    "target": "LeaveRequests(2)/Approve"
+  },
+  ...
+}
+
+
+

Example 46: full representation in a collection

+
{
+  "@context": "http://host/service/$metadata#LeaveRequests",
+  "#Model.Approve": {
+    "title": "Approve All Leave Requests",
+    "target": "Employees(22)/Model.Manager/LeaveRequests/Approve"
+  },
+  "value": [ ... ]
+}
+
+
+

Example 47: full representation in a nested collection

+
{
+  "@context": "http://host/service/$metadata#Employees/$entity",
+  "@type": "Model.Manager",
+  "ID": 22,
+  ...
+  "LeaveRequests#Model.Approve": {
+    "title": "Approve All Leave Requests",
+    "target": "Employees(22)/Model.Manager/LeaveRequests/Approve"
+  }
+}
+

18 Action Invocation

+

Action parameter values are encoded in a single JSON object in the request body.

+

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 entity reference, as appropriate to the action.

+

Non-binding parameters that are nullable or annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the null value. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of null.

+
+

Example 46:

+
{
+  "param1": 42,
+  "param2": {
+    "Street": "One Microsoft Way",
+    "Zip": 98052
+  },
+  "param3": [ 1, 42, 99 ],
+  "param4": null
+}
+
+

In order to invoke an action with no non-binding parameters, the client passes an empty JSON object in the body of the request. 4.01 Services MUST also support clients passing an empty request body for this case.

19 Batch Requests and Responses

19.1 Batch Request

diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 78675d5dd..ab0e0c665 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -2564,14 +2564,268 @@ inline as a delta # 16 Bound Function +A bound function is advertised via a name/value pair where the name is a +hash (`#`) character followed by the namespace- or +alias-qualified name of the function. The namespace or alias MUST be +defined or the namespace referenced in the metadata document of the +service, see [OData-CSDLJSON](#ODataCSDL) or +[OData-CSDLXML](#ODataCSDL) A +specific function overload can be advertised by appending the +parentheses-enclosed, comma-separated list of non-binding parameter +names to the qualified function name, see rule +`qualifiedFunctionName` in [OData-ABNF](#ODataABNF). + +A function that is bound to a single structured type MAY be advertised +within the JSON object representing that structured type. + +Functions that are bound to a collection MAY be advertised within the +JSON object containing the collection. If the collection is the +top-level response, the function advertisement name/value pair is placed +next to the `value` name/value pair representing the +collection. If the collection is nested within an instance of a +structured type, then in 4.01 payloads the name of the function +advertisement is prepended with the name of the collection-valued +property and is placed next to the collection-valued property, [expanded +navigation property](#ExpandedNavigationProperty), or +[`navigationLink`](#NavigationLink) +control information, if present. 4.0 payloads MUST NOT advertise +functions prefixed with property names. + +If the function is available, the value of the advertisement is an +object. OData 4.01 services MAY advertise the non-availability of the +function with the value `null`. + +If +[`metadata=full`](#metadatafullodatametadatafull) +is requested, each value object MUST have at least the two name/value +pairs `title` and `target`. It MAY contain +[annotations](#InstanceAnnotations). The order of the name/value +pairs MUST be considered insignificant. + +The `target` name/value pair contains a URL. Clients MUST be +able to invoke the function or the specific function overload by passing +the parameter values via query options for [parameter +aliases](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ParameterAliases) that are identical to +the parameter name preceded by an at +(`@`) sign. Clients MUST check if the obtained +URL already contains a query part and appropriately precede the +parameters either with an ampersand +(`&`) +or a question mark +(`?`). + +The `title` name/value pair contains the function or action +title as a string. + +If [`metadata=minimal`](#metadataminimalodatametadataminimal) +is requested, the `target` name/value pair MUST be included +if its value differs from the canonical function or action URL. + +::: example +Example 40: minimal representation of a function where all overloads are +applicable +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "#Model.RemainingVacation": {}, + ... +} +``` +::: + +::: example +Example 41: full representation of a specific overload with parameter +alias for the `Year` parameter +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "#Model.RemainingVacation(Year)": { + "title": "Remaining vacation from year.", + "target": "Employees(2)/RemainingVacation(Year=@Year)" + }, + ... +} +``` +::: + +::: example +Example 42: full representation in a collection +```json +{ + "@context": "http://host/service/$metadata#Employees", + "#Model.RemainingVacation": { + "title": "Remaining Vacation", + "target": "Managers(22)/Employees/RemainingVacation" + }, + "value": [ ... ] +} +``` +::: + +::: example +Example 43: full representation in a nested collection +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "@type": "Model.Manager", + "ID":22, + ... + "Employees#RemainingVacation": { + "title": "RemainingVacation", + "target": "Managers(22)/Employees/RemainingVacation" + } +} +``` +::: + ------- # 17 Bound Action +A bound action is advertised via a name/value pair where the name is a +hash (`#`) character followed by the namespace- or +alias-qualified name of the action. The namespace or alias MUST be +defined or the namespace referenced in the metadata document of the +service, see [OData-CSDLJSON](#ODataCSDL) or +[OData-CSDLXML](#ODataCSDL) + +An action that is bound to a single structured type is advertised within +the JSON object representing that structured type. + +Actions that are bound to a collection MAY be advertised within the JSON +object containing the collection. If the collection is the top-level +response, the action advertisement name/value pair is placed next to the +`value` name/value pair representing the collection. If the +collection is nested within an instance of a structured type, then in +4.01 payloads the name of the action advertisement is prepended with the +name of the collection-valued property and is placed next to the +name/value pair representing the collection-valued property, [expanded +navigation property](#ExpandedNavigationProperty), or +[`navigationLink`](#NavigationLink) +control information, if present. 4.0 payloads MUST NOT advertise actions +prefixed with property names. + +If the action is available, the value of the advertisement is an object. +OData 4.01 services MAY advertise the non-availability of the action +with the value `null`. + +If [`metadata=full`](#metadatafullodatametadatafull) +is requested, each value object MUST have at least the two name/value +pairs `title` and `target`. It MAY contain +[annotations](#InstanceAnnotations). The order of these name/value +pairs MUST be considered insignificant. + +The `target` name/value pair contains a bound function or +action URL. + +The `title` name/value pair contains the function or action +title as a string. + +If [`metadata=minimal`](#metadataminimalodatametadataminimal) +is requested, the `target` name/value pair MUST be included +if its value differs from the canonical function or action URL. + +::: example +Example 44: minimal representation in an entity +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests/$entity", + "#Model.Approve": {}, + ... +} +``` +::: + +::: example +Example 45: full representation in an entity: +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests/$entity", + "#Model.Approve": { + "title": "Approve Leave Request", + "target": "LeaveRequests(2)/Approve" + }, + ... +} +``` +::: + +::: example +Example 46: full representation in a collection +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests", + "#Model.Approve": { + "title": "Approve All Leave Requests", + "target": "Employees(22)/Model.Manager/LeaveRequests/Approve" + }, + "value": [ ... ] +} +``` +::: + +::: example +Example 47: full representation in a nested collection +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "@type": "Model.Manager", + "ID": 22, + ... + "LeaveRequests#Model.Approve": { + "title": "Approve All Leave Requests", + "target": "Employees(22)/Model.Manager/LeaveRequests/Approve" + } +} +``` +::: + ------- # 18 Action Invocation +Action parameter values are encoded in a single JSON object in the +request body. + +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 [entity reference](#EntityReference), as +appropriate to the action. + +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 +[OData-VocCore](#ODataVocCore) MAY be omitted from the request body. +If an omitted parameter is not annotated (and thus nullable), it MUST be +interpreted as having the `null` value. If it is annotated +and the annotation specifies a `DefaultValue`, the omitted +parameter is interpreted as having that default value. If omitted and +the annotation does not specify a default value, the service is free on +how to interpret the omitted parameter. Note: a nullable non-binding +parameter is equivalent to being annotated as optional with a default +value of `null`. + +::: example +Example 46: +```json +{ + "param1": 42, + "param2": { + "Street": "One Microsoft Way", + "Zip": 98052 + }, + "param3": [ 1, 42, 99 ], + "param4": null +} +``` +::: + + +In order to invoke an action with no non-binding parameters, the client +passes an empty JSON object in the body of the request. 4.01 Services +MUST also support clients passing an empty request body for this case. + ------- # 19 Batch Requests and Responses diff --git a/odata-json-format/16 Bound Function.md b/odata-json-format/16 Bound Function.md index 5d6041088..1c1139c26 100644 --- a/odata-json-format/16 Bound Function.md +++ b/odata-json-format/16 Bound Function.md @@ -2,10 +2,264 @@ # ##sec Bound Function +A bound function is advertised via a name/value pair where the name is a +hash (`#`) character followed by the namespace- or +alias-qualified name of the function. The namespace or alias MUST be +defined or the namespace referenced in the metadata document of the +service, see [OData-CSDLJSON](#ODataCSDL) or +[OData-CSDLXML](#ODataCSDL) A +specific function overload can be advertised by appending the +parentheses-enclosed, comma-separated list of non-binding parameter +names to the qualified function name, see rule +`qualifiedFunctionName` in [OData-ABNF](#ODataABNF). + +A function that is bound to a single structured type MAY be advertised +within the JSON object representing that structured type. + +Functions that are bound to a collection MAY be advertised within the +JSON object containing the collection. If the collection is the +top-level response, the function advertisement name/value pair is placed +next to the `value` name/value pair representing the +collection. If the collection is nested within an instance of a +structured type, then in 4.01 payloads the name of the function +advertisement is prepended with the name of the collection-valued +property and is placed next to the collection-valued property, [expanded +navigation property](#ExpandedNavigationProperty), or +[`navigationLink`](#NavigationLink) +control information, if present. 4.0 payloads MUST NOT advertise +functions prefixed with property names. + +If the function is available, the value of the advertisement is an +object. OData 4.01 services MAY advertise the non-availability of the +function with the value `null`. + +If +[`metadata=full`](#metadatafullodatametadatafull) +is requested, each value object MUST have at least the two name/value +pairs `title` and `target`. It MAY contain +[annotations](#InstanceAnnotations). The order of the name/value +pairs MUST be considered insignificant. + +The `target` name/value pair contains a URL. Clients MUST be +able to invoke the function or the specific function overload by passing +the parameter values via query options for [parameter +aliases](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ParameterAliases) that are identical to +the parameter name preceded by an at +(`@`) sign. Clients MUST check if the obtained +URL already contains a query part and appropriately precede the +parameters either with an ampersand +(`&`) +or a question mark +(`?`). + +The `title` name/value pair contains the function or action +title as a string. + +If [`metadata=minimal`](#metadataminimalodatametadataminimal) +is requested, the `target` name/value pair MUST be included +if its value differs from the canonical function or action URL. + +::: example +Example ##ex: minimal representation of a function where all overloads are +applicable +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "#Model.RemainingVacation": {}, + ... +} +``` +::: + +::: example +Example ##ex: full representation of a specific overload with parameter +alias for the `Year` parameter +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "#Model.RemainingVacation(Year)": { + "title": "Remaining vacation from year.", + "target": "Employees(2)/RemainingVacation(Year=@Year)" + }, + ... +} +``` +::: + +::: example +Example ##ex: full representation in a collection +```json +{ + "@context": "http://host/service/$metadata#Employees", + "#Model.RemainingVacation": { + "title": "Remaining Vacation", + "target": "Managers(22)/Employees/RemainingVacation" + }, + "value": [ ... ] +} +``` +::: + +::: example +Example ##ex: full representation in a nested collection +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "@type": "Model.Manager", + "ID":22, + ... + "Employees#RemainingVacation": { + "title": "RemainingVacation", + "target": "Managers(22)/Employees/RemainingVacation" + } +} +``` +::: + ------- # ##sec Bound Action +A bound action is advertised via a name/value pair where the name is a +hash (`#`) character followed by the namespace- or +alias-qualified name of the action. The namespace or alias MUST be +defined or the namespace referenced in the metadata document of the +service, see [OData-CSDLJSON](#ODataCSDL) or +[OData-CSDLXML](#ODataCSDL) + +An action that is bound to a single structured type is advertised within +the JSON object representing that structured type. + +Actions that are bound to a collection MAY be advertised within the JSON +object containing the collection. If the collection is the top-level +response, the action advertisement name/value pair is placed next to the +`value` name/value pair representing the collection. If the +collection is nested within an instance of a structured type, then in +4.01 payloads the name of the action advertisement is prepended with the +name of the collection-valued property and is placed next to the +name/value pair representing the collection-valued property, [expanded +navigation property](#ExpandedNavigationProperty), or +[`navigationLink`](#NavigationLink) +control information, if present. 4.0 payloads MUST NOT advertise actions +prefixed with property names. + +If the action is available, the value of the advertisement is an object. +OData 4.01 services MAY advertise the non-availability of the action +with the value `null`. + +If [`metadata=full`](#metadatafullodatametadatafull) +is requested, each value object MUST have at least the two name/value +pairs `title` and `target`. It MAY contain +[annotations](#InstanceAnnotations). The order of these name/value +pairs MUST be considered insignificant. + +The `target` name/value pair contains a bound function or +action URL. + +The `title` name/value pair contains the function or action +title as a string. + +If [`metadata=minimal`](#metadataminimalodatametadataminimal) +is requested, the `target` name/value pair MUST be included +if its value differs from the canonical function or action URL. + +::: example +Example ##ex: minimal representation in an entity +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests/$entity", + "#Model.Approve": {}, + ... +} +``` +::: + +::: example +Example ##ex: full representation in an entity: +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests/$entity", + "#Model.Approve": { + "title": "Approve Leave Request", + "target": "LeaveRequests(2)/Approve" + }, + ... +} +``` +::: + +::: example +Example ##ex: full representation in a collection +```json +{ + "@context": "http://host/service/$metadata#LeaveRequests", + "#Model.Approve": { + "title": "Approve All Leave Requests", + "target": "Employees(22)/Model.Manager/LeaveRequests/Approve" + }, + "value": [ ... ] +} +``` +::: + +::: example +Example ##ex: full representation in a nested collection +```json +{ + "@context": "http://host/service/$metadata#Employees/$entity", + "@type": "Model.Manager", + "ID": 22, + ... + "LeaveRequests#Model.Approve": { + "title": "Approve All Leave Requests", + "target": "Employees(22)/Model.Manager/LeaveRequests/Approve" + } +} +``` +::: + ------- # ##sec Action Invocation + +Action parameter values are encoded in a single JSON object in the +request body. + +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 [entity reference](#EntityReference), as +appropriate to the action. + +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 +[OData-VocCore](#ODataVocCore) MAY be omitted from the request body. +If an omitted parameter is not annotated (and thus nullable), it MUST be +interpreted as having the `null` value. If it is annotated +and the annotation specifies a `DefaultValue`, the omitted +parameter is interpreted as having that default value. If omitted and +the annotation does not specify a default value, the service is free on +how to interpret the omitted parameter. Note: a nullable non-binding +parameter is equivalent to being annotated as optional with a default +value of `null`. + +::: example +Example 46: +```json +{ + "param1": 42, + "param2": { + "Street": "One Microsoft Way", + "Zip": 98052 + }, + "param3": [ 1, 42, 99 ], + "param4": null +} +``` +::: + + +In order to invoke an action with no non-binding parameters, the client +passes an empty JSON object in the body of the request. 4.01 Services +MUST also support clients passing an empty request body for this case. diff --git a/odata-json-format/temp/odata-json-format-v4.01-os.md b/odata-json-format/temp/odata-json-format-v4.01-os.md index 5c391ee08..3fa3b510c 100644 --- a/odata-json-format/temp/odata-json-format-v4.01-os.md +++ b/odata-json-format/temp/odata-json-format-v4.01-os.md @@ -1,290 +1,3 @@ -# {#sec_BoundFunction}[16[ ]{style="font:7.0pt "Times New Roman""}][Bound Function](#BoundFunction) {#bound-function style="margin-left:19.85pt;text-indent:-19.85pt"} - -::: - -A bound function is advertised via a name/value pair where the name is a -hash (`\#`) character followed by the namespace- or -alias-qualified name of the function. The namespace or alias MUST be -defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML[.]{style="color:windowtext"}](#ODataCSDL) A -specific function overload can be advertised by appending the -parentheses-enclosed, comma-separated list of non-binding parameter -names to the qualified function name, see rule -`qualifiedFunctionName` in [OData-ABNF](#ODataABNF). - -A function that is bound to a single structured type MAY be advertised -within the JSON object representing that structured type. - -Functions that are bound to a collection MAY be advertised within the -JSON object containing the collection. If the collection is the -top-level response, the function advertisement name/value pair is placed -next to the `value` name/value pair representing the -collection. If the collection is nested within an instance of a -structured type, then in 4.01 payloads the name of the function -advertisement is prepended with the name of the collection-valued -property and is placed next to the collection-valued property, [expanded -navigation property](#ExpandedNavigationProperty), or -[`navigationLink`](#NavigationLink) -control information, if present. 4.0 payloads MUST NOT advertise -functions prefixed with property names. - -If the function is available, the value of the advertisement is an -object. OData 4.01 services MAY advertise the non-availability of the -function with the value `null`. - -If -[`metadata=full`](#metadatafullodatametadatafull) -is requested, each value object MUST have at least the two name/value -pairs `title` and `target`. It MAY contain -[annotations](#InstanceAnnotations). The order of the name/value -pairs MUST be considered insignificant. - -The `target` name/value pair contains a URL. Clients MUST be -able to invoke the function or the specific function overload by passing -the parameter values via query options for [parameter -aliases](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ParameterAliases)[[ -]{style="color:#0000EE"}]{.apple-converted-space}[that are identical to -the parameter name preceded by an at -(][[@]{style="font-family:"Courier New"; -color:black"}]{.datatype0}[) sign. Clients MUST check if the obtained -URL already contains a query part and appropriately precede the -parameters either with an ampersand -(][[&]{style="font-family:"Courier New";color:black"}]{.datatype0}[) -or a question mark -(][[?]{style="font-family:"Courier New";color:black"}]{.datatype0}[)]. - -The `title` name/value pair contains the function or action -title as a string. - -If -[`metadata=minimal`](#metadataminimalodatametadataminimal) -is requested, the `target` name/value pair MUST be included -if its value differs from the canonical function or action URL. - -::: example -Example ##ex: minimal representation of a function where all overloads are -applicable -```json -{ - "@context": -"http://host/service/$metadata#Employees/$entity", - "#Model.RemainingVacation": {}, - ... -} -``` -::: - -::: example -Example ##ex: full representation of a specific overload with parameter -alias for the [[Year]{style="font-size:10.0pt"}]{.Keyword} parameter -```json -{ - "@context": -"http://host/service/$metadata#Employees/$entity", - "#Model.RemainingVacation(Year)": { - "title": "Remaining vacation from year.", - "target": -"Employees(2)/RemainingVacation(Year=@Year)" - }, - ... -} -``` -::: - -::: example -Example ##ex: full representation in a collection -```json -{ - "@context": -"http://host/service/$metadata#Employees", - "#Model.RemainingVacation": { - "title": "Remaining Vacation", - "target": -"Managers(22)/Employees/RemainingVacation" - }, - "value": \[ ... \] -} -``` -::: - -{#\_Bound_Action}Example -41: full representation in a nested collection -```json -{ - "@context": -"http://host/service/$metadata#Employees/$entity", - "@type": "Model.Manager", - "ID":22, - ... - "Employees#RemainingVacation": { - "title": "RemainingVacation", - "target": -"Managers(22)/Employees/RemainingVacation" - } -} -``` -::: {style="border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in"} - -# {#sec_BoundAction}[17[ ]{style="font:7.0pt "Times New Roman""}][Bound Action](#BoundAction) {#bound-action style="margin-left:19.85pt;text-indent:-19.85pt"} - -::: - -A bound action is advertised via a name/value pair where the name is a -hash (`\#`) character followed by the namespace- or -alias-qualified name of the action. The namespace or alias MUST be -defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML[.]{style="color:windowtext"}](#ODataCSDL) - -An action that is bound to a single structured type is advertised within -the JSON object representing that structured type. - -Actions that are bound to a collection MAY be advertised within the JSON -object containing the collection. If the collection is the top-level -response, the action advertisement name/value pair is placed next to the -`value` name/value pair representing the collection. If the -collection is nested within an instance of a structured type, then in -4.01 payloads the name of the action advertisement is prepended with the -name of the collection-valued property and is placed next to the -name/value pair representing the collection-valued property, [expanded -navigation property](#ExpandedNavigationProperty), or -[`navigationLink`](#NavigationLink) -control information, if present. 4.0 payloads MUST NOT advertise actions -prefixed with property names. - -If the action is available, the value of the advertisement is an object. -OData 4.01 services MAY advertise the non-availability of the action -with the value `null`. - -If -[`metadata=full`](#metadatafullodatametadatafull) -is requested, each value object MUST have at least the two name/value -pairs `title` and `target`. It MAY contain -[annotations](#InstanceAnnotations). The order of these name/value -pairs MUST be considered insignificant. - -The `target` name/value pair contains a bound function or -action URL. - -The `title` name/value pair contains the function or action -title as a string. - -If -[`metadata=minimal`](#metadataminimalodatametadataminimal) -is requested, the `target` name/value pair MUST be included -if its value differs from the canonical function or action URL. - -::: example -Example ##ex: minimal representation in an entity -```json -{ - "@context": -"http://host/service/$metadata#LeaveRequests/$entity", - "#Model.Approve": {}, - ... -} -``` -::: - -::: example -Example ##ex: full representation in an entity: -```json -{ - "@context": -"http://host/service/$metadata#LeaveRequests/$entity", - "#Model.Approve": { - "title": "Approve Leave Request", - "target": "LeaveRequests(2)/Approve" - }, - ... -} -``` -::: - -::: example -Example ##ex: full representation in a collection -```json -{ - "@context": -"http://host/service/$metadata#LeaveRequests", - "#Model.Approve": { - "title": "Approve All Leave Requests", - "target": -"Employees(22)/Model.Manager/LeaveRequests/Approve" - }, - "value": \[ ... \] -} -``` -::: - -[Example] 45: full -representation in a nested collection -```json -{ - "@context": -"http://host/service/$metadata#Employees/$entity", - "@type": "Model.Manager", - "ID":22, - ... - "LeaveRequests#Model.Approve": { - "title": "Approve All Leave Requests", - "target": -"Employees(22)/Model.Manager/LeaveRequests/Approve" - } -} -``` -::: {style="border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in"} - -# {#sec_ActionInvocation}[18[ ]{style="font:7.0pt "Times New Roman""}][Action Invocation](#ActionInvocation) {#action-invocation style="margin-left:19.85pt;text-indent:-19.85pt"} - -::: - -Action parameter values are encoded in a single JSON object in the -request body. - -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 [entity reference](#EntityReference), as -appropriate to the action. - -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)[[ -]{style="font-family:"Arial",sans-serif"}]{.Datatype}defined in -[OData-VocCore](#ODataVocCore) MAY be omitted from the request body. -If an omitted parameter is not annotated (and thus nullable), it MUST be -interpreted as having the `null` value. If it is annotated -and the annotation specifies a `DefaultValue`, the omitted -parameter is interpreted as having that default value. If omitted and -the annotation does not specify a default value, the service is free on -how to interpret the omitted parameter. Note: a nullable non-binding -parameter is equivalent to being annotated as optional with a default -value of `null`. - -Example 46: -```json -{ - "param1": 42, - "param2": { - "Street": "One Microsoft Way", - "Zip": 98052 - }, - "param3": \[ 1, 42, 99 \], - "param4": null -} -``` -::: - - - -In order to invoke an action with no non-binding parameters, the client -passes an empty JSON object in the body of the request. 4.01 Services -MUST also support clients passing an empty request body for this case. - -::: {style="border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in"} - # {#sec_BatchRequestsandResponses}[19[ ]{style="font:7.0pt "Times New Roman""}][Batch Requests and Responses](#BatchRequestsandResponses) {#batch-requests-and-responses style="margin-left:19.85pt;text-indent:-19.85pt"} :::