Inclusion of Hierarchical Metadata within CoreMetaData

This relates to the Object Hierarchy Items, which is being proposed as an addition to Core Meta Data.

Overview

This is a proposal to enhance the structure and usability of JSON-LD schema in REST API responses through the inclusion of hierarchical metadata. This metadata provides essential information about the hierarchical relationships between records. By organizing this information under a new property named hierarchyItems within coreMetaData, a clean and clear structure in API responses can be maintained. This approach helps isolate hierarchical data from other properties, making it easier to manage and understand.

Assumptions

There is a need to include hierarchical data in all individual record API responses.
A record can belong to multiple hierarchies.

The Story…

The story behind hierarchical items is simple. JSON-LD doesn’t distinguish between unordered and ordered lists (see arrays in the style guide). Therefore, any sort values, as well as references to parents and children, need to be added.

Both parents and children need to be an array - just like in real life. Any listing of a record should be able to point to multiple parents as well as multiple children. And it should be assumed, then, that the children listed belong to that parental genealogy just as in real life.

Hierarchical Metadata Properties

The hierarchical metadata includes the following properties:

@id: The URL for the API endpoint to find a detailed response for the hierarchical item record this object belongs to.
@type: Specifies the type of the object, in this case, "HierarchyItem".
elementId: A unique and persistent identifier for the hierarchical item record this object belongs to.
parents: A navigable object consisting of @id, and elementId of the associated parent within an array for this record. This value will be null for a top-level record.
sortValue: An integer used to sort the record relative to its siblings at each sibling level. If not applicable, this can be null.
genealogy: An ordered array of elementIds that provides the record’s hierarchical lineage or path, useful for tracing its origins.
children: A collection of child navigable objects consisting of @id, and elementId. This will be an empty array for a record without children.

Benefits of Storing Hierarchical Metadata in the `hierarchicalItems` Property

Storing hierarchical metadata within a dedicated hierarchicalItems property offers several advantages:

Clarity: It keeps the hierarchical information separate from other record attributes, reducing clutter and making the structure more comprehensible.
Modularity: This separation allows for easier modifications and expansions of hierarchical data without affecting other parts of the record.
Consistency: It ensures consistent handling and access of hierarchical data across different records and API responses.

Detailed Reasoning Behind Proposed Properties

@id, @type, elementId:
- Consistency: These are properties included on all entities
parents:
- Interoperability: Using a JSON-LD object allows integration with linked data standards, facilitating easier data sharing and connectivity.
- Clarity: The @id property provides a clear reference to the API endpoint of the parent, while elementId maintains the numeric ID for internal use. This dual representation makes it straightforward for clients to follow and interact with the hierarchical structure.
sortValue:
- Sortability: Without this property, there would be no way to custom sort the children underneath a parent
children:
- Consistency: Similar to the parent property, using JSON-LD objects for children ensures consistency in how hierarchical relationships are represented.
- Ease of Access: The @id properties provide direct links to the API endpoints of child elements, making it easier for clients to access and manipulate these records.
- Scalability: This structure can easily accommodate additional metadata about child elements if needed in the future, without breaking existing implementations.
genealogy:
- Precision: An ordered array of ID values provides a precise and unambiguous representation of the hierarchical path.
- Simplicity: This format is easier to parse programmatically compared to a string representation, reducing potential errors and improving data processing efficiency.
- Flexibility: The array format allows for easy updates and modifications to the hierarchy, ensuring the genealogy can be dynamically adjusted as the data evolves.

Example JSON Response

{
    "@context": "https://grcschema.org",
    "@type": "Person",
    "elementId": 87,
    "name": "Jane Doe",
    ...,
    "coreMetaData": {
      ...,  
      "hierarchicalItems": [
        {
          "@id": "https://api.app.unifiedcompliance.com/api/hierarchy/5/item/123",
          "@type": "HierarchyItem",
          "elementId": 123,
          "hierarchicalParents": 
          [
              hierarchicalParent" : {
              "@id": "https://api.app.unifiedcompliance.com/api/person/45",
              "@type": "Person",
              "elementId": 45
              },
          ],
          
          "sortValue": 1,
          "hierarchicalChildren": [
              "hierarchicalChild" : {
                  "@id": "https://api.app.unifiedcompliance.com/api/person/124",
                  "@type": "Person",
                  "elementId": 124
              },
              "hierarchicalChild" : {
                  "@id": "https://api.app.unifiedcompliance.com/api/person/125",
                  "@type": "Person",
                  "elementId": 125
              },
              "hierarchicalChild" : {
                  "@id": "https://api.app.unifiedcompliance.com/api/person/126",
                  "@type": "Person",
                  "elementId": 126
              }
          ]
        }
      ]
    }
}