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 transformations for recursive hierarchy processing originally introduced with ODATA-1218:

      Proposal to extend definitions of transformations ancestors and descendants to receive a recursive hierarchy via parameters that may differ from the input set.

      Proposal to rewrite section about hierarchical functions:

      6.5.2.1 Hierarchy Functions

      For testing the position of a given entity in a recursive hierarchy, the Aggregation vocabulary defines functions. These have

      • a parameter pair HierarchyNodes, HierarchyQualifier where HierarchyNodes is a collection and HierarchyQualifier is the qualifier of a RecursiveHierarchy annotation on its entity type. The node values in this collection define the recursive hierarchy
      • a parameter Node that contains the node value of entity to be tested. Note that the test result depends only on this node value, not on any other property of the given entity
      • additional parameters, depending on the type of test (see below)
      • a boolean return value for the outcome of the test.

      The following functions are defined:

      • isroot tests if the given entity is a root of the hierarchy,
      • isdescendant tests if the given entity is a descendant of an ancestor node (whose node value is given in a parameter Ancestor) with a maximum distance MaxDistance, or equals the ancestor if IncludeSelf is true,
      • isancestor tests if the given entity is an ancestor of a descendant node (whose node value is given in a parameter Descendant) with a maximum distance MaxDistance, or equals the descendant if IncludeSelf is true,
      • issibling tests if the given entity and another entity (whose node value is given in parameter Other) have the same parent node or both are roots, but are not the same,
      • isleaf tests if the given entity is without descendants.
      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 transformations for recursive hierarchy processing originally introduced with ODATA-1218 : Proposal to extend definitions of transformations ancestors and descendants to receive a recursive hierarchy via parameters that may differ from the input set. Proposal to rewrite section about hierarchical functions: 6.5.2.1 Hierarchy Functions For testing the position of a given entity in a recursive hierarchy, the Aggregation vocabulary defines functions. These have a parameter pair HierarchyNodes , HierarchyQualifier where HierarchyNodes is a collection and HierarchyQualifier is the qualifier of a RecursiveHierarchy annotation on its entity type. The node values in this collection define the recursive hierarchy a parameter Node that contains the node value of entity to be tested. Note that the test result depends only on this node value, not on any other property of the given entity additional parameters, depending on the type of test (see below) a boolean return value for the outcome of the test. The following functions are defined: isroot tests if the given entity is a root of the hierarchy, isdescendant tests if the given entity is a descendant of an ancestor node (whose node value is given in a parameter Ancestor ) with a maximum distance MaxDistance , or equals the ancestor if IncludeSelf is true, isancestor tests if the given entity is an ancestor of a descendant node (whose node value is given in a parameter Descendant ) with a maximum distance MaxDistance , or equals the descendant if IncludeSelf is true, issibling tests if the given entity and another entity (whose node value is given in parameter Other ) have the same parent node or both are roots, but are not the same, isleaf tests if the given entity is without descendants.
    • Resolution:
      Show
      https://github.com/oasis-tcs/odata-vocabularies/pull/125 https://www.oasis-open.org/apps/org/workgroup/odata/download.php/69664/odata-data-aggregation-ext-v4.0-wd05.docx https://github.com/oasis-tcs/odata-abnf/pull/72  is merged.

      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: