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

Describe $compute, $expand, and $select via prose text and examples, remove ABNF snippets

    Details

    • Proposal:
      Hide

      Remove ABNF snippets and make sure that prose text and examples cover all valid alternatives.

      For $compute:

      The value of $compute is a comma-separated list of compute instructions, each consisting of an expression followed by the keyword as, followed by the name for of computed dynamic property. This name MUST differ from the names of declared or other dynamic properties of the identified resources.

      instead of

      Following is a (non-normative) snippet from [OData-ABNF] showing the syntax of $compute:
      compute = '$compute' EQ computeItem *( COMMA computeItem )
      computeItem = commonExpr RWS 'as' RWS computedProperty
      computedProperty = odataIdentifier

       

      For $expand:

      The value of $expand is a comma-separated list of expand items. Each expand item is evaluated relative to the retrieved resource being expanded. An expand item is either a path or one of the symbols * or $value.

      A path consists of segments separated by a forward slash ( / ). Segments are either names of single- or collection-valued complex properties, or type-cast segments consisting of the qualified name of a structured type that is derived from the type identified by the preceding path segment to reach properties defined on the derived type.

      A path can end with

      • the name of a stream property to include that stream property,
      • a star ( * ) to expand all navigation properties of the identified structured instance, optionally followed by /$ref to expand only entity references, or
      • a navigation property to expand the related entity or entities, optionally followed by a type-cast segment to expand only related entities of that derived type or one of its sub-types.

      instead of

      expand            = '$expand' EQ expandItem *( COMMA expandItem )

      expandItem        = STAR [ ref / OPEN levels CLOSE ]
                        / "$value"
                        / expandPath
                          [ ref   [ OPEN expandRefOption   
                                 *( SEMI expandRefOption   ) CLOSE ]
                          / count [ OPEN expandCountOption
                                 *( SEMI expandCountOption ) CLOSE ]
                          /         OPEN expandOption
                                 *( SEMI expandOption      ) CLOSE 
                          ]

      expandPath        = [ ( qualifiedEntityTypeName
                            / qualifiedComplexTypeName 
                            ) "/" ] 
                          *( ( complexProperty / complexColProperty ) "/" 
                             [ qualifiedComplexTypeName "/" ] )
                          ( STAR 
                          / streamProperty
                          / navigationProperty [ "/" qualifiedEntityTypeName ]
                          )

      expandCountOption = filter
                        / search

      expandRefOption   = expandCountOption
                        / orderby
                        / skip 
                        / top 
                        / inlinecount

      expandOption      = expandRefOption
                        / select 
                        / expand
                        / compute
                        / levels
                        / aliasAndValue

      Note: all other optional segments are covered in the existing text, intermingled with examples

      For $select:

      The value of $select is a comma-separated list of select items. Each select item is either a path, a qualified schema name followed by a dot ( . ) and a star ( * ), or just a star ( * ).
      A path consists of segments separated by a forward slash ( / ). Segments are either names of single- or collection-valued complex properties, or type-cast segments consisting of the qualified name of a structured type that is derived from the type identified by the preceding path segment to reach properties defined on the derived type.
      A path can end with

      • the name of a structural property of the identified structured instance,
      • the name of a navigation property to request navigation links,
      • the qualified name of a bound action,
      • the qualified name of a bound function to include all matching overloads, or
      • the qualified name of a bound function followed by parentheses containing the comma-separated lists of non-binding parameters identifying a single overload.

      instead of

      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
      ]

      selectPath = ( complexProperty / complexColProperty )
      [ "/" qualifiedComplexTypeName ]

      selectOptionPC = filter / search / inlinecount / orderby / skip / top

      selectOption = selectOptionPC
      / compute / select / expand / aliasAndValue

      Note: all other optional segments are covered in the existing text, intermingled with examples

      Show
      Remove ABNF snippets and make sure that prose text and examples cover all valid alternatives. For $compute: The value of $compute is a comma-separated list of compute instructions, each consisting of an expression followed by the keyword as, followed by the name for of computed dynamic property. This name MUST differ from the names of declared or other dynamic properties of the identified resources. instead of Following is a (non-normative) snippet from [OData-ABNF] showing the syntax of $compute: compute = '$compute' EQ computeItem *( COMMA computeItem ) computeItem = commonExpr RWS 'as' RWS computedProperty computedProperty = odataIdentifier   For $expand: The value of $expand is a comma-separated list of expand items. Each expand item is evaluated relative to the retrieved resource being expanded. An expand item is either a path or one of the symbols * or $value. A path consists of segments separated by a forward slash ( / ). Segments are either names of single- or collection-valued complex properties, or type-cast segments consisting of the qualified name of a structured type that is derived from the type identified by the preceding path segment to reach properties defined on the derived type. A path can end with the name of a stream property to include that stream property, a star ( * ) to expand all navigation properties of the identified structured instance, optionally followed by /$ref to expand only entity references, or a navigation property to expand the related entity or entities, optionally followed by a type-cast segment to expand only related entities of that derived type or one of its sub-types. instead of expand            = '$expand' EQ expandItem *( COMMA expandItem ) expandItem        = STAR [ ref / OPEN levels CLOSE ]                   / "$value"                   / expandPath                     [ ref   [ OPEN expandRefOption                               *( SEMI expandRefOption   ) CLOSE ]                     / count [ OPEN expandCountOption                            *( SEMI expandCountOption ) CLOSE ]                     /         OPEN expandOption                            *( SEMI expandOption      ) CLOSE                      ] expandPath        = [ ( qualifiedEntityTypeName                       / qualifiedComplexTypeName                        ) "/" ]                      *( ( complexProperty / complexColProperty ) "/"                         [ qualifiedComplexTypeName "/" ] )                     ( STAR                      / streamProperty                     / navigationProperty [ "/" qualifiedEntityTypeName ]                     ) expandCountOption = filter                   / search expandRefOption   = expandCountOption                   / orderby                   / skip                    / top                    / inlinecount expandOption      = expandRefOption                   / select                    / expand                   / compute                   / levels                   / aliasAndValue Note: all other optional segments are covered in the existing text, intermingled with examples For $select: The value of $select is a comma-separated list of select items. Each select item is either a path, a qualified schema name followed by a dot ( . ) and a star ( * ), or just a star ( * ). A path consists of segments separated by a forward slash ( / ). Segments are either names of single- or collection-valued complex properties, or type-cast segments consisting of the qualified name of a structured type that is derived from the type identified by the preceding path segment to reach properties defined on the derived type. A path can end with the name of a structural property of the identified structured instance, the name of a navigation property to request navigation links, the qualified name of a bound action, the qualified name of a bound function to include all matching overloads, or the qualified name of a bound function followed by parentheses containing the comma-separated lists of non-binding parameters identifying a single overload. instead of 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 ] selectPath = ( complexProperty / complexColProperty ) [ "/" qualifiedComplexTypeName ] selectOptionPC = filter / search / inlinecount / orderby / skip / top selectOption = selectOptionPC / compute / select / expand / aliasAndValue Note: all other optional segments are covered in the existing text, intermingled with examples

      Description

      Sections 5.1.2 $expand and 5.1.3 $select currently start with ABNF snippets and then explain allowed constructs via prose text and examples.

      Unfortunately the ABNF is incorrectly restrictive in some places, see ODATA-1155, as well as overly lax on other places.

        Attachments

          Activity

            People

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

              Dates

              • Created:
                Updated:
                Resolved: