OCA Package version 1.0.1

Overlays Capture Architecture (OCA) is a standardized language for describing data schemas.

Overlays Capture Architecture is optimized for overlays, where the community can improve the functionalities of a schema to meet their needs while maintaining interoperability.

OCA Package extends the functionality of OCA by specifying how new overlays created by communities can be added to OCA objects without disrupting those overlays that belong to the core specification. The core specification overlays remain in one object of OCA Package (oca_bundle) with a Self-addressing Identifier (SAID) calculated only from in-specification OCA overlays. Additional overlays that are not part of the core specfication are added to a second object (extensions) where their addition does not change the calculation of the SAID of the in-specification overlays. This helps with interoperability as different communities may not recognize each others community overlays, but all should recognize the in-specification overlays. The SAIDs of these in-specification overlays will therefore remain consistent across communities.

Components of an OCA Package

OCA Package formalizes a way to develop, publish and use overlays that are outside of the OCA specification.

The OCA specification describes ocabundle which collects a capture base and associated overlays into a single object. OCA Package describes how additional overlays outside of the official specification can be added to an OCA Schema without altering the ocabundle object.

Link to a fully worked example of an OCA Package.

Figure: example ocapackage structure. The ocabundle is from the OCA specification and contents are out of scope for OCA Package. Extensions are grouped according to community and bundle_digest target. In this example there is one community (adc) and two schema bundles (blue and orange highlight) which are referenced by two community groupings.

OCA Bundle

The overlays and capture base of the OCA Specification are contained in the ocabundle object of an ocapackage. The contents of oca_bundle are governed by the Human Colossus Foundation and documented into the official OCA Specification.

The SAID of any bundle when calculated only includes capturebase and OCA overlays documented by the official specification. A bundle can reference other bundles in a hierarchical fashion. The referenced schemas are found inside dependencies of an ocabundle object. Dependencies only include official specification oca_bundles.

Extension overlays

Extension within ocapackage contains overlays developed by various communities. These overlays are outside of the governance of the Human Colossus Foundation and can be created by members of the community to meet their needs. Community overlays are governed by their respective communities. A community can consist of one individual implementing a single project addressing a single need. A community can also be a large consortium of partners with their own governance structure for determining composition, versioning and acceptance of their community overlays. When present in an ocapackage, community overlays MUST follow the OCA Package Design Requirements.

Governance of OCA Package

The oca_package is under the governance of the OCA Package governance body.

The OCA Package governance body MUST maintain the official standard specification for oca_package and the OCA Package Design Requirements. OCA Community overlays MUST follow the OCA Package Design Requirements.

Governance of OCA Package community names

Communities are free to establish and govern their own namespace within OCA Package. Communities must avoid collision within the namespace and ensure that their names are unique. Communities can request to register their unique name with the OCA Package governance body which lists accepted names here at the end of this specification. Provide the namespace name (no wildcards), source URL and email contact to register. These namespaces are recognized by the OCA Package community as privileged and exclusive to that community. Reserved namespaces include internal* where anyone can use names that begin with internal (such as internal-uog) to be used within private systems and example which can be used for examples similar to the usage of example.com.

Promotion of overlays to official OCA Specification:

HCF maintains the official implementation the OCA specification. To become become part of the official OCA specification any overlay must go through the official RFC process.

Technical Implementation of an OCA Package

Technical implementation of the OCA package is outside of the scope of the OCA Package governance body. Communities are expected to develop their own implementations.

The ADC implementation can be found on npm.

OCA Package Design Requirements

1. Community overlays MUST follow OCA Package Syntax Requirements
2. Documentation for Community overlays MUST be published publically and follow the OCA Package Overlay Documentation Requirements.
3. SAID calculations of the ocapackage contents (excluding ocabundle) follow requirements documented in CESR Specification. This non-normative post documents the process and design choices of the calculations of SAIDs and includes links to libraries implementing the SAID calculation which can be used by overlay developers. The author Kent Bull is officially contributing documentation to the ongoing work of the latest CESR specification.
4. Lexicographical sorting follows the requirements documented in section 3.2.3 Sorting of Object Properties

OCA Package Syntax Requirements

An oca_package is a canonicalized serialized JSON object that MUST include the following top-level keys, in this exact order:

1. d where the ocapackage MUST use "d":"_SAID value of entire ocapackage\". The SAID is calculated from the canonicalized and serialized JSON object.

2. type where the ocapackage MUST use "type":"ocapackage/1.0". The versioning MUST follow semantic versioning.

3. oca_bundle which MUST contain two objects:

• bundle which MUST contain overlays and capture_base as specified by the OCA specification v1.0.1 and be canonicalized and serialized according to that specification.
• dependencies which MAY contain additional bundle (sub)schemas as specified by the OCA specification v1.0.1, that are referenced by the schema of oca_bundle.

1. extensions which MAY contain community group(s) with there developed community overlays.

• community group(s) which MUST contain oca_bundle(s) they are extending identified by their capture_base digest. For example, a community group named adc would describe and identify an oca_bundle it extends as the following:

json // adc is the community name { "adc": { "_SAID value of the extended oca_bundle": { FIELDS OF THE EXTENSION OVELAY } } }

• Community overlays can contain different key-value items relevant to what the community is extending. Importantly the structure of the community overlay MUST always be consistent unless a new version emerges.

• A community overlay MUST be canonicalized and serialized according to the OCA Package Design Requirements.

• In addition to the above, each community overlay MUST include always include required and/or optional top-level keys, in the below exact order:

  REQUIRED TOP-LEVEL KEYS ON EVERY EXTENSION OVERLAY:

 1. `d` where the community overlay MUST use "d":"_SAID of the correctly canonicalized overlay_".
 2. `type` where the community overlay MUST use type= "community/overlays/community_name/overlay_name/vX.X" where `community_name` (i.e., `adc`) is the name of the community, `overlay_name` (i.e., `ordering`) is the name of the overlay, and versioning MUST follow semantic versioning (i.e., `1.0` etc.). Putting it all together, the `type` would look like "community/overlays/adc/ordering/v1.0".

 **OPTIONAL TOP-LEVEL KEYS OF AN EXTENSION OVERLAY:**

 3. `language`: a community overlay MAY include **language key** and if present, MUST reference language using "language":"xxx" if they are specific to languages where xxx is the 2 or 3 letter ISO language code.

 > All other content defined in the community overlay scope follows after these four top-level keys and their canonicalization MUST be described in the community overlay documentation.

• Communities MUST ensure that their overlay names are unique within their community_name namespace.

OCA Package Overlay Documentation Requirements

This section outlines the different sections of published documentation for each overlay. Each header MUST be present in a publically documented overlay description and if a section is left empty include the phrase "Intentionally left empty" to indicate it is not a mistake.

Title: overlay name by community name - v version (e.g. Ordering by ADC - v1.0)

Community grouping: "community/communityname/extension/vX.X" where communityname is the name of the community and versioning MUST follow semantic versioning.

Authors: overlay author names

Date released: date of version release ISO standard YYYY-MM-DD

This overlay follows official OCA Package requirements documented at (link to OCA Package source)

Description:

• Describe the functionality of the overlay, what needs the overlay is addressing and complete descriptions of components of the overlay. Any references to community standards belong in this section.

Canonicalization Rules:

• Extension overlay documentation MUST describe their canonicalization rules; when contents are insertion ordered and when they are lexicographically ordered.

Example:

• Provide at least one example of the overlay which has been fully canonicalized and serialized (in JSON) for calculating the correct overlay SAID value.
• The capturebase SAID does not need to reference a specific capturebase but MUST be well formed.
• The capture_base example SAID is used in the calculations of the overlay SAID.
• The example MAY be formatted with line breaks and indentations, including reorganizing objects for readability after the SAID has been calculated.

Rules summary:

• Extension overlay documentation MUST summarize all the requirements (MUST and MAY) for the overlay.
• Extension overlay documentation MUST list all keys (i.e., top-level and low-level and what type of value(s) they can be assigned to) of the overlay that are required to be present (even if left empty) and which keys are optional.

Test case:

• At least one fully worked example MUST be provided.
• The worked example MUST be a fully canonicalized, JSON serialized oca_package with SAIDs calculated.
• The fully worked example MUST include a minimal set of capture_base and any other overlays that the documented overlay depends on and MAY include more overlays.
• The example MUST NOT be transformed for readability or altered in any way that would interfere with the reproducible calculation of the SAID directly from the test case example.

Normative references

• OCA specification v1.0.1
• 3.2.3 Sorting of Object Properties
• CESR Specification for SAID calculations

Table of Accepted Community Names

| Name | URL source | email contact | Date | | ---- | ---------------------------------------------------- | --------------- | ---------- | | adc | https://github.com/agrifooddatacanada/ADC_extensions | adc@uoguelph.ca | 2025-01-01 |