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

Allow using instance annotations in $select and $expand

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_CS01
    • Fix Version/s: V4.01_CS02
    • Component/s: ABNF, Protocol, URL Conventions
    • Labels:
      None
    • Environment:

      Applied

    • Proposal:
      Hide

      Allow using instance annotations of type (collection of) primitive or complex in $select and instance annotations of type (collection of) entity in $expand.

      Example

      GET Stuff?$select=@Core.Messages($top=5)
      

      Services can signal this capability to clients with the tagging term Capabilities.AnnotationValuesInQuerySupported.

      <Term Name="AnnotationValuesInQuerySupported" Type="Core.Tag" DefaultValue="True"
            Nullable="false" AppliesTo="EntityContainer">
          <Annotation Term="Core.Description" 
                      String="Supports annotation values within system query options" />
      </Term>
      

      Annotations in $select must be included in response and take precedence over preference header; if $select says to include, and preference says omit, it's still included. preference header can add additional annotations to what is specified in $select.

      In the presence of both include-annotations preference and annotations selected in $select, then preference-applied, if present, reflects the set of annotations added by the preference-applied (not by $select). In the absence of the include-annotations preference header, there should not be an include-annotations in the preference applied.

      Explicitly selected (expanded) annotations must appear in the contextUrl as other properties. It is possible to select only annotations, in which case only those selected (expanded) navigations appear in the result. Note that annotations specified in include-annotations do not appear in the context Url, and do not affect the selected/expanded properties.

      It is not valid to $select an entity-valued annotation (because we do not currently define a canonical navigation url for an entity-valued annotation). entity-valued annotations can be included using $expand.

      If the annotation isn't applied to the instance, a null value is returned (same as for dynamic properties).

      Note that selecting control information (@odata.type, @odata.navigationLink, etc.) is not allowed.

      Show
      Allow using instance annotations of type (collection of) primitive or complex in $select and instance annotations of type (collection of) entity in $expand. Example GET Stuff?$select=@Core.Messages($top=5) Services can signal this capability to clients with the tagging term Capabilities.AnnotationValuesInQuerySupported . <Term Name= "AnnotationValuesInQuerySupported" Type= "Core.Tag" DefaultValue= "True" Nullable= "false" AppliesTo= "EntityContainer" > <Annotation Term= "Core.Description" String= "Supports annotation values within system query options" /> </Term> Annotations in $select must be included in response and take precedence over preference header; if $select says to include, and preference says omit, it's still included. preference header can add additional annotations to what is specified in $select. In the presence of both include-annotations preference and annotations selected in $select, then preference-applied, if present, reflects the set of annotations added by the preference-applied (not by $select). In the absence of the include-annotations preference header, there should not be an include-annotations in the preference applied. Explicitly selected (expanded) annotations must appear in the contextUrl as other properties. It is possible to select only annotations, in which case only those selected (expanded) navigations appear in the result. Note that annotations specified in include-annotations do not appear in the context Url, and do not affect the selected/expanded properties. It is not valid to $select an entity-valued annotation (because we do not currently define a canonical navigation url for an entity-valued annotation). entity-valued annotations can be included using $expand. If the annotation isn't applied to the instance, a null value is returned (same as for dynamic properties). Note that selecting control information (@odata.type, @odata.navigationLink, etc.) is not allowed.
    • Resolution:
      Show
      Approved 2019/11/29: https://github.com/oasis-tcs/odata-abnf/pull/7 Approved 2018/10/25: https://github.com/oasis-tcs/odata-vocabularies/pull/24 Approved 2018/10/25: https://www.oasis-open.org/committees/download.php/64118/odata-v4.01-wd06-part2-url-conventions-2018-10-19.docx Approved 2018/10/25: https://www.oasis-open.org/committees/download.php/64119/odata-v4.01-wd06-part1-protocol-2018-10-19.docx new:  https://github.com/oasis-tcs/odata-abnf/pull/15    

      Description

      We already allow using instance annotations in $filter, $orderby, and $compute:

      GET Stuff?$filter=@Core.Messages/any(m:m/severity eq 'error')
      

      This indirectly allows using instance annotations in $select and $expand:

      GET Stuff?$compute=@Core.Messages as _at_Core_dot_Messages
               &$select=*,_at_Core_dot_Messages($top=5)
      

      Which is kind of ugly and loses the canonical name of the instance annotation

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              handl Ralf Handl
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: