Hierarchy.xml

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
    <edmx:Include Alias="Core" Namespace="Org.OData.Core.V1" />
  </edmx:Reference>
  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml">
    <edmx:Include Alias="Aggregation" Namespace="Org.OData.Aggregation.V1" />
  </edmx:Reference>
  <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/Common.xml">
    <edmx:Include Namespace="com.sap.vocabularies.Common.v1" Alias="Common" />
  </edmx:Reference>
  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Validation.V1.xml">
    <edmx:Include Namespace="Org.OData.Validation.V1" Alias="Validation" />
  </edmx:Reference>

  <edmx:DataServices>
    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="com.sap.vocabularies.Hierarchy.v1" Alias="Hierarchy">
      <Annotation Term="Core.Description">
        <String>Terms for Hierarchies</String>
      </Annotation>
      <Annotation Term="Core.Description" Qualifier="Published">
        <String>2018-01-31 © Copyright 2018 SAP SE. All rights reserved</String>
      </Annotation>
      <Annotation Term="Core.Links">
        <Collection>
          <Record>
            <PropertyValue Property="rel" String="latest-version" />
            <PropertyValue Property="href" String="https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy.xml" />
          </Record>
          <Record>
            <PropertyValue Property="rel" String="alternate" />
            <PropertyValue Property="href" String="https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy.json" />
          </Record>
          <Record>
            <PropertyValue Property="rel" String="describedby" />
            <PropertyValue Property="href" String="https://github.com/sap/odata-vocabularies/blob/main/vocabularies/Hierarchy.md" />
          </Record>
        </Collection>
      </Annotation>

      <Term Name="RecursiveHierarchy" Type="Hierarchy.RecursiveHierarchyType" BaseTerm="Aggregation.RecursiveHierarchy" Nullable="false" AppliesTo="EntityType">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Common.IsInstanceAnnotation" />
        <Annotation Term="Core.Description" String="Hierarchy-specific information in the result set of a hierarchical request" />
        <Annotation Term="Core.LongDescription">
          <String>The [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)
          governs what are the nodes and parents in the hierarchy, whereas this term defines derived information.</String>
        </Annotation>
      </Term>
      <ComplexType Name="RecursiveHierarchyType">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.LongDescription">
          <String>The properties in this complex type contain information about
a node in the result set of a hierarchical request. If the same node occurs multiple times
with different parents, certain properties may differ between the occurrences.
The properties are derived when hierarchical transformations
are applied whose first parameter has the annotated entity type
and whose second parameter is the annotation qualifier.

For requests like
```
SalesOrganizations?$apply=
descendants(..., ID, filter(ID eq 'US'), keep start)
/ancestors(..., ID, filter(contains(Name, 'New York')), keep start)
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&amp;$top=10
```
or
```
SalesOrganizations?$apply=groupby((rolluprecursive(..., ID,
  descendants(..., ID, filter(ID eq 'US')),
  ancestors(..., ID, filter(contains(Name, 'New York')), keep start))), aggregate(...))
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&amp;$top=10
```
(where `...,` stands for hierarchy nodes and hierarchy qualifier)
the following collections of hierarchy nodes are distinguished:

|Collection|Definition|Value|Where in request|
|----------|----------|-----|----------------|
|sub-hierarchy|output set of a `descendants` transformation, possibly embedded in a `rolluprecursive` transformation, that is not preceded by an `ancestors` or `descendants` transformation|US sales organizations|rows 1–2|
|matching nodes|see [`MatchCount`](#MatchCount)|US sales organizations with "New York" in their name|output set of `filter` transformation in row 3|
|unlimited hierarchy|output set of the last `ancestors`, `descendants` or `traverse` transformation, possibly embedded in a `rolluprecursive` transformation, disregarding numeric fifth parameters|US sales organizations with leaves containing "New York"|rows 1–3|
|limited hierarchy|output set of the last `ancestors`, `descendants`, `traverse` or [`Hierarchy.TopLevels`](#TopLevels) transformation, possibly embedded in a `rolluprecursive` transformation|2 levels of US sales organizations with leaves containing "New York"|rows 1–4|
</String>
        </Annotation>
        <Property Name="ExternalKey" Type="Edm.String" Nullable="true">
          <Annotation Term="Core.Description" String="Human-readable key value for a node" />
          <Annotation Term="Core.LongDescription">
            <String>If a `NodeType` exists, the external key is unique only in combination with it.
            Or the external key can coincide with the [`Aggregation.RecursiveHierarchy/NodeProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType).</String>
          </Annotation>
        </Property>
        <Property Name="NodeType" Type="Edm.String" Nullable="true">
          <Annotation Term="Core.Description" String="Type of a node" />
          <Annotation Term="Core.LongDescription">
            <String>In a recursive hierarchy with mixed types, nodes can
- have a type-specific (navigation) property whose name is the node type or
- be represented by entities of different subtypes of a common entity type that is

annotated with the `RecursiveHierarchy` annotation. The qualified name of the subtype is the node type.</String>
          </Annotation>
        </Property>
        <Property Name="ChildCount" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of children a node has in the unlimited hierarchy" />
        </Property>
        <Property Name="DescendantCount" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of descendants a node has in the unlimited hierarchy" />
        </Property>
        <Property Name="LimitedDescendantCount" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of descendants a node has in the limited hierarchy" />
        </Property>
        <Property Name="DrillState" Type="Edm.String" Nullable="true">
          <Annotation Term="Core.Description" String="Drill state of an occurrence of a node" />
          <Annotation Term="Core.LongDescription">
            <String>Possible drill states are:
            &lt;br&gt;- `expanded` if a node has children in the limited hierarchy
            &lt;br&gt;- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy
            &lt;br&gt;- `leaf` if a node has no children in the unlimited hierarchy</String>
          </Annotation>
        </Property>
        <Property Name="DistanceFromRoot" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of ancestors an occurrence of a node has in the limited hierarchy" />
          <Annotation Term="Core.LongDescription">
            <String>This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy.</String>
          </Annotation>
        </Property>
        <Property Name="LimitedRank" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Rank of a node in the limited hierarchy in preorder or postorder" />
          <Annotation Term="Core.LongDescription">
            <String>The rank of a node is the index of the node in the sequence of nodes
            created from a preorder or postorder traversal of the limited hierarchy. The first node in the traversal has rank 0.</String>
          </Annotation>
        </Property>
        <Property Name="SiblingRank" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Sibling rank of a node" />
          <Annotation Term="Core.LongDescription">
            <String>The sibling rank of a node is the index of the node in the sequence of all nodes
            in the unlimited hierarchy with the same parent. The first sibling has rank 0.</String>
          </Annotation>
        </Property>
        <Property Name="Matched" Type="Edm.Boolean" Nullable="true">
          <Annotation Term="Core.Description" String="Flag indicating [matching](#MatchCount) nodes" />
        </Property>
        <Property Name="MatchedDescendantCount" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of [matching](#MatchCount) descendants a node has in the unlimited hierarchy" />
        </Property>
        <!--
        <Property Name="Cycle" Type="Edm.Boolean" Nullable="true">
          <Annotation Term="Core.Description" String="There is a cycle from this occurrence of a node to the node itself following the [`Aggregation.UpPath`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#UpPath)" />
        </Property>
        -->
      </ComplexType>

      <Term Name="RecursiveHierarchyActions" Type="Hierarchy.RecursiveHierarchyActionsType" BaseTerm="Aggregation.RecursiveHierarchy" Nullable="false" AppliesTo="EntityType">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Actions for maintaining the recursive hierarchy defined by the [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)" />
        <Annotation Term="Core.LongDescription">
          <String>When an annotation with this term is present, the [`ParentNavigationProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType)
          in the base term must not have a collection-valued segment prior to its last segment.</String>
        </Annotation>
      </Term>
      <ComplexType Name="RecursiveHierarchyActionsType">
        <Annotation Term="Core.LongDescription">
          <String>The qualified action names identify actions for maintaining nodes in the recursive hierarchy,
which are specific for the given annotation qualifier.
These actions MUST have the same signature as the template actions linked below, with
`Edm.EntityType` replaced with the entity type on which the recursive hierarchy is defined.
The resource path of the binding parameter MUST traverse the hierarchy collection,
including any hierarchy directory. If the resource path contains a Content ID reference to an earlier request,
the hierarchy directory MUST be determined from the resource path of that request.
```json
{"requests": [{
  "id": "1",
  "method": "post",
  "url": "HierarchyDirectory(1)/Nodes",
  "body": {
    "Name": "child of A",
    "Superordinate@odata.bind": "Nodes('A')"
  }
}, {
  "id": "2",
  "dependsOn": ["1"],
  "method": "post",
  "url": "$1/Hierarchy.ChangeNextSiblingAction",
  "body": {
    "NextSibling": null
  }
}]}
```
The template actions themselves cannot be invoked.</String>
        </Annotation>
        <Property Name="ChangeNextSiblingAction" Type="Common.QualifiedName" Nullable="true">
          <Annotation Term="Core.Description" String="Action that moves a node among its siblings, following [this template](#Template_ChangeNextSiblingAction)" />
        </Property>
        <!--
        <Property Name="ChangePreviousSiblingAction" Type="Common.QualifiedName" Nullable="true">
          <Annotation Term="Core.Description" String="Action that moves a node among its siblings, following [this template](#Template_ChangePreviousSiblingAction)" />
        </Property>
        -->
        <Property Name="ChangeSiblingForRootsSupported" Type="Edm.Boolean" Nullable="false" DefaultValue="true">
          <Annotation Term="Core.Description" String="Whether the sibling of a root can be changed" />
        </Property>
        <Property Name="CopyAction" Type="Common.QualifiedName" Nullable="true">
          <Annotation Term="Core.Description" String="Action that copies a node and its descendants, following [this template](#Template_CopyAction)" />
        </Property>
      </ComplexType>

      <Term Name="MatchCount" Type="Edm.Int64" Nullable="false" AppliesTo="Collection">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Common.IsInstanceAnnotation" />
        <Annotation Term="Core.Description" String="Instance annotation on the result of an `$apply` query option containing the number of matching nodes after hierarchical transformations" />
        <Annotation Term="Core.LongDescription">
          <String>The service MAY designate a subset of the `$apply` result as "matching nodes".
For requests following the pattern described [here](#RecursiveHierarchyType), this subset is the output set of the
`filter` or `search` transformation that occurs as the fourth parameter
of the last `ancestors` transformation or occurs nested into it.

For requests not following this pattern, the subset NEED NOT be defined.

This instance annotation is available if [`RecursiveHierarchy/Matched`](#RecursiveHierarchyType)
and [`RecursiveHierarchy/MatchedDescendantCount`](#RecursiveHierarchyType) are also available.</String>
        </Annotation>
      </Term>

      <!--
      <Term Name="StartNodeCounts" Type="Collection(Edm.Int64)" AppliesTo="Collection">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Common.IsInstanceAnnotation" />
        <Annotation Term="Core.Description" String="Instance annotation on the result of an `$apply` query option containing the number of start nodes for each `ancestors` or `descendants` transformation" />
        <Annotation Term="Core.LongDescription">
          <String>The annotation value is an integer collection whose n-th entry is the number of start nodes determined
          for the n-th `ancestors` or `descendants` transformation in the order in which they occur in the `$apply` query option.
          Start nodes are determined by the fourth parameter of an `ancestors` or `descendants` transformation.</String>
        </Annotation>
      </Term>
      -->

      <Function Name="TopLevels" IsBound="true" EntitySetPath="InputSet">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Returns the first n levels of a hierarchical collection in preorder with individual nodes expanded or collapsed" />
        <Annotation Term="Core.LongDescription">
          <String>This function can be used as a transformation whose input set has a recursive hierarchy
          defined by an [`Aggregation.RecursiveHierarchy`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)
          annotation on the entity type of the `HierarchyNodes`.
          (Its binding parameter is the unlimited hierarchy as defined [here](#RecursiveHierarchyType),
          its output is the limited hierarchy.) The output initially contains the nodes with less than n ancestors
          in the hierarchical collection given in the binding parameter.
          Then individual nodes are expanded, shown or collapsed in the output, which extends or reduces the limited hierarchy.
          Finally the output is sorted in preorder as with the `traverse` transformation with the hierarchy-specific
          definition of start nodes.</String>
        </Annotation>
        <Parameter Name="InputSet" Type="Collection(Edm.EntityType)" Nullable="false"/>
        <Parameter Name="HierarchyNodes" Type="Collection(Edm.EntityType)" Nullable="false">
          <Annotation Term="Core.Description" String="A collection, given through a `$root` expression" />
        </Parameter>
        <Parameter Name="HierarchyQualifier" Type="Aggregation.HierarchyQualifier" Nullable="false" />
        <Parameter Name="NodeProperty" Type="Edm.String" Nullable="false">
          <Annotation Term="Core.Description" String="Property path to the node identifier, evaluated relative to the binding parameter" />
        </Parameter>
        <Parameter Name="Levels" Type="Edm.Int64" Nullable="false">
          <Annotation Term="Core.Description" String="The number n of levels to be output, absent means all levels" />
          <Annotation Term="Core.OptionalParameter">
            <Record/>
          </Annotation>
          <Annotation Term="Validation.Minimum" Int="1" />
        </Parameter>
        <Parameter Name="Show" Type="Collection(Edm.String)" Nullable="false">
          <Annotation Term="Core.Description" String="Identifiers of nodes to be shown" />
          <Annotation Term="Core.OptionalParameter">
            <Record/>
          </Annotation>
        </Parameter>
        <Parameter Name="ExpandLevels" Type="Collection(Hierarchy.TopLevelsExpandType)" Nullable="false">
          <Annotation Term="Core.Description" String="Nodes to be expanded" />
          <Annotation Term="Core.OptionalParameter">
            <Record/>
          </Annotation>
        </Parameter>
        <ReturnType Type="Collection(Edm.EntityType)" />
      </Function>
      <ComplexType Name="TopLevelsExpandType">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Information about nodes to be expanded" />
        <Property Name="NodeID" Type="Edm.String" Nullable="false">
          <Annotation Term="Core.Description" String="Identifier of a node to be expanded" />
        </Property>
        <Property Name="Levels" Type="Edm.Int64" Nullable="true">
          <Annotation Term="Core.Description" String="Number of levels to be expanded, null means all levels, 0 means collapsed" />
        </Property>
      </ComplexType>

      <Term Name="RecursiveHierarchySupported" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="Collection">
        <Annotation Term="Core.AppliesViaContainer" />
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Whether the annotated collection acts as a [`RecursiveHierarchy`](#RecursiveHierarchy) with the given qualifier" />
        <Annotation Term="Core.LongDescription">
          <String>This tag is applied to a collection with the same qualifier as the [`RecursiveHierarchy`](#RecursiveHierarchy) term which is applied to its entity type.
          The recursive hierarchy can then only be addressed through a collection where this tag is true.</String>
        </Annotation>
      </Term>

      <Action Name="Template_ChangeNextSiblingAction" IsBound="true">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Template for actions that move a node among its siblings and are named in [`RecursiveHierarchyActions/ChangeNextSiblingAction`](#RecursiveHierarchyActionsType)" />
        <Parameter Name="Node" Type="Edm.EntityType" Nullable="false">
          <Annotation Term="Core.Description" String="The node T to be moved" />
        </Parameter>
        <Parameter Name="NextSibling" Type="Edm.ComplexType" Nullable="true">
          <Annotation Term="Core.Description" String="Key of the node's new next sibling S (null if the node shall become the last sibling)" />
          <Annotation Term="Core.LongDescription">
            <String>This parameter has properties with the same names as the key properties of the entity type.
            next(T) = S after the action.
            If R is a node with next(R) = S before the action, then next(R) = T after the action, even if S = null.
            It is an error if S has a different parent than T.</String>
          </Annotation>
        </Parameter>
      </Action>
      <!--
      <Action Name="Template_ChangePreviousSiblingAction" IsBound="true">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Template for actions that move a node among its siblings and are named in [`RecursiveHierarchyActions/ChangePreviousSiblingAction`](#RecursiveHierarchyActionsType)" />
        <Parameter Name="Node" Type="Edm.EntityType" Nullable="false">
          <Annotation Term="Core.Description" String="The node T to be moved" />
        </Parameter>
        <Parameter Name="PreviousSibling" Type="Edm.ComplexType" Nullable="true">
          <Annotation Term="Core.Description" String="Key of the node's new previous sibling S (null if the node shall become the first sibling)" />
          <Annotation Term="Core.LongDescription">
            <String>This parameter has properties with the same names as the key properties of the entity type.
            prev(T) = S after the action.
            If R is a node with prev(R) = S before the action, then prev(R) = T after the action, even if S = null.
            It is an error if S has a different parent than T.</String>
          </Annotation>
        </Parameter>
      </Action>
      -->
      <Action Name="Template_CopyAction" IsBound="true" EntitySetPath="Node">
        <Annotation Term="Common.Experimental" />
        <Annotation Term="Core.Description" String="Template for actions that copy a node and its descendants and are named in [`RecursiveHierarchyActions/CopyAction`](#RecursiveHierarchyActionsType)" />
        <Annotation Term="Core.LongDescription">
          <String>To give the copied sub-hierarchy a parent, the action invocation can be followed
by a PATCH that binds the parent navigation property (for example, `Superordinate` in the following JSON batch request).
```json
{"requests": [{
  "id": "1",
  "method": "post",
  "url": "HierarchyDirectory(1)/Nodes('A')/CopyAction"
}, {
  "id": "2",
  "dependsOn": ["1"],
  "method": "patch",
  "url": "$1",
  "body": {
    "Superordinate@odata.bind": "Nodes('B')"
  }
}]}
```</String>
        </Annotation>
        <Parameter Name="Node" Type="Edm.EntityType" Nullable="false">
          <Annotation Term="Core.Description" String="The node to be copied" />
        </Parameter>
        <ReturnType Type="Edm.EntityType" Nullable="false">
          <Annotation Term="Core.Description" String="The copied node" />
        </ReturnType>
      </Action>

    </Schema>
  </edmx:DataServices>
</edmx:Edmx>