Introduction to Standard Elements for Things

As part of the comprehensive GRCSchema.org initiative, this document outlines the "Standard Elements for Things", a core set of JSON-LD elements that are fundamental to enhancing the interoperability and usability of data across various systems. These elements, which include @context, version, and CoreMetaData, are integral to ensuring that the structured data is not only accurately interpreted by machines, such as search engines and other applications, but also maintained with a high level of integrity and traceability. This document serves as a guide for developers and organizations to implement these standard elements effectively, ensuring that data remains robust, consistent, and reliable across different platforms and applications. By adhering to these standards, organizations can facilitate better data management practices and prepare their systems for future technological advancements and regulatory requirements.

@Context

In the GRCSchema.org context, the "@context" is a key component used in JSON-LD (JavaScript Object Notation for Linked Data) to define the vocabulary for the terms used in the data structure. This is important because it allows the structured data to be correctly interpreted by machines, such as search engines and other applications.

The "@context" provides the base URI (Uniform Resource Identifier) that will be used to expand the properties and types in the JSON-LD document. For example, if you use GRCSchema.org vocabulary, the "@context" would typically be set to "https://grcschema.org". This tells the application processing the JSON-LD that the terms used should be interpreted according to the definitions found at GRCSchema.org.

Here’s a simple example of how "@context" is used in JSON-LD:

{
  "@context": "https://grcschema.org",
  "@type": "Person",
  "name": "Jane Doe",
  "postalAddress": "1234 Tuff Street",
  "CountryCode": "USA"
}

In this example, "@context" ensures that properties like "name", “postalAddress, and “CountryCode” are understood to be defined by GRCSchema.org, ensuring that the data can be properly read and utilized by machines that are familiar with the Schema.org vocabulary.

@id

In GRCSchema.org, used within JSON-LD for structuring data, the "@id" property serves as a unique identifier for a particular item described in the JSON-LD. This identifier is a URL that can either point to a resource where more information about the item can be found, or act as a node identifier within the data structure itself that can be referenced by other parts of the document.

The use of "@id" is crucial for distinguishing between different entities that may have similar characteristics or properties but are distinct entities. For example, two people might have the same name and job title but are different individuals with different identities.

@elementId

THe @elementId” is the record identifier for any particular record in a set. Furthermore, the element_id is in there for external sources to leverage for reference without having the parse the entire @id to get it from. The @id can also be something like children entities, i.e. "https://api.app.unifiedcompliance.com/authority-document/1/citation" for the citations in the document.

Here’s an example of how "@id" and “@elementId” might be used in a JSON-LD snippet:

{
  "@context": "https://schema.org",
  "@type": "AuthorityDocument",
  "@id": "https://api.app.unifiedcompliance.com/authority-document/1",
  "elementId" : 1
}

In this example, "@id" provides a URL that uniquely identifies the AuthorityDocument. This URL could lead to a page providing more detailed information about her or serve as a reference that other JSON-LD structured data can link to, ensuring it refers specifically to this Jane Doe, not any other.

version

Versioning of Things is tracked within GRCSChema.org, versioning of properties is not. This allows participating organizations to document the version of JSON-LD the schema is intended to be complied with. However, GRCSChema.org is designed to be backward compatible, minimizing the need for tracking specific version dependendencies.

Tying a schema “Thing” to a particular vendor’s API version should be done by the ISV as part of their API context (see Schema versioning vs. API versioning).

CoreMetaData

The “@CoreMetaData” provides a crucial component for tracking and managing metadata associated with any digital assets or records within the target system. This schema is quite comprehensive and is designed to maintain detailed records about the creation and modification of items, along with metadata that ensures integrity, traceability, and status tracking. Here’s a breakdown of each component and its intended use:

CoreMetaData Structure

  • @type: Specifies the type of the object, in this case, "CoreMetaData".
  • checksum: A checksum value generated using Verhoeff algorithm based on properties like 'date_modified', 'id', and 'live_status'. This is typically used to ensure data integrity and detect any errors or alterations in the data.
  • created and modified: These objects track the creation and modification details of the item. Each contains:
  • organization: Details about the organization involved in the creation or modification, including a unique identifier (URL) and the name of the organization.
  • person: Details about the person who created or modified the item, including a unique identifier (URL) and their name.
  • timeStamp: The exact date and time when the item was created or modified.
  • liveStatus: Indicates whether the item is currently active ("live") or deprecated. This helps in lifecycle management of the data.
  • notes: Any additional textual information that might be relevant to the item.
  • status: Describes the release status of the item, with values like Released, In Review, On Hold, etc. This is useful for tracking the workflow and lifecycle of the item.
  • supersededBy: A URL pointing to another item that replaces or supersedes the current item. This is important for maintaining version control and historical tracking.
  • validated: Indicates the validation status of the record, with possible values showing different levels of review and approval.

Purpose and Use of CoreMetaData

The "CoreMetaData" structure serves multiple purposes:

  1. Data Integrity and Verification: The use of checksums and validated flags helps ensure that the data has not been tampered with and is recognized as accurate by relevant authorities.
  2. Audit Trail: By tracking both creation and modification details (who, when, what), the schema provides a comprehensive audit trail that is essential for compliance, governance, and historical records.
  3. Lifecycle Management: Fields like liveStatus, status, and supersededBy assist in managing the lifecycle of the item, from creation to deprecation, including all revisions and status changes along the way.
  4. Traceability: Each record is traceable through unique identifiers and timestamps, ensuring that users can follow the history and lineage of an item. Overall, this schema is geared towards robust data management and governance, providing all necessary tools to ensure that data is accurate, up-to-date, and traceable through its lifecycle.

clientReferenceId

When creating new records (POST), or updating existing records (PATCH), an additional level of validation and non-repudiation is presented as an optional key-value pair. Because there is a great deal of information associated with this, please reference this page for more information.