Skip to main content
Version: Stage 5 - Deliverable Acceptance Check

GRID Data Schema Governance

This document outlines the versioning policy for all JSON schemas used within the Global Registry Information Directory (GRID), aligned with UN Transparency Protocol (UNTP) standards.

1. Versioning Model (SemVer)​

Schemas follow Semantic Versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking changes (e.g., converting an optional property to required, altering field regex patterns).
  • MINOR: Backward-compatible additions (e.g., adding new optional fields).
  • PATCH: Non-functional updates (e.g., clarifying descriptions or $comment notes).

2. Introduce New Fields​

All newly introduced fields MUST initially be defined as optional properties (omitted from the "required" array).

3. Mandatory Field Transitions​

Adding a mandatory field requires:

  1. Publishing a MINOR release introducing the property as optional.
  2. A minimum 6-month transition period for sovereign nodes to adopt the field.
  3. Promoting the property to "required" in the subsequent MAJOR release.

Note: The 6-month transition requirement applies only to schemas in live production. During draft, beta, or pilot testing phases, MAJOR version updates may be released without a transition period to resolve critical bugs or structural data model issues.

4. Deprecation Notice​

Fields targeted for removal MUST be marked with "deprecated": true in the schema at least 6 months prior to removal in a MAJOR release.

5. Permanence & Historical Resolution​

All published schema versions remain permanently hosted under https://grid.unece.org/schemas/<version>/<schema> to ensure historical records remain verifiable.

For example, the registrar.json schema, version v1.0.0, will be published and accessible here: https://grid.unece.org/schemas/v1.0.0/registrar.json

version v1.1.1 would be published here: https://grid.unece.org/schemas/v1.1.1/registrar.json [Illustrative only. v1.1.1 is not yet published so this link will fail]

The v1 release folder provides a rolling major alias for all v1.x.x releases: https://grid.unece.org/schemas/v1/registrar.json