Credential Engine Significant Managed CTDL Specification Updates Process

Introduction

Credential Engine (CE) is committed to an open, collaborative, and iterative process as the Credential Transparency Description Language (CTDL) family of specifications (schemas and APIs) evolve over time. CE manages specifications for CTDL (for credentials and related information) and CTDL-ASN (for competency frameworks). These specifications are governed by a Namespace Policy and you can see their Release Histories on the CE Technical site.

Policy Changes

Development Process

The need for the evolution and expansion of CE specifications comes from subject and technical experts and other stakeholders and follows the process outlined below. CE's Board provides oversight to assure that the processes for change are open. Proposals for specification updates bring Advisory, Registry Participants and other stakeholders together through an open, collaborative process. Final decisions for specification updates are made by CE Leadership.

Expansion

Credential Engine's Technical Team develops a framing document to outline proposals for significant schema updates such as expansion. The document is frequently a result of input and recommendations by field experts and based on extensive technical reviews and modeling. This document includes a request for experts in the subject(s) and technical areas of the proposal to meet and provide input as a Task Group. The experts are recruited from all CE Advisory Groups, registry participants, and other organizations.

CTDL Advisory Group

Review of the framing document is included as an agenda item with the Task Group and the CTDL Advisory Group (CAG) open meetings, where in-depth discussion occurs. The CAG is an open group and interested parties can join the CAG or select to participate with open meetings as desired. All CE Advisory Groups and other stakeholders will be notified when these discussions are included on the agenda.

Collaboration

If relevant, the framing document is updated based on feedback from the CAG meeting and it is provided to all of the Advisory Group Chairs by the Credential Engine Executive Director. Advisory Group Chairs introduce the potential updates and provide the document to their respective group; members who are either subject or technical experts or have a general interest in the areas of the proposal are invited to participate in a formal Working Group, committing to between two to four webinars and actively providing input to the Proposal.

How to Suggest a CTDL Change

As a living language, anyone can suggest changes to the CTDL. Credential Engine’s CTDL team regularly reviews potential CTDL updates. There are two options to submit a change for a potential update:

• Submit the request as an issue to the Credential Engine's GitHub repository for Schema Development.
• If it’s not possible to use GitHub, submit your request to Credential Engine via email instead.

The GitHub repository is regularly watched and the email address is checked each business day.

Task Groups

The Technical Team convenes each Task Group with a charter. The Group provides input during webinars and via shared Google documents and discussion groups to develop a Proposal for final consideration.

Proposals

Based on input from the Working Group, the Technical Team develops the Proposal for updates with a deadline for final input. The Proposal is provided to all members of the Working Group, the CAG, and Advisory Group Chairs for distribution to their group. The Working Group must reach consensus for the Proposal to go forward.

Approval

All input is considered and Credential Engine Leadership make the final decision on the Proposal. If consensus is not reached, a determination is made whether to continue refining with further attempts to reach consensus. In the rare occasion where a negative decision is reached by CE Leadership, they will provide a written justification for inclusion in GitHub and for distribution to the CE advisory chairs, the CAG, and any other relevant stakeholders.

Publishing Process

The process for publishing updates to the schema is as follows:

1. The final Proposal is shared with everyone who participated in the update process. Credential Registry participants and Advisory Group members are notified of the public comment period and final release date.
2. The CE Technical Team sets release dates. Release dates typically fall on the last Friday of a selected month. The Proposal approved by CE Leadership is posted two weeks prior to the last release date as Pending and the Release Histories show all Pending updates. The two week period is the final opportunity for public comments.
3. All public comments are posted via a CE GitHub issues through which anybody can provide feedback.
4. Newly introduced CTDL terms may be marked as "Stable" or "Unstable" per Section 5.1 of the Namespace Policy. The period for which a term will remain Unstable is based upon the following criteria:
1. The term being utilized, and
2. No issues being raised.

Credential Registry Impacts

Updates to the schemas also impact systems that use those schemas:

1. Schema updates may impact publishing to the Credential Registry. If the schema changes are directly related to the Registry's constraints on the schema (such as required fields, multi-value fields, etc.) or to data validation during publishing, the Registry Assistant API is updated. All users who have approved Credential Engine publishing accounts are notified of the updates.
2. Per the Namespace Policy, CE makes a concerted effort to ensure that updates are made in a way that avoids breaking existing publishing and consuming systems. However, those systems may need changes in order to fully use the updated schema. The CE technical team is available to work with developers of these systems.

Credential Engine’s Advisory Groups are open and welcome subject and technical experts. To join an Advisory Group, please email info@credentialengine.org.