1.1 Scope and Context

1EdTech published its first specification in 1999. To date some one hundred new specifications and new versions of specifications have been published. Apart from the actual specification documentation, 1EdTech release many other artifacts to support the adoption of those specifications. These artifacts are also subject to revision. In many cases, EdTech systems support more than one version of a specification. 1EdTech Ecosystems are composed, simultaneously, of many specifications and several versions and profiles of those specifications. Therefore, a clear and consistent versioning scheme is essential to enable the EdTech sector to track, exploit and audit expected interoperability capabilities enabled by the use of the 1EdTech specifications and related artifacts.

Versioning must be addressed from several perspectives, namely:

• Specification - the version of the specification itself;
• Specification Documentation - the version of the documentation that contains the definition of the specification in the context of the version of the specification;
• Other Specification Artifacts - the version of the artifacts created to support the adoption of the specification in the context of the version of the specification;
• 1EdTech Common Data Model (CDM) - the versioning of the definitive set of common data and service models that provide the foundation of the 1EdTech specifications;
• Software - versioning of the set of software components, tools and systems that are used to support the adoption and adaptation of the 1EdTech specifications.

This Versioning Framework document MUST be cited, and used, in the appropriate artifacts created as part of the 1EdTech specification development process and other related processes. In some circumstances it may be appropriate to not follow the defined versioning mechanisms: in such cases a clear justification MUST be supplied alongside the citation of this document.

1.2 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT REQUIRED, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

1.3 Structure of this Document

The structure of the rest of this document is:

1.4 Key Terms

Profile

A refinement of a 1EdTech specification such that the data model properties have added constraints and extensions are used as permitted by the original specification. Examples of added constraints includes changing the multiplicity from one-to-many (1..*) to only one (1), changing a data-type of 'string' to a list of enumerated string values, etc. The form of the extensions is dependent upon the binding technology being used. An essential property of a profile is that an instance of any profile is a valid instance of the base specification: the inverse is NOT true.

Semantic Versioning

A simple set of rules and requirements that dictate how version numbers are assigned and incremented. The Semantic Versioning specification was originally authored by Tom Preston-Werner, inventor of Gravatar and cofounder of GitHub.

1.5 Acronyms

API

Application Programming Interface

CASE

Competencies & Academic Standards Exchange

CDM

Common Data Model

IETF

Internet Engineering Task Force

JSON

Java Script Object Notation

JSON-LD

Java Script Object Notation Link Data

LTI

Learning Tools Interoperability

OASIS

Organization for the Advancement of Structured Information Standards

QTI

Question & Test Interoperability

REST

Representational State Transfer

RFC

Request for Comment

URL

Uniform Resource Locator

VDEX

Vocabulary Definition & Exchange

WSDL

Web Services Description Language

WS-I

Web Services Interoperability Consortium

XML

Extensible Markup Language

XSD

XML Schema Definition

YAML

Yet Another Mark-up Language

3.1 Versioning

Versioning of specifications will use the following semantic versioning principles:

• A specification MUST have major and minor version numbers;
• A specification MUST NOT have a patch version of '0' i.e. the patch version MUST ONLY be used when the value is greater than '0';
• The first major release will be versioned as '1.0' e.g. Comprehensive Learner Record 1.0;
• Subsequent major releases will be versioned as '2.0', '3.0', etc. Maintenance of backwards compatibility is NOT REQUIRED when releasing a major release;
• A minor release MUST be used when new backwards compatible functionality is added and/or features are marked as deprecated. Examples of this are OneRoster 1.1 and 1.2;
• A patch release MUST be used when backward compatible bug fixes are introduced. Examples of this are QTI 2.2.1, QTI 2.2.2, etc.
• In the case where both minor and patch changes occur in the same release then the minor version is incremented and the patch number dropped.

A new version of a specification MUST ONLY occur when there is a change in functionality. Editorial changes in the associated documentation MUST NOT change the specification version i.e. it is the document version that is changed.

Specification development includes the phases of 'Base Document, 'Candidate Final' and 'Final Release'. The phase of release is NOT reflected in the version of the specification. Instead this will be denoted by the 'Status' field of the associated artifact.

3.2 Versioning of Profiles of Specifications

Profiling is the process by which an 1EdTech specification is tailored to fit the requirements of a specific community. A community may be a collection of organizations in a market sector and/or geographically based. For example 1EdTech is supporting the development of a OneRoster 1.2 profile for use in K-12/Schools sector in Norway. A profile is created to enable more precise formal definition of Conformance & Certification i.e. to move from the generic practice enabled by the 1EdTech specification, to best practice enforced by the profile for the specific community. By definition, a profile increases the set of conformance requirements.

A profile MUST be aligned to a base specification. More than one version of a profile MAY exist and the profile itself will be subject to maintenance and development. Therefore, versioning a profile will follow the same rules as for the base specification itself i.e. two version identifiers MUST, and a third, MAY be used. There MUST be a separate version for the profile. For example the first version of the European Profile of the OneRoster 1.2 Specification has the title of OneRoster 1.2 European Profile 1.0.

There is no naming convention for profiles except for use of the word 'Profile' in name of the profile.

3.3 Conformance & Certification

Whenever a new version of a specification, or a new version of a profile of a specification, is released there are significant implications for Certification and Conformance. The points of note for certification are:

• Major Release - a new certification system will be deployed. Support of the new version will be OPTIONAL. 1EdTech will maintain certification for all major versions that have not been deprecated;
• Minor Release - a new certification system will be deployed. Support of the new version will be OPTIONAL. 1EdTech will maintain certification for all minor release versions that have not been deprecated;
• Patch Release - the relevant certification system will be upgraded. Support of the new version will be REQUIRED. 1EdTech will NOT maintain certification for previous patch releases.

Vendors MUST follow the appropriate certification as part of their normal development cycle and the 1EdTech re-certification requirements.

4.1 Specification-based Documents

For documents published as part of a specification e.g. the OneRoster Service Model, two versions MUST be used for the:

• Specification being defined;
• Document itself.

The version of the specification is taken from the specification itself. The version for the final release document uses a single incrementing integer starting at 1.

An example of the versioning of a document as part of the file name is: onerosterv1p2_rostering_infomodelv1.html for document version 1 of the OneRoster 1.2 Rostering Service. Note that the dot notation is replaced by 'p' notation i.e. 1.2 is mapped to 1p2 and the character 'v' precedes the actual version number. This dual versioning enables the document itself to be revised independent of a change to the actual specification. It is not unusual for an 'Implementation Guide' to undergo many revisions as new recommendations are added; over time experience in the usage of a specification increases and so new insights must be documented.

For pre-Final Release documents the document versioning takes the format 0.Y where 'Y' is an integer that is >1. Again the dot notation is replaced by 'p' notation in file names.

4.2 Profile-based Documents

As discussed in Versioning of Profiles in Specifications the base 1EdTech specification may be profiled to meet the specific needs of a community. If the name of the profile document introduces a profile-specific component then it MUST include a version number. The same general rules as specified for the versioning of specifications MUST be applied i.e. two version identifiers MUST, and a third, MAY be used.

For example, the European profile for the 1EdTech OneRoster 1.2 exists and the corresponding profiled document has the file name: imsonerosterv1p2_europeanprofilev1p0_v1.html. The profile is named 'europeanprofile' and this is the first version of that profile. It MUST be noted that the final 'v1' is the version for that HTML document.

4.3 Non-Specification-based Documents

For documents that are not published as part of a specification, for example this document and the 1EdTech Security Framework, only the document version is REQUIRED. The principles and format for the document version are the same as for the equivalent component for specification documents.

5.1 OpenAPI Files

When defining service-based specifications with REST/JSON bindings, 1EdTech make use of OpenAPI files as defined by [OAS2] and [OAS3]. 1EdTech use a profiled version of the OpenAPI syntax as produced through the 1EdTech Model Driven Specification approach. The OpenAPI specification itself is under revision and at present 1EdTech create both version 2 and version 3 OpenAPI artifacts (version 3.1 is almost ready for general adoption and version 3.2 is undergoing initial development). Therefore, OpenAPI artifacts MUST use the format of three version numbers:

• For the specification being defined;
• For the version of OpenAPI being used;
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version for the OpenAPI follows the semantic versioning principles of:

• An artifact's technology MUST have a major version number;
• An artifact's technology MAY have a minor version number;
• An artifact's technology MUST NOT have a patch version number;
• An artifact's technology MUST reflect the version of the technology being used.

An example of the versioning of an OpenAPI artifact as part of the file name is: onerosterv1p2rostersservice_openapi2_v1p0p0.json or onerosterv1p2rostersservice_openapi3_v1p0p0.yaml for OpenAPI version 2 and 3 respectively. Note that any dot notation is replaced by 'p' notation and the character 'v' does not precede the actual version number. This triple versioning enables the artifact itself to be made available in multiple versions of the technology.

5.2 XML Schema Files

When defining data model-only specifications with XML-based bindings, 1EdTech make use of XML Schema Definition (XSD) files [XSD]. Version 1.1 of XSD, the latest, was published in 2004. No revisions are expected to this specification and so there will be no artifact technology-based version. Therefore, XSD artifacts MUST use the format of two version numbers:

• For the specification being defined;
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version of the specification is taken from the specification itself. The version for the artifact follows the semantic versioning principles given at the start of Section 5.

Note that the dot notation is replaced by 'p' notation i.e. 1.0.0 is mapped to 1p0 and the character 'v' precedes the actual version number. An example of XSD file versioning is for the 1EdTech Question and Test Interoperability 3.0 specification of: imsqti_asiv3p0_v1p0p0.xsd for the first release of that file.

A key feature of XSDs is the use of namespaces to enable the combination of multiple XSDs without causing tag clashes. Namespaces MUST be versioned with respect to the specification only. Versioning of namespaces will use the following semantic versioning principles:

• A namespace MUST have major and minor version numbers;
• A namespace MUST NOT have a patch release version;
• With the exclusion of the patch version number, the version of the namespace is taken from the specification itself.

5.3 JSON Schema Files

JSON Schema is a vocabulary to enable the annotation and validation of JSON documents [JSONSD]. 1EdTech use standalone JSON Schema files to enable the validation of individual JSON payloads exchanged in the REST/JSON-based bindings for an 1EdTech service specification. The standardization of this technology is being undertaken actively by the IETF, with the latest version having a $schema keyword value ofhttps://json-schema.org/draft/2020-12/schema: OpenAPI version 3.1 is aligned with this version of JSON Schema. New versions are expected to be published and so the JSON Schema artifacts MUST use the format of three version numbers:

• For the specification being defined;
• For the version of JSON Schema being used with [JSONSD] denoted as version 1 (further permitted values will be defined, when appropriate, in this document);
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version for the JSON Schema follows the semantic versioning principles of:

• An artifact's technology MUST have a major version number;
• An artifact's technology MAY have a minor version number;
• An artifact's technology MUST NOT have a patch version number;
• An artifact's technology MUST reflect the version of the technology being used.

The version of the specification is taken from the specification itself. The version for the artifact follows the semantic versioning principles given at the start of Section 5.

Note that the dot notation is replaced by 'p' notation i.e. 1.0.0 is mapped to 1p0p0 and the character 'v' precedes the actual version number. An example of JSON Schema file versioning is for the 1EdTech OneRoster 1.2 specification of: onerosterresourcesservicev1p2-getallresources-200-responsepayload-jsonschema1_v1p0p0.json for the first release of that file (this file is used to validate response payloads for the 'getAllResources' endpoint returned with a HTTP code of 200.

5.4 JSON-LD Context Files

When defining service and data model specifications with JSON Linked Data (LD) bindings, 1EdTech make use of JSON-LD Context Files [JSONLD]. Version 1.1 of JSON-LD, the latest, was published in 2020. JSON-LD context files enable the definition of locally meaningful names which can then be used by importing systems to understand the data structures being described. No revisions are expected to this specification and so there will be no artifact technology-based version. Therefore, JSON-LD artifacts MUST use the format of two version numbers:

• For the specification being defined;
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version of the specification is taken from the specification itself. The version for the artifact follows the semantic versioning principles given at the start of Section 5.

Note that the dot notation is replaced by 'p' notation i.e. 1.0.0 is mapped to 1p0p0 and the character 'v' precedes the actual version number. An example of a JSON-LD context file is for the 1EdTech Competencies & Academic Standards Exchange (CASE) 1.0 specification of: imscasev1p0_context_v1p0p0.jsonld for the first release of that file.

5.5 Web Services Description Language (WSDL) Files

When defining service-based specifications with SOAP/XML-based bindings, 1EdTech make use of Web Services Description Language (WSDL) files [WSDL]. Version 2.0 of WSDL, the latest, was published as a W3C Recommendation in 2007. No revisions are expected to this specification and so there will be no artifact technology-based version. 1EdTech specifications MUST make use of WSDL 1.1 and NOT WSDL 2.0 (1EdTech did not migrate to using and/or supporting WSDL 2.0). It should be noted that 1EdTech made use of the various profiles for WSDL published by the Web Services Interoperability (WS-I) Consortium (now published under the auspices of the OASIS). Therefore, WSDL-based artifacts MUST use the format of two version numbers:

• For the specification being defined;
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version of the specification is taken from the specification itself. The version for the artifact follows the semantic versioning principles given at the start of Section 5.

Note that the dot notation is replaced by 'p' notation i.e. 1.0.0 is mapped to 1p0p0 and the character 'v' precedes the actual version number. An example of WSDL file versioning is for the 1EdTech Group Management Service 2.0 specification of: GroupManagementServicev2p0_SyncWSDL_v1p0p0.wsdl for the first release of that file.

A key feature of WSDL is the use of namespaces to enable the combination of multiple XSDs without causing tag clashes. Namespaces MUST be versioned with respect to the specification only. Versioning of namespaces will use the following semantic versioning principles:

• A namespace MUST have major and minor version numbers;
• A namespace MUST NOT have a patch release version;
• With the exclusion of the patch version number, the version of the namespace is taken from the specification itself.

5.6 Vocabulary (VDEX) Files

The 1EdTech Vocabulary Definition Exchange (VDEX) 1.0 specification, published in February 2004, defines a grammar for the exchange of value lists of various classes: collections often denoted "vocabulary". Specifically, VDEX defines a grammar for the exchange of simple machine-readable lists of values, or terms, together with information that may aid a human being in understanding the meaning or applicability of the various terms. VDEX can also express strictly hierarchical schemes in a compact manner while allowing for more loose networks of relationship to be expressed if required. Several 1EdTech specifications use VDEX to make vocabularies available in an independent machine readable format. There is only one version of VDEX. Therefore, VDEX-based artifacts MUST use the format of two version numbers:

• For the specification being defined;
• For the version of the artifact itself (apart from the file type extension, this MUST be the last set of characters in the file name).

The version of the specification is taken from the specification itself. The version for the artifact follows the semantic versioning principles given at the start of Section 5.

Note that the dot notation is replaced by 'p' notation i.e. 1.0.0 is mapped to 1p0p0 and the character 'v' precedes the actual version number. An example of vdex file versioning is for the 1EdTech QTI Usage Data & Item Statistics 3.0 specification of: imsqti_usagedatav3p0_itemstatisticsglossary_v1p0p0.xml for the first release of that file. The same versioning MUST be used for any associated human-readable forms e.g. an HTML page of: imsqti_usagedatav3p0_itemstatisticsglossary_v1p0p0.html.

5.7 Miscellaneous

5.8 Profile-based Artifacts

As discussed in Versioning of Profiles in Specifications the base 1EdTech specification may be profiled to meet the specific needs of a community. If the file name of the artifact introduces a profile-specific component then it MUST include a version number. The same general rules as specified for the versioning of other specification artifacts MUST be applied i.e. two version identifiers MUST, and a third, MAY be used.

An example of XSD file versioning for the 1EdTech Question and Test Interoperability 3.0 specification is: imsqti_asiv3p0_v1p0p0.xsd for the first release of that file. An SBAC profile for the QTI 3.0 specifications exists and the corresponding profiled XSD has the file name: imsqti_asiv3p0_sbacv1p0_v1p0p0.xsd. The profile is named 'sbac' and this is the first version of that profile. It MUST be noted that the final 'v1p0' is the version for that XSD.

7.1 Conformance Test System Software Release Versioning

For Conformance Test System software, two versions MUST be used:

• For the specification being defined;
• For the version of the software itself.

The version of the specification is taken from the specification itself. The version for the software follows the semantic versioning principles:

• The software release MUST have major, minor and patch version numbers;
• The first major release will be versioned as '1.0.0' e.g. OneRoster 1.2 Service Provider Conformance Test System 1.0.0;
• Subsequent major releases will be versioned as '2.0.0', '3.0.0', etc. Maintenance of backwards compatibility is NOT REQUIRED when releasing a major release;
• A minor release MUST be used when new backwards compatible functionality is added and/or features are marked as deprecated. Examples of this are OneRoster 1.2 Service Provider Conformance Test System 1.1, etc.
• A patch release MUST be used when backward compatible bug fixes are introduced. Examples of this are OneRoster 1.2 Service Provider Conformance Test System 1.1.1, etc.
• In the case where both minor and patch changes occur in the same release then the minor version is incremented and the patch number becomes '0'.

7.2 Reference Implementation Release Versioning

For Reference Implementation software, two versions MUST be used:

• For the specification being defined;
• For the version of the software itself.

The version of the specification is taken from the specification itself. The version for the software follows the semantic versioning principles:

• The software release MUST have major, minor and patch version numbers;
• The first major release will be versioned as '1.0' e.g. LTI Advantage Reference Implementation 1.0;
• Subsequent major releases will be versioned as '2.0', '3.0', etc. Maintenance of backwards compatibility is NOT REQUIRED when releasing a major release;
• A minor release MUST be used when new backwards compatible functionality is added and/or features are marked as deprecated. Examples of this are LTI Advantage Reference Implementation 1.1.0;
• A patch release MUST be used when backward compatible bug fixes are introduced. Examples of this are LTI Advantage Reference Implementation 1.1.1, QTI 2.2.2, etc.
• In the case where both minor and patch changes occur in the same release then the minor version is incremented and the patch number dropped.

Note that, by definition, a Reference Implementation SHOULD be able to support the operation of the equivalent specification profiles as well as the base specification. Therefore, no separate versioning, and naming convention, is required for the support of profiles.

7.3 Other Software Release Versioning

All non-specification related software will follow semantic versioning principles:

• The software release MUST have major, minor and patch version numbers;
• The first major release will be versioned as '1.0.0';
• Subsequent major releases will be versioned as '2.0.0', '3.0.0', etc. Maintenance of backwards compatibility is NOT REQUIRED when releasing a major release;
• A minor release MUST be used when new backwards compatible functionality is added and/or features are marked as deprecated i.e. 1.1, 1.2, etc.
• A patch release MUST be used when backward compatible bug fixes are introduced i.e. 1.1.1, 1.1.2, etc.
• In the case where both minor and patch changes occur in the same release then the minor version is incremented and the patch number becomes '0'.

7.4 API Versioning

As stated previously, the [SEMVER] document addresses versioning for Public APIs. Therefore, this will be adopted for versioning of all 1EdTech private and public APIs. In summary:

• An API MUST have major, minor and patch version numbers;
• The first major release will be versioned as '1.0' e.g. REST API 1.0;
• Subsequent major releases will be versioned as '2.0.0', '3.0.0', etc. Maintenance of backwards compatibility is NOT REQUIRED when releasing a major release;
• A minor release MUST be used when new backwards compatible functionality is added and/or features are marked as deprecated;
• A patch release MUST be used when backward compatible bug fixes are introduced. Examples of this are REST API 1.0.1, REST API 1.0.2, etc.
• In the case where both minor and patch changes occur in the same release then the minor version is incremented and the patch number becomes '0'.

A new version of an API MUST ONLY occur when there is a change in functionality. Editorial changes in the associated documentation MUST NOT change the API version i.e. it is the document version that is changed.