[OASIS Issue Tracker] (ODATA-1238) Clarifications for select-list in ContextUrl

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

Michael Pizzo created ODATA-1238:
------------------------------------

             Summary: Clarifications for select-list in ContextUrl
                 Key: ODATA-1238
                 URL: https://issues.oasis-open.org/browse/ODATA-1238
             Project: OASIS Open Data Protocol (OData) TC
          Issue Type: Bug
            Reporter: Michael Pizzo


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

{panel}
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 {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.
{panel}

We go on to say:

{panel}
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. 
{panel}

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:

{panel}
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
{panel}

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:

{code:abnf}
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 
                            ]
{code}

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:

{code}
qualifiedFunctionName = namespace "." function [ OPEN parameterNames CLOSE ]
{code}

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?



--
This message was sent by Atlassian JIRA
(v7.7.2#77003)