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

Consider supporting optional operation parameters

    XMLWordPrintable

    Details

    • Proposal:
      Hide

      1) Add a new OptionalParameter annotation:
      <Term Name="OptionalParameter" Type="Core.OptionalParameterType" AppliesTo="Parameter">
      <Annotation Term="Core.Description" String="Supplying a value for the parameter is optional." />
      </Term>

      <ComplexType Name="OptionalParameterType">
      <Property Name="IsOptional" Type="Edm.Boolean" DefaultValue = "true"/>
      <Property Name="DefaultValue" Type="Edm.String">
      <Annotation Term="Core.Description" String="Default value for an optional parameter, using the same rules for the default value facet of a property." />
      </Property>
      </ComplexType>

      2) All parameters marked optional must come after any parameters not marked optional

      3) Keep existing rules for function overloads.

      4) In function resolution:
      I) If the set of specified params exactly matches a function overload, chose it.
      ii) If the set of specified params matches a subset of parameters that includes all required parameters for exactly one function overload, choose it

      5) Services should avoid ambiguity. If there is ambiguity then services may return 400 with an error stating that request was ambiguous

      Show
      1) Add a new OptionalParameter annotation: <Term Name="OptionalParameter" Type="Core.OptionalParameterType" AppliesTo="Parameter"> <Annotation Term="Core.Description" String="Supplying a value for the parameter is optional." /> </Term> <ComplexType Name="OptionalParameterType"> <Property Name="IsOptional" Type="Edm.Boolean" DefaultValue = "true"/> <Property Name="DefaultValue" Type="Edm.String"> <Annotation Term="Core.Description" String="Default value for an optional parameter, using the same rules for the default value facet of a property." /> </Property> </ComplexType> 2) All parameters marked optional must come after any parameters not marked optional 3) Keep existing rules for function overloads. 4) In function resolution: I) If the set of specified params exactly matches a function overload, chose it. ii) If the set of specified params matches a subset of parameters that includes all required parameters for exactly one function overload, choose it 5) Services should avoid ambiguity. If there is ambiguity then services may return 400 with an error stating that request was ambiguous
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/61017/odata-v4.01-wd02-part1-protocol-2017-06-20.docx https://github.com/oasis-tcs/odata-vocabularies/commit/92b84be8c5f53c872bfed08d53629c3f202f06ea

      Description

      We have frequently had requests to support optional parameters, but have pushed back because they could introduce ambiguity in function resolution.

      However, with our current rules:
      1) The unordered set of nonbinding parameter names must be unique, and
      2) The ordered list of nonbinding parameter types must be unique

      We could support making some parameters optional as a backward compatible change with the following resolution rules:
      1) If the set of provided parameters exactly matches all parameters of an overload, then that overload is chosen
      2) If the set of provided parameters matches all required and a subset of optional parameters of exactly one overload, then that overload is chosen

      otherwise a 400 error

      Questions:
      1) Should we provide a set of rules so there is never any ambiguity (i.e., there does not exist a set of parameters for which one of the two rules above is not met) or specify that the service returns 400 if the request does not resolve to a single overload?
      2) Should we define a default value for optional parameters? This would really just be documentation (the service wouldn't need you to tell it what the default value was in metadata). It could be useful in generating strongly typed function calls in languages with optional parameters (C++, C#,...) but there may not be a static default value that can be specified (i.e., current time, a computed value, etc.)

        Attachments

        There are no Sub-Tasks for this issue.

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              mikep Michael Pizzo
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: