Credential Engine Registry Handbook

Last Updated on 6/7/2023

Introduction: Credential Engine Registry

The Credential Engine Registry is a repository of metadata about Credentials and related entities (such as organizations, assessments, and learning opportunities) and a set of related services to enable publishing, finding, and retrieving data about these entities.

This data is described using CTDL, which allows for consistent data across a variety of sources and types of entities.

CTDL is based on linked data principles. Individual CTDL records in the registry are formatted using JSON-LD. The Registry itself is not an RDF triples store, but the records within it can be easily translated into RDF triples.

Data in the Credential Registry is automatically and periodically uploaded to Archive.org for permanent keeping. These records are stored in the same way in which they are received, but are first base64 encoded to eliminate any potential issues with special characters.

Below is some key information that will help you quickly understand the structure and function of data in the Registry.

CTID

As you publish entities, you will receive responses that contain Credential Transparency Identifier (CTID) s. A CTID is a special unique identifier for a top-level object in the Registry, and is the preferred way to reference one entity from another. A CTID is not the same as a version number, nor is it the same as the unique identifier for a particular record in the Registry (the "envelope ID"). The CTID stays with your data as it evolves through updates and new versions, and the only time you should use a new CTID is if you are publishing a new entity, such as a new credential or a new assessment that cannot be substituted for the previous one. You are responsible for determining when it is appropriate to use a new CTID. Learn more about the CTID.

A CTID is combined with the Registry's Resources endpoint to form a unique URI that can be used with linked data systems. A CTID is combined with the Registry's Resources endpoint to form a unique URI that can be used with linked data systems.

A CTID is formed from the combination of a static prefix (ce-) and a standard UUID, and looks like this: ce-a4c0a549-aed3-4704-ade2-e81a5d76865b. CTIDs can be readily generated in most programming languages, and you will need to generate these yourself. Ensure that your system keeps track of CTIDs so that it can maintain references to entities in the Registry. You will not be able to update or remove records in the Registry without the CTID!

Through simple concatenation, easy-to-create parts come together to form a CTID, a linked data URI, and a JSON-LD identifier Through simple concatenation, easy-to-create parts come together to form a CTID, a linked data URI, and a JSON-LD identifier

In order to reference an entity in the registry, you will need to combine the Registry's resources URL (https://credentialengineregistry.org/resources/) with the CTID. Together, these form the unique resource identifier (URI) for your entity, which looks like this: https://credentialengineregistry.org/resources/ce-a4c0a549-aed3-4704-ade2-e81a5d76865b. Resolving the URI directly will yield the latest version of the data for that CTID (as stated, it is not tied to a particular version). Such URIs are used within the Registry to enable entities to point at each other, so that no entity needs to contain or maintain the actual data for another entity (for example, a Credential never contains the data about the learning opportunities it requires; it only contains references to them via their URIs, which return that data when resolved).

Sandbox and Production

There are currently two instances of the Registry, both of which share the same APIs and functionality. You will be able to use the information in this handbook for either one:

  • Sandbox - An environment meant for development and testing. Data here is typically short-term and may be deleted at any time. The URL for the sandbox is:
    https://sandbox.credentialengineregistry.org/
  • Production - The main Registry environment. Data here is real, long-lived, and should rarely (if ever) be deleted. The URL for production is:
    https://credentialengineregistry.org/

Organization Accounts and Published Organization Data

Credential Engine relies on other organizations as primary sources of the information in the Credential Registry. Part of enabling those organizations to publish data to the Registry is issuing and maintaining accounts for those Organizations. While there is a great deal of overlap in the data for an Organization Account in Credential Engine and the data about an Organization that gets published to the Registry using CTDL, these two objects are separate things with distinct purposes and it is important not to confuse one for the other. In other words, an Organization must first create an Organization Account for itself with Credential Engine and then publish an Organization record about itself, using CTDL, to the Registry. However, these are two entirely separate representations of the same Organization.

The Credential Registry and CTDL

The Credential Registry implements some additional constraints that are not part of CTDL. These additional constraints make up the Registry's "Application Profile" of CTDL. The following are a few examples of constraints on data in the Registry that are not part of CTDL:

  • All credentials must have a name and description.
  • The Person class is never used, since the Credential Registry does not contain any personal information or records dealing with individuals.
  • The keyword property allows multiple values, while subjectWebpage, in most cases, does not.
  • The description for a credential must have at least 25 characters.
  • The only valid value for the requires property is an array of Condition Profile objects.
  • Credential Engine checks for valid subjectWebpage URLs, but does not force a specific format for the telephone property, since different parts of the world have different formats for their phone numbers.
  • The Credential Alignment Object is always embedded as a nested object in the JSON data wherever it appears.
  • The value of a credential's accreditedBy property, if it is present, is always an array of strings where each string is either a URI that resolves to a separate record or a blank node ID that resolves (within the graph for that credential) to a blank node that describes the accrediting organization.
  • Records in the registry are considered to be from an authoritative source, except for blank nodes, which are non-authoritative and enable useful assertions like the one above about accreditation. Wherever possible, an authoritative record should be referenced by its URI instead of creating a blank node.

For a more detailed listing of the constraints in place for the Registry, consult the Policy Page.

Get Started

In order to publish or consume data, you must first register your organization:

  • Navigate to the Credential Engine Accounts site.
  • Create an account. After registering, you will receive an email to confirm your account.
  • After confirming your account, add your organization.
  • Complete the required information for the organization, including the publishing and/or consuming methods you want to use.
  • Submit your organization. Credential Engine will review and approve your organization.

Get Your API Key

Most of the ways you interact with the Registry will require an API key. The Get Record and Finder Widget search methods are notable exceptions. You can find your API key on your Credential Engine Account after your organization has been approved to publish or consume from the Registry. Note:

  • The same API key can be used for all functions that require an API key.
  • You should not reveal your API key to any other organization or user, or in any public place.
  • You can generate a new API key at any time from your dashboard.
  • If you wish to have another organization publish on your behalf, or if you wish to publish for another organization, use the functionality built into the account system to handle this. Do not share API keys.

Publish Data

Publishing data requires several things:

  • You must sign up for a Credential Engine Account
  • Your account must be authorized to publish data
  • You must obtain an API key
  • You must be able to provide data that conforms to the Minimum Data Policy
  • You must keep track of the data you publish in case you want to update or delete it later

Publish Your Data

There are three methods for publishing to the registry:

Manual Entry

For organizations with a small number of credentials that aren't updated very often, the manual publishing tool is likely the right choice. Authenticated users with approved organizations can access the manual publishing tool via the Credential Publisher website.

Using the tool is straightforward: Just click the "Add New" button in the Credential Publisher's header and select the type of data you want to publish. Then work your way through the forms presented, filling in as much information as you have available to you.

At the end, click the "Save Data" button, then click "Review" to see a summary of the information you entered. If you're happy with it, click the "Approve" button in the review interface. The Credential Engine staff will be notified, and conduct a final review of your data. If it meets the requirements and there aren't any issues, Credential Engine will then publish the data to the registry.

The Manual Entry tool will also enable you to update your data later.

Spreadsheet-Based Bulk Upload

Organizations with a large number of credentials but limited access to information technology development staff may find the bulk upload option to be the best bet. This tool can be accessed via the Bulk Upload Page on the Credential Publisher website.

To use this tool, you will need to be able to provide your credential information in a spreadsheet in CSV format, with columns that match up to what is provided to you by the instructions on the bulk upload page. You can download a spreadsheet template and fill it in manually, or export the data from your system. You can also update via the bulk upload tool.

Refer to the bulk upload page itself for detailed instructions and guidance.

Registry Assistant API

Organizations with a large number of credentials (and/or credentials that are updated frequently) and which have ready access to information technology development staff may find the Registry Assistant API to be the way to go. The Registry Assistant API Handbook should be the starting point for using this tool.

To use the Registry Assistant API, your system will need to be able to provide the data according to the schema described on the API Handbook page, and you will also need the API key from your dashboard in the Credential Engine Accounts System. It also helps if your development team is familiar with JSON and CTDL. It is also possible to update your data via the Assistant API.

For complete details on using the publishing API see section Registry Assistant API Handbook

Consume Data

In most cases, you will be coming to the Registry to find data. There are multiple ways to do so, depending on your needs. Each of these methods requires an approved Credential Engine Organization Account.

Get Record

You can get a record from the registry directly by CTID. There are three options:

  • Using /envelopes - to return the registry wrapper object that includes metadata about who published the data and links to previous revisions of that data, along with the data itself
    https://credentialengineregistry.org/envelopes/{CTID}
  • Using /graph - to return the full document and any child entities such as blank nodes, or competencies for a competency framework, in a flattened array structure
    https://credentialengineregistry.org/graph/{CTID}
  • Using /resources - to return only the main document and no child documents
    https://credentialengineregistry.org/resources/{CTID}

An example URI looks like this:

https://credentialengineregistry.org/graph/ce-a4c0a549-aed3-4704-ade2-e81a5d76865b

In most programming languages, an HTTP GET request is straightforward. For example, to get the data and parse it into an object in C#, you could do this:

Finder Widget

The Credential Finder hosts customizable Search Widgets that can be embedded in your website to provide your visitors with a way to search the data with very minimal technical know-how or investment.

Some examples of how a widget can be customized to filter search results are:

  • By Location (Country, Region, or City)
  • By Owning organization(s) - only show artifacts owned by the selected organization(s)
  • By relationships such as Offered By, Accredited By, Approved By, Regulated By - only show artifacts with the related relationship with the selected organization(s)

Bulk Download for Offline Use

The Credential Engine Registry offers a way to quickly download all of the data in the registry for use by your system directly. This allows for applications that may need different access to the Credential Registry data than what the Search API provides. The bulk download options below are suitable for use cases such as:

  • Analyzing the entire Registry's data for your own purposes
  • Combining Registry data with data from your own system to power a customized search
  • Keeping track of updates to data that are published by various organizations

Note:

  • All of the options below require that your organization be approved to consume data for "Offline Storage" in the Credential Engine accounts system.
  • You will need to periodically update the data, as the data in the Registry changes daily.

JSON-LD in a single zip file

This feature allows you to download the resources from the Registry as individual JSON-LD files through a single .zip file.

To access it, log into your Credential Engine account, click the "Download Data" tab from your organization's dashboard page, and click the "Download All Credential Registry Data" button.

JSON-LD in separate files

This feature enables you to run a lightweight automated process for downloading updated JSON-LD files from the Registry on a regular schedule. It can be configured to only download data that has changed, making it easier to keep your system up to date.

For documentation about using this feature, see the Github Repository.

Transformed data in a SQL Database

This feature offers the same functionality as above, but will convert the downloaded data to a ready-made SQL data structure for direct use by your system.

For documentation about using this feature, see the Github Wiki for the Credential Registry Import Tool.

Search API

The Credential Engine Registry offers a Search API to enable the development of Credential Registry search applications.

The Search API is suitable for use cases such as:

  • Getting live, real-time information from the Registry directly
  • Querying for data by leveraging the connections between resources in the Registry
  • Finding and filtering information based on the properties in CTDL

The Search API is not suitable for use cases such as:

  • Downloading individual records one at a time (see the Get Record section instead)
  • Mass downloading ("scraping") the Registry for many thousands of records (e.g. downloading all Certificates) or other bulk data (see the Bulk Download section instead)

To learn more about the Search API, visit the Search API Guide

References