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

Clarify usage of annotation qualifiers as references to hierarchies

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_CS02
    • Fix Version/s: V4.0_CSD04
    • Component/s: Data Aggregation
    • Labels:
      None
    • Environment:

      Applied

    • Proposal:
      Hide

      Regarding hierarchy predicate functions:

      The node set on which these functions operate should be explicitly specified with an additional argument addressing the entity set containing the hierarchy nodes. This will then also cover the interesting use case to use the functions for related hierarchies. For example,

      GET ~/Sales?
       $filter=$it/SalesOrganization/Aggregation.isdescendant(
            Nodes='SalesOrganizations',Hierarchy='SalesOrgHierarchy',Node='EMEA')
      

      returns those sales entities whose sales organization is a descendant of EMEA.

      Necessary changes:

      1. Extend functions in the Aggregation vocabulary: Add Nodes as new first parameter to isroot, isdescendant, isancestor, issibling, isleaf.
        • The Nodes parameter takes the name of an entity set exposed by the service.
        • The Hierarchy parameter receives the qualifier of a RecursiveHierarchy annotation attached to the entity type of the set whose name is specified in Nodes.
      2. Adjust examples 42-46 to reflect point 1.
      3. Add the example above to illustrate application of a predicate function on a related hierarchy.

      Regarding new transformations for recursive hierarchy processing in the proposal for ODATA-1218:

      The proposal clarifies that the entities in the input set passed to these transformations must be of a type that has been annotated with RecursiveHierarchy and the qualifier passed to the transformation. This effectively means that these entities are always part of the resource collection addressed by the request like in this example from the proposal in section 3.2:

      GET ~/SalesOrganizations?$apply=
          descendants(SalesOrgHierarchy,filter(Name eq 'US'),keep start)
      

      No changes required.

      Show
      Regarding hierarchy predicate functions: The node set on which these functions operate should be explicitly specified with an additional argument addressing the entity set containing the hierarchy nodes. This will then also cover the interesting use case to use the functions for related hierarchies. For example, GET ~/Sales? $filter=$it/SalesOrganization/Aggregation.isdescendant(      Nodes= 'SalesOrganizations' ,Hierarchy= 'SalesOrgHierarchy' ,Node= 'EMEA' ) returns those sales entities whose sales organization is a descendant of EMEA. Necessary changes: Extend functions in the Aggregation vocabulary: Add Nodes as new first parameter to isroot , isdescendant , isancestor , issibling , isleaf . The Nodes parameter takes the name of an entity set exposed by the service. The Hierarchy parameter receives the qualifier of a RecursiveHierarchy annotation attached to the entity type of the set whose name is specified in Nodes . Adjust examples 42-46 to reflect point 1. Add the example above to illustrate application of a predicate function on a related hierarchy. Regarding new transformations for recursive hierarchy processing in the proposal for ODATA-1218 : The proposal clarifies that the entities in the input set passed to these transformations must be of a type that has been annotated with RecursiveHierarchy and the qualifier passed to the transformation. This effectively means that these entities are always part of the resource collection addressed by the request like in this example from the proposal in section 3.2: GET ~/SalesOrganizations?$apply=     descendants(SalesOrgHierarchy,filter(Name eq 'US' ),keep start) No changes required.
    • Resolution:
      Show
      https://github.com/oasis-tcs/odata-vocabularies/pull/125

      Description

      Section 6.3.2 Recursive Hierarchy specifies that "The value of the Qualifier attribute can be used to reference the hierarchy in Hierarchy Filter Functions."

      Hierarchy filter functions make use of this concept, they accept a qualifier as first parameter.

      All examples in the document apply this approach with top-level entities, i.e. part of the collection addressed by the resource path. E.g.:
      GET ~/SalesOrganizations?$filter=$it/Aggregation.isdescendant(}}
      {{      Hierarchy='SalesOrgHierarchy',Node='EMEA')}}

      Using this approach also for hierarchies on entity collections related to the top-level entities would require identifying the node set on which the function operates, which is not possible (example: GET ~/Sales?
      $filter=$it/SalesOrganization/Aggregation.isdescendant(
           Hierarchy='SalesOrganization/SalesOrgHierarchy',Node='EMEA') leaves the set of sales orgs to consider as hierarchy unspecified )

      Therefore it needs to be clarified if/that these functions with the references to hierarchies always operate on top-level entities given by the resource path.

      This issue is also relevant for ODATA-1218, which introduces transformations for hierarchy processing that also expect such a qualifier as call argument.

       

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                gerald.krause1 Gerald Krause
              • Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: