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

Clarifications for select-list in ContextUrl

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: V4.01_CS02
    • Component/s: Protocol
    • Labels:
    • Environment:

      Applied

    • Proposal:
      Hide

      Make sure the following are clear in the documentation:
      1) If the contextUrl includes only expanded navigation properties (i.e., only navigation properties suffixed with parens), then all structural properties are implicitly selected (same as if there were no properties listed in the select-list)
      2) In section 10.8, Projected Entity, change:
      "Note that expanded properties are implicitly selected." to "Note that expanded properties are automatically included in the response."
      3) Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the contextUrl using path syntax, as defined in 4.0. Similarly, expands nested within $select are represented the same as expands outside of $select.
      4) Operations in the ContextUrl should always be represented using the full namespace- or alias- qualified name, so if it has a dot it is an operation. Functions suffixed with parens represent a specific overload, while functions without parens represent all overloads of the function.
      5) Navigation properties with expanded references are not represented in the ContextUrl. i.e., the contextUrl for Customers?$expand=Orders/$ref would just be $metadata#Customers.

      Show
      Make sure the following are clear in the documentation: 1) If the contextUrl includes only expanded navigation properties (i.e., only navigation properties suffixed with parens), then all structural properties are implicitly selected (same as if there were no properties listed in the select-list) 2) In section 10.8, Projected Entity, change: "Note that expanded properties are implicitly selected." to "Note that expanded properties are automatically included in the response." 3) Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the contextUrl using path syntax, as defined in 4.0. Similarly, expands nested within $select are represented the same as expands outside of $select. 4) Operations in the ContextUrl should always be represented using the full namespace- or alias- qualified name, so if it has a dot it is an operation. Functions suffixed with parens represent a specific overload, while functions without parens represent all overloads of the function. 5) Navigation properties with expanded references are not represented in the ContextUrl. i.e., the contextUrl for Customers?$expand=Orders/$ref would just be $metadata#Customers.
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/64681/odata-v4.01-wd06-part1-protocol-2019-02-08.docx

      Description

      The use of select-list is defined in prose in the Protocol document:

      10.8 Projected Entity

      Context URL templates:

        {context-url}#{entity-set}{/type-name}{select-list}/$entity
        {context-url}#{singleton}{select-list}
        {context-url}#{type-name}{select-list}
      

      If a single entity contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, navigation properties, functions, and actions is appended to the entity-set after an optional type-cast segment and prior to appending /$entity. If the response is not bound to a single entity set, the select-list is instead appended to the

      Unknown macro: {type-name}

      of the returned entity.
      The shortcut * represents the list of all structural properties. Properties defined on types derived from the type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in [OData-ABNF]. Note that expanded properties are implicitly selected.
      OData 4.01 responses MAY use the shortcut pattern namespace.* to represent the list of all bound actions or functions available for entities in the collection, see system query option $select.

      We go on to say:

      10.9 Collection of Expanded Entities

      Context URL template:

        {context-url}#{entity-set}{/type-name}{select-list}
        {context-url}#Collection({type-name}){select-list}
      

      For a 4.01 response, if a navigation property is explicitly expanded, then in addition to any non-suffixed names of any selected properties, navigation properties, functions or actions, the comma-separated list of properties MUST include the name of the expanded property, suffixed with the parenthesized comma-separated list of any properties of the expanded navigation property that are selected or expanded. If the expanded navigation property does not contain a nested $select or $expand, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign is infixed between the navigation property name and the opening parenthesis.
      For a 4.0 response, the expanded navigation property suffixed with parentheses MAY be omitted from the select-list if it does not contain a nested $select or $expand, but MUST still be present, without a suffix, if it is explicitly selected.

      Questions:

      1) We should clarify that, if the contextUrl includes only expanded navigation properties (i.e., only navigation properties suffixed with parens), then implicitly the default set of properties is selected. This is never spelled out, but is implied by our example 22:

      Example 22: resource URL and corresponding context URL

      http://host/service/Employees(1)/Sales.Manager?
      $expand=DirectReports($select=FirstName,LastName;$levels=4)
      http://host/service/$metadata
      #Employees/Sales.Manager(DirectReports+(FirstName,LastName))/$entity

      Note that, in this example, there is no $select applied to the top level entity (Employees(1)) implying that the default set of properties should be returned for the sales manager, which appears to be implied by the contextUrl only including the expanded properties.

      2) What do we mean by "Note that expanded properties are implicitly selected."? Does this mean that expanded properties are implicitly in the response, or does it mean that expanded properties also have their navigation link included? In 4.01 we say that, in the contextUrl, the expanded navigation property must appear with open/close parens in addition to any selected or expanded navigation properties. i.e., if it both selected and expanded, then it appears twice; once with, and once without, the parens. If we read the first statement as "also have their navigation link included" then it seems unnecessary to represent the expanded navigation property in the contextUrl without the parens.

      3) Now that we have introduced select options, how do we represent select options within the contextUrl. We already have a syntax for nested select, using path syntax:

      select         = ( "$select" / "select" ) EQ selectItem *( COMMA selectItem )
      selectItem     = STAR
                     / allOperationsInSchema 
                     / [ ( qualifiedEntityTypeName / qualifiedComplexTypeName ) "/" ] 
                       ( selectProperty
                       / qualifiedActionName  
                       / qualifiedFunctionName  
                       )
      selectProperty = primitiveProperty  
                     / primitiveColProperty [ OPEN selectOptionPC *( SEMI selectOptionPC ) CLOSE ]
                     / navigationProperty
                     / selectPath [ OPEN selectOption *( SEMI selectOption ) CLOSE
                                  / "/" selectProperty 
                                  ]
      

      This is somewhat more verbose, but it would be breaking (and somewhat ambiguous between dynamic properties with select options and expanded dynamic nav props) to change it to use the parens syntax. But, what about nested expands within $select?

      4) We say that explicitly selected functions are also represented in the contextUrl. Should these be represented with, or without, parens?

      Looking again at our ABNF, we see that qualifiedFunctionName is defined generally as:

      qualifiedFunctionName = namespace "." function [ OPEN parameterNames CLOSE ]
      

      which implies that you could include or omit the parens (we should pick one).
      If we don't include the parens, then we can't differentiate between overloads.
      If we do include the parens, then how can we differentiate between dynamic functions and dynamic expanded navigation properties?

      5) We say that the contextUrl for a collection of references (i.e., Customers/$ref) is #Collection($ref), and the contextUrl for a single reference (i.e., Orders(1)/Customer/$ref) is #$ref, but we don't say how an expanded reference (i.e., Customers?$expand=Orders/$ref) is represented in the contextUrl. Note that defining new syntax for this (for example, Customers(Orders/$ref)) would be a breaking change. Also, it's not really necessary to know about the $ref in order to interpret the results, understand metadata, or materialize missing information in a JSON minimal metadata format. So there may be no need to represent it at all.

        Attachments

          Activity

            People

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

              Dates

              • Created:
                Updated:
                Resolved: