Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-1446

Clarify usage of Edm.Stream-typed function and action parameters and return types

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_OS
    • Fix Version/s: V4.01_ERRATA01
    • Labels:
      None
    • Environment:

      Proposed

    • Proposal:
      Hide

      JSON Format

      • 18 Action Invocation: mention Edm.Stream for values of non-binding parameters, reference chapter 9 for their representation
      • (do not rename chapter 9)

      URL Conventions

      • 5.1.1.14.1 Primitive Literals: explicitly mention Edm.Stream literals, using same encoding as Edm.Binary literals, no cleartext representation for text/plain or application/json because we can't pass media-type control information in URL

      Protocol

      • Return type Edm.Stream has same behavior as Stream properties: return content-type and raw octet-stream according to content-type, allow content negotiation via Accept.
      Show
      JSON Format 18 Action Invocation: mention Edm.Stream for values of non-binding parameters, reference chapter 9 for their representation (do not rename chapter 9) URL Conventions 5.1.1.14.1 Primitive Literals: explicitly mention Edm.Stream literals, using same encoding as Edm.Binary literals, no cleartext representation for text/plain or application/json because we can't pass media-type control information in URL Protocol Return type Edm.Stream has same behavior as Stream properties: return content-type and raw octet-stream according to content-type, allow content negotiation via Accept.

      Description

      1. Edm.Stream-typed function parameters in URLs

      Today, the option to pass a value to an Edm.Stream-typed parameter in a request addressing a function import requires to look at different places and combine the individual steps (analogous for function calls):

      • Section on Addressing Functions in the URL conventions spec refers to certain ABNF rules (e.g., primitiveFunctionImportCall) that eventually lead to either rule parameterAlias or primitiveLiteral.
      • Following parameterAlias, section 5.3 Parameter Aliases in the same spec explains the relation to ABNF rule aliasAndValue, which finally gets us to parameterValue with arrayOrObject as one of the options.
      • Section 5.1.1.14.2 Complex and Collection Literals in the same spec defines the use of this ABNF rule arrayOrObject for complex and collection literals, but not for JSON documents as values of Edm.Stream-typed properties.
      • So, the only escape is to go the other route and use commonExpr, which is the other choice for arrayOrObject. This can become a primitiveValue, which includes a comment that strings can be used for JSON documents
      • So, finally we have found a rule to pass such a stream value

      It should be discussed if the consumption of this feature could be simplified by making it more explicit in the URL conventions spec.

       

      2. Edm.Stream-typed action parameters in request body and function and action return types in response body

      Section 9        Stream Property in the JSON Format spec defines the representation of stream properties of media type JSON. It should be clarified that these rules are also applicable to function and action parameters as well as return types.

       

       

       

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              gerald.krause1 Gerald Krause
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: