Policies and Architecture

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This is a public OCI Working Draft for review by OCI Members and other interested parties. This section describes the status of this document at the time of its publication. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use OCI Working Drafts as reference material or to cite as other than "work in progress". A list of current OCI Recommendations and other technical documents can be found here https://github.com/Open-Credentialing-Initiative.

This specification describes the requirements for all OCI Policy and Architecture documentation created through external and internal collaboration. The contribution process is described elsewhere. Please visit Contribution Process.

Keywords

The following keywords indicate the precedence and general rigidity of a given conformance criterion, and are to be interpreted as:

MUST and MUST NOT indicate strict requirements from which no deviation is permitted.

SHOULD and SHOULD NOT indicate preferred approaches; among several possibilities, one is recommended as particularly suitable without mentioning or excluding others, but is not necessarily required, or that (in the negative form) a certain course of action is discouraged but not prohibited.

MAY and NEED NOT indicate possible and permissible approaches that are not necessarily preferred.

CAN and CANNOT indicate a capability, whether material, physical or causal or, in the negative, the absence of that capability.

Keywords appear in bold and ALL CAPS in the Conformance Criteria. The keywords MAY, RECOMMENDED, REQUIRED, OPTIONAL, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [[RFC2119]] [[RFC8174]] when, and only when, they appear in all capitals.

Versioning of OCI Specifications and Documents

Various conformance and technical specifications created by OCI rely on each other. Hence, changes to any of such documentation must be managed with care to prevent lack of clarity, failure of services to interoperate or any other consequential disruption to services provided or consumed by external and internal stakeholders who rely on the OCI framework. This policy describes how OCI manages versions and releases of its conformance and technical documentation.

Scope

OCI manages versions of its releases at the following two levels:

Versioning on a repository basis
Versioning on a file basis

Versioning on a repository basis may occur when a group of semantically connected documents is published by OCI. Changes in versions in a repository are always reflected via Releases found in the corresponding repository on GitHub. For example: https://github.com/Open-Credentialing-Initiative/schemas/releases.

Versioning on a file basis may occur when stakeholders directly consume a file published by OCI. This is often the case with json-ld schemas, open-api specifications or other programmatically required resources. This is done to avoid breaking existing integrations and dependencies which directly consume these files. Any updates made to them mean that stakeholders have to consciously update a link to a file in order to increment their version as well.

Semantic Versioning

In order to version published work, OCI utilizes a well-established and known versioning mechanism: Semantic Versioning.

Versioning in OCI is largely borrowed from the Semantic Versioning approach.
The core principles are:

Each document in OCI MUST declare a semantic version.
A version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 → 1.10.0 → 1.11.0.
Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

Changes in version have to adhere to the following guideline:

MAJOR (X) version when incompatible changes are made.
MINOR (Y) version changes are made in a backwards compatible manner.
FIX (Z) version when backwards compatible fixes are made.

Interoperability Profiles

To ensure that defined sets of OCI-versioned documents remain interoperable, these must be adjusted and reviewed in lockstep. To this end an overarching entity, called Interoperability Profile, is leveraged. An Interoperability Profile encapsulates multiple OCI-versioned documents that directly relate to each other or functionally rely on each other. An integrator MUST observe the versioning of the complete interoperability profile instead of manually choosing which document versions within such a set to implement.

Increases in single OCI documents will be reflected in appropriate version changes in the connected OCI interoperability profile.