Credential Engine Registry Handbook

Last Updated on 4/26/2019

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.

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-6f05953f-8541-4c79-80be-5ce11040f5b6. It is possible to generate these yourself (which you will need to do if your data set contains circular references), or they will be generated for you if they are not present. 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

In order to reference an entity in the registry, you will need to combine the Registry's resources URL (https://sandbox.credentialengineregistry.org/resources/) with the CTID. Together, these form the unique resource identifier (URI) for your entity, which looks like this: https://sandbox.credentialengineregistry.org/resources/ce-6f05953f-8541-4c79-80be-5ce11040f5b6. 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).

Object Connections

Data Design

Object Types

The Credential Registry supports several "top level" or "main" CTDL classes that are considered to be standalone and can be individually published to and retrieved from the Registry. All other CTDL classes must be embedded inside of one of these classes when being published to the Registry. These top level classes are:

Types of Organization

ceterms:CredentialOrganization

Organization that plays one or more key roles in the lifecycle of a credential.

ceterms:QACredentialOrganization

Quality assurance organization that plays one or more key roles in the lifecycle of a credential, learning program, or assessment.

Types of Credential

ceterms:ApprenticeshipCertificate

Credential earned through work-based learning and earn-and-learn models that meet standards and are applicable to industry trades and professions.

ceterms:AssociateDegree

College/university award for students typically completing the first one to two years of post secondary school education.

Equivalent to an award at UNESCO ISCED 2011, Level 5.

ceterms:BachelorDegree

College/university award for students typically completing three to five years of education where course work and activities advance skills beyond those of the first one to two years of college/university study.

Equivalent to an award at UNESCO ISCED 2011, Level 6.

Use for 5-year cooperative (work-study) programs. A cooperative plan provides for alternate class attendance and employment in business, industry, or government; thus, it allows students to combine actual work experience with their college studies. Also includes bachelor's degrees in which the normal 4 years of work are completed in 3 years.

ceterms:Badge

Recognition designed to be displayed as a marker of accomplishment, activity, achievement, skill, interest, association, or identity.

ceterms:Certificate

Credential that designates requisite knowledge and skills of an occupation, profession, or academic program.

ceterms:Certification

Time-limited, revocable, renewable credential awarded by an authoritative body for demonstrating the knowledge, skills, and abilities to perform specific tasks or an occupation.

Certifications can typically be revoked if not renewed, for a violation of a code of ethics (if applicable) or proven incompetence after due process. Description of revocation criteria for a specific Certification should be defined using Revocation Profile.

ceterms:Degree

Academic credential conferred upon completion of a program or course of study, typically over multiple years at a college or university.

ceterms:DigitalBadge

Badge offered in digital form.

ceterms:Diploma

Credential awarded by educational institutions for successful completion of a course of study or its equivalent.

ceterms:DoctoralDegree

Highest credential award for students who have completed both a bachelor's degree and a master's degree or their equivalent as well as independent research and/or a significant project or paper.

Equivalent to UNESCO ISCED, Level 8.

ceterms:GeneralEducationDevelopment

Credential awarded by examination that demonstrates that an individual has acquired secondary school-level academic skills.

ceterms:JourneymanCertificate

Credential awarded to skilled workers on successful completion of an apprenticeship in industry trades and professions.

ceterms:License

Credential awarded by a government agency that constitutes legal authority to do a specific job and/or utilize a specific item, system or infrastructure and are typically earned through some combination of degree or certificate attainment, certifications, assessments, work experience, and/or fees, and are time-limited and must be renewed periodically.

ceterms:MasterCertificate

Credential awarded upon demonstration through apprenticeship of the highest level of skills and performance in industry trades and professions.

ceterms:MasterDegree

Credential awarded for a graduate level course of study where course work and activities advance skills beyond those of the bachelor's degree or its equivalent.

Equivalent to an award at UNESCO ISCED 2011, Level 7.

ceterms:MicroCredential

Credential that addresses a subset of field-specific knowledge, skills, or competencies; often developmental with relationships to other micro-credentials and field credentials.

ceterms:OpenBadge

Visual symbol containing verifiable claims in accordance with the Open Badges specification and delivered digitally.

ceterms:ProfessionalDoctorate

Doctoral degree conferred upon completion of a program providing the knowledge and skills for the recognition, credential, or license required for professional practice.

Equivalent to an award at UNESCO ISCED 2011, Level 8.

ceterms:QualityAssuranceCredential

Credential assuring that an organization, program, or awarded credential meets prescribed requirements and may include development and administration of qualifying examinations.

ceterms:ResearchDoctorate

Doctoral degree conferred for advanced work beyond the master level, including the preparation and defense of a thesis or dissertation based on original research, or the planning and execution of an original project demonstrating substantial artistic or scholarly achievement.

Equivalent to an award at UNESCO ISCED 2011, Level 8.

ceterms:SecondarySchoolDiploma

Diploma awarded by secondary education institutions for successful completion of a secondary school program of study.

Equivalent to an award at UNESCO ISCED 2011 Levels 2 or 3.

Assessments

ceterms:AssessmentProfile

Entity that describes the key characteristics of an assessment for a credential.

Characteristics described include, but are not limited to, processes for assessment development, maintenance, selection and evaluation as well as assessment examples.

The ceterms:AssessmentProfile is intended for use in describing stand-alone assessments. Assessments that are a part of a learning opportunity associated with a credential should be described as part the ceterms:LearningOpportunityProfile for that learning opportunity.

Learning Opportunities

ceterms:LearningOpportunityProfile

Entity describing an educational or training opportunity.

Opportunities include formal and informal educational training programs and classes, apprenticeship or work experience programs, or other structured or unstructured experiences that serve as educational or training activities.

Manifests

ceterms:ConditionManifest

Set of constraints, prerequisites, entry conditions, or requirements maintained at the organizational and/or sub-organizational level.

These conditions are intended to be referenced by external entities such as individual credentials in order to facilitate the process of their description and to reduce unnecessary duplication of data applicable across an array of entities.

ceterms:CostManifest

Entity that describes a set of costs maintained at, and applicable across the organizational and/or sub-organizational level.

Instances of these ceterms:CostManifest entities are intended to be referenced by other entities to augment the process of describing their costs.

Competency Frameworks

ceasn:CompetencyFramework

A description of a competency framework as a whole.

ceasn:Competency

Description of knowledge, skills, and/or abilities.

Concept Schemes

skos:ConceptScheme

Concept Schemes are used in CTDL to define controlled vocabularies.

skos:Concept

Concepts are used in CTDL to define terms in a controlled vocabulary.

Planned

ceterms:Pathway

Resource composed of a structured set of PathwayComponents defining points along a route to fulfillment of a goal or objective.

ceterms:AlignmentMap

An entity comprised of a set of alignment or mapping assertions between two existing entities such as mapping a certificate providing advanced standing to a degree.

Alignment maps provide the means for parties to assert sets of alignments between already existing entities created by themselves or other parties--e.g., a 3rd party mapping of a learning resource owned by one party to a credential owned by another; or, mapping a military occupational experience or Military Occupational Specialty (MOS code) as advanced standing to a course or credential.

ceterms:EmploymentOutcomeProfile

Entity that describes employment outcomes and related statistical information for a given credential.

ceterms:EarningsProfile

Entity that describes earning and related statistical information for a given credential.

ceterms:HoldersProfile

Entity describing the count and related statistical information of holders of a given credential.

Unstable Classes

Other classes in CTDL that are marked with a status of vs:unstable may be handled in the Registry in the future.

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
Spreadsheet-Based Bulk Upload
Registry Assistant API

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

Calling the Publish API

To call the publish API, you will need to make an HTTP POST request to the API endpoint specific to the artifact type being published. For example, to publish a credential you would use:

https://credentialengine.org/assistant/credential/publish

With your request, include two things: First, you will need to pass your organization's API key (see Getting your API Key) as a request header using the format:

Authorization: ApiToken [YOUR API KEY]

Second, a JSON object with properties to publish. The provided JSON object will be specific to the type of artifact being published.

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 the record directly via its CTID if you already know the CTID for the data you want.
Use a customized Search Widget provided by the Credential Finder.
Use the CTDL JSON-based Search API to build a system that can perform complex searches.
Download data in bulk to store and use offline within your system.

Get Record

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

Using /graph - to return the full document and any child entities such as blank nodes, or competencies for a competency framework
https://sandbox.credentialengineregistry.org/ce-registry/graph/{CTID}
Using /resource - to return only the main document and no child documents.
https://sandbox.credentialengineregistry.org/ce-registry/resources/{CTID}

For example:

https://sandbox.credentialengineregistry.org/graph/ce-8a82436e-49bf-4856-b67a-60f1984df77d1

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)

Sample Widgets

Indiana

The Indiana widget uses filters to only show credentials where the owning organization has an address in Indiana.

NOCTI

The NOCTI widget uses filters to only show credentials where the owning organization is NOCTI.

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 by "importing" it from the registry. This allows for applications that may need different access to the Credential Registry data than what the Search API provides.

For documentation about bulk downloading data from the Registry, 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.

In essence, the Search API works like this:

Your system constructs a JSON document that mirrors the structure of CTDL records in the Registry.

This document contains only the properties you wish to query on; all other properties are omitted.
This document may contain special operators to modify the behavior of the search for specific properties (such as requiring an exact match for text fields).
The order of properties and values does not matter, but the structure of the objects in your query does.
You will need to be aware of properties whose values use language maps instead of simple strings.
In general, properties contained within the same object are searched for with logical ANDs between them, while items in arrays are searched for with logical ORs between them. This behavior can be overridden if desired.

Your system passes the JSON document and your API key along with properties to enable paginating through result sets to the Search API endpoint.
The results will be passed back to your system as described below.

Preparing to use the Search API

Before you begin using the search API, you will need:

An approved Credential Engine organization account - Visit the Credential Engine Accounts System to get signed up.
An API Key for your organization - You can find this on your account dashboard after your organization is approved to search.
An understanding of CTDL - Review the CTDL Handbook and CTDL Explorer.

Calling the Search API

To call the search API, you will need to make an HTTP POST request to the API endpoint:

https://credentialengine.org/assistant/search/ctdl

With your request, include two things: First, you will need to pass your organization's API key as a request header using the format:

Authorization: ApiToken [YOUR API KEY]

Second, the body of the request must be a JSON object with the following properties:

Query: The CTDL JSON query itself.
Skip: An integer representing how many results to skip over before the value provided by Take is applied. Enables paging through large result sets. Defaults to 0.
Take: An integer representing how many results from the current result set to take after the value provided by Skip. Enables paging through large result sets. Defaults to 5.

An example HTTP POST body would look like this:


{
	"Query": { "ceterms:name": "My credential's name" },
	"Skip": 0,
	"Take": 10
}

It is recommended to use the Query Helper to develop, test, and debug queries before implementing them in your system's code.

CTDL JSON Query Structure

Since relevant, searchable data can exist in many different objects and places in CTDL, it is important to look for the correct data in the correct place. For instance, you would not look for the required assessments for a credential within the body of the credential itself; you would need to follow the CTDL structure as it appears in the Registry. Below are some examples that show this structure in use.

It is important to understand that multiple object types coexist in the Registry, and you will likely need to filter by these types to ensure you don't get assessments or learning opportunities when you're looking for credentials.

For more examples and to try out your own customized queries, use the CTDL Query Helper tool.

Special Search Terms

The search API supports several special search terms that can be combined with the CTDL schema to fine-tune how queries function:

The following properties are supported:

search:value: Sometimes you will want to change how a plain value (such as a string or number) is queried. Any time a property would normally take a value (such as a string, number, or boolean), you can substitute that value for an object. Inside that object, use search:value to convey the value, and add additional parameters (described below) to the object to adjust how that value is queried.; Accepts: A single value, an array of values, a single object, an array of objects
search:operator: In cases where search:value is present in the same object as this property, use this property to control how the values in search:value are queried. Otherwise, this will control how values in the object this property appears in are queried. See the list of supported values below for more information.; Accepts: search:andTerms, search:orTerms
search:termGroup: This term enables you to look for specific combinations of properties and values, even if they would otherwise overlap with each other. When combined with "search:operator": "search:orTerms", it also enables searches that need to find a piece of information in at least one property. See below for examples of usage.; Accepts: A single object, an array of objects
search:languageCode: If you use search:value when querying a language map property, you can provide a list of language codes via search:languageCode to check for the provided value. Leaving this property off or using search:anyValue as its value will look for the provided text regardless of which language code(s) it may be associated with in the data. See the language map handling section below for more information.; Accepts: An array of BCP 47 language codes or search:anyValue
search:matchType: When dealing with string properties, sometimes it's useful to check for matches in a precise way. The default matching for any string value is a case-insensitive "contains" match (e.g. "Does the data contain the string provided in the query?"). You can override this behavior by substituting an object as the value for the string property in the query, using search:value to contain the string you're looking for, and use search:matchType along with one of its accepted values to control how the string is matched.; Accepts: search:contains, search:startsWith, search:endsWith, search:exactMatch
search:isCaseSensitive: This property is used in conjunction with search:matchType to control whether or not the matches must match the text casing you provide. By default, this value is false.; Accepts: Boolean value (true or false)
search:greaterThan: When querying for a numeric value, use search:greaterThan to match any values greater than the one provided in the query. See the Value Ranges section below for more information.; Accepts: A numeric value (integer or decimal)
search:greaterThanOrEqualTo: When querying for a numeric value, use search:greaterThanOrEqualTo to match any values greater than or equal to the one provided in the query. See the Value Ranges section below for more information.; Accepts: A numeric value (integer or decimal)
search:lessThan: When querying for a numeric value, use search:lessThan to match any values less than the one provided in the query. See the Value Ranges section below for more information.; Accepts: A numeric value (integer or decimal)
search:lessThanOrEqualTo: When querying for a numeric value, use search:lessThanOrEqualTo to match any values less than or equal to the one provided in the query. See the Value Ranges section below for more information.; Accepts: A numeric value (integer or decimal)

The following values are supported:

search:andTerms: You can use search:andTerms as the value for search:operator to force the items in the search:value array to be queried using a logical AND instead of a logical OR (logical OR is the default handling for values in an array).; Value For: search:operator
search:orTerms: You can use search:orTerms as the value for search:operator to force the items in any object to be queried using a logical OR instead of a logical AND. (logical AND is the default handling for values in an object).; Value For: search:operator
search:anyValue: If you don't care what the value for a property is, and simply want to see if a piece of data has that property at all, use search:anyValue as the value for the property you're looking for.; Value For: Any CTDL/CTDL-ASN property
search:contains: This value will look in the data for strings that contain the string you provide in the query. This is the default value for string matches.; Value For: search:matchType
search:startsWith: This value will look in the data for strings that start with the string you provide in the query.; Value For: search:matchType
search:endsWith: This value will look in the data for strings that end with the string you provide in the query.; Value For: search:matchType
search:exactMatch: This value will look in the data for strings that exactly match the string you provide in the query.; Value For: search:matchType

Simple Queries

The following examples demonstrate basic search functionality by examining fields that exist at the top level of the object.

Look for all Certificates

This simple query looks for any record in the Registry with a @type value of ceterms:Certificate:

{ "@type": "ceterms:Certificate" }

Look for multiple types of Degrees

This query looks for any record in the Registry with a @type value that matches any of the provided values. A record in the Registry can only have one type value, but you can query for multiple values at once.

{ "@type": [ "ceterms:BachelorDegree", "ceterms:AssociateDegree", "ceterms:MasterDegree", "ceterms:DoctoralDegree" ] }

Look for Organizations with "Indiana" in their name

This query will look for any organization whose name contains "indiana" anywhere in the english version of its name property. By default, text searches are case-insensitive and will find a match anywhere in the property. Note that records must match both of the parameters in order to be returned. You can modify this behavior, as we will show later.

{ "@type": "ceterms:CredentialOrganization", "ceterms:name": { "en": "indiana" } }

Deeper Queries

These queries show examples of traversing other objects within the top-level object.

Search for text in the requirements

This query will look for any record in the Registry that has requirements which contain the text "must be able to" in the english version of its description. Note that this query is not constrained to any type of type level object, and so it could return credentials, assessments, and/or learning opportunities (as these are the only objects with a ceterms:requires property)

{ "ceterms:requires": { "ceterms:description": { "en": "must be able to" } } }

Search for records intended for specific audiences

This query will look for any record in the Registry that has requirements that target an audience of audience:FormerMilitary. Note that because the query mirrors the structure of CTDL, this query includes the structure of the ceterms:CredentialAlignmentObject used for Concept Schemes.

{ "ceterms:requires": { "ceterms:audienceType": { "ceterms:targetNode": "audience:FormerMilitary" } } }

Search for Certificates or Certifications with one set of requirements or another

This query will look for any certificates or certifications whose requirements match either of the provided sets of requirements. This is because the two sets of requirements (each of which is a ceterms:ConditionProfile) are in an array together. Items in arrays are, by default, queried as logical ORs. Objects are, by default, queried as logical ANDs, so this query could be thought of like this:

Find credentials where ( @type == ceterms:Certificate OR @type == ceterms:Certification ) AND ( ( requires the provided description AND requires the two conditions ) OR ( requires 3 years of experience ) )

{ "@type": [ "ceterms:Certificate", "ceterms:Certification" ], "ceterms:requires": [ { "ceterms:description": { "en": "must be able to" }, "ceterms:condition": [ "condition one", "condition two" ] }, { "ceterms:yearsOfExperience": 3 } ] }

Overriding Default AND/OR Operators

Sometimes it's useful to override the default behavior of objects (AND) and arrays (OR). The search API uses a pair of special properties for this: search:value to provide the values, and search:operator to control whether those values are compared via AND (search:andTerms) or OR (search:andTerms). The following examples illustrate the usage of these properties.

Find credentials with a ceterms:subjectWebpage of one value or another

This query will look for credentials with a ceterms:subjectWebpage value that matches any of the provided values. This takes advantage of the fact that the default handling for arrays, which is to use logical ORs.

{ "@type": "ceterms:BachelorDegree", "ceterms:subjectWebpage": [ "http://credreg.net/123", "http://credreg.net/abc", "http://credreg.net/789" ] }

If you need to provide multiple values for a single property, use an object as the value for that property and, inside that object, use search:value to contain the desired values. You can then use search:operator to control how those values are evaluated (the default is to use logical ORs since the contents of search:value are an array).

Find credentials that are available in multiple specified languages

This query will look for credentials whose ceterms:inLanguage property contains all of the provided languages, instead of simply looking for a match on any of them.

This is done by using search:value to contain the desired values and search:operator to dictate how to compare those values.

{ "@type": "ceterms:Certification", "ceterms:inLanguage": { "search:value": [ "en", "fr", "ru" ], "search:operator": "search:andTerms" } }

Find credentials that have one name or another name

This example will look for credentials with an english name that matches either of the names provided. Here we are overriding the normal structure of a language map (which would have only one value for each language field within ceterms:name).

{ "@type": "ceterms:BachelorDegree", "ceterms:name": { "en": [ "value 1", "value 2" ] } }

The next set of examples illustrate one of the nuances of using the CTDL structure to query for data. The first example will match a credential offered by any organization whose CTID is either of the provided values - a logical OR. If you were to use "search:operator": "search:andTerms" with this query, you would be looking for a credential offered by an organization whose CTID matches both values - and would get no results!

Find credentials that are offered by Organization A or Organization B

This query will search for credentials that are offered by either of the organizations you specify.

{ "@type": "ceterms:Certificate", "ceterms:offeredBy": { "ceterms:ctid": [ "ce-57aafbe6-7190-473e-a8e4-819363d590a0", "ce-03b053cb-9c62-468f-bcb6-711588a3dcee" ] } }

Find credentials that are offered by an organization with two CTIDs (incorrect!)

This query will search for credentials that are offered by an organization whose CTID matches both values - and will yield no results, since organizations only have one CTID. This is an example of what not to do.

{ "@type": "ceterms:Certificate", "ceterms:offeredBy": { "ceterms:ctid": { "search:value": [ "ce-57aafbe6-7190-473e-a8e4-819363d590a0", "ce-03b053cb-9c62-468f-bcb6-711588a3dcee" ], "search:operator": "search:andTerms" } } }

Instead, to look for a credential that is offered by both organizations, you need to look for two separate organizations as values for the ceterms:offeredBy property. Using "search:operator": "search:andTerms" here will look for a credential whose ceterms:offeredBy property contains both values.

Find credentials that are offered by Organization A and Organization B

This query will search for credentials that are offered by both of the organizations you specify, instead of simply matching either of them.

{ "@type": "ceterms:Certificate", "ceterms:offeredBy": { "search:value": [ { "ceterms:ctid": "ce-57aafbe6-7190-473e-a8e4-819363d590a0" }, { "ceterms:ctid": "ce-03b053cb-9c62-468f-bcb6-711588a3dcee" } ], "search:operator": "search:andTerms" } }

Sometimes it's necessary to find credentials where some piece of data appears in one or more properties, without requiring that it appears in all of them, or to look in certain combinations of properties. For these cases, use search:termGroup:

Find credentials where name or description includes the word "nursing"

This query will look for data in multiple fields in the root level of the document.

{ "search:termGroup": { "ceterms:name": "nursing", "ceterms:description": "nursing", "search:operator": "search:orTerms" } }

Find credentials where name and description include the word "nursing" or keywords includes the word "healthcare"

This query shows the flexibility of search:termGroup. You can use it to look for matches in different combinations of properties, with different operators for each combination.

{ "search:termGroup": [ { "ceterms:name": "nursing", "ceterms:description": "nursing" }, { "ceterms:keyword": "healthcare" } ] }

Find a certificate for math or a certification for programming

This query may not be very realistic, but it shows that search:termGroup can also look for different combinations of values for the same properties.

{ "ceterms:name": "a credential about integers", "ceterms:keyword": [ "integer", "numbers" ], "search:termGroup": [ { "@type": "ceterms:Certificate", "ceterms:keyword": [ "math", "algebra", "geometry" ] }, { "@type": "ceterms:Certification", "ceterms:keyword": [ "programming", "code", "C#" ] } ] }

Language Maps

All langauge-dependent string fields in the Registry use Language Maps to contain data. Language maps looks like one of the below examples, depending on whether or not the term supports multiple values. Note that for multi-value language maps (as shown below via ceterms:keyword), the number, order, and meanings of values are not necessarily identical across languages.


	"ceterms:name": {
		"en": "The name of the Credential in non-region-specific English",
		"en-us": "The name of the Credential in the US",
		"en-gb": "The name of the Credential in Britain",
		"fr": "The name of the credential in French",
		"ru": "The name of the credential in Russian"
	},
	"ceterms:keyword": {
		"en": [ "English keyword 1", "English Keyword 2", "English Keyword 3" ],
		"fr": [ "Keyword in French that covers the meanings of the first two english keywords", "Keyword exclusive to the list of French keywords" ],
		"ru": [ "Russian keyword 1", "Russian keyword 2", "Russian keyword 3", "Russian keyword 4"]
	}

Each property in a language map represents a BCP 47 language code that may or may not have a region code attached. A language map may have any number of these properties (though it will have at least one). This means that data in the registry may or may not have text in the language(s) that your system looks for.

The search API enables treating language maps like any other object in terms of which properties you query against. However, in order to avoid needing to send large queries that explicitly list the same text string for every potential combination of language and region code your system might accept, the search API supports special handling for properties that use language maps. This handling is detailed below.

The CTDL properties that use language maps are:

The following examples illustrate various ways to query against language map properties:

Find credentials by name, without regard to what language the name is in

This query will look for the provided name in the language map for the ceterms:name field without specifying what language(s) to check. If the provided text matches the name in any language, it will be considered a match.

{ "ceterms:name": "my credential's name" }

Find credentials by keywords, without regard to what language the keywords are in

This query works the same way as the first example, except that it uses multiple values. If any value matches, regardless of which language it matches, the credential will be returned.

{ "ceterms:keyword": [ "keyword 1", "keyword 2", "keyword 3" ] }

Find credentials by name, explicitly indicating which language to check

This query treats the language map like any other object in CTDL, effectively bypassing the special language map handling and specifying the exact language code to look for.

Note that if a credential had the provided text in an en-us field instead, it would be missed by this query.

{ "ceterms:name": { "en": "my credential's name" } }

Find credentials by name, specifying which languages to check (the strict way)

This query is functionally equivalent to the previous example, but it looks in multiple languages - and provides the text for each language.

Note that because ceterms:name is provided as an object here, the languag ecodes are AND-ed together. This means that every provided language must match in order for the credential to be returned by the search.

Note also that this is redundant if your query is looking for the same text in each of the provided languages - this redundancy can be avoided by following the "easy" example below.

{ "ceterms:name": { "en": "my credential's name", "en-us": "my credential's US name", "en-gb": "my credential's British name" } }

Find credentials by name, specifying which languages to check (the looser way)

This query is functionally equivalent to the previous example, except that the credential will be returned if any of the provided combinations of language code and value match the data.

Note that this is redundant if your query is looking for the same text in each of the provided languages - this redundancy can be avoided by following the "easy" example below.

{ "ceterms:name": { "en": "my credential's name", "en-us": "my credential's US name", "en-gb": "my credential's British name", "search:operator": "search:orTerms" } }

Find credentials by name, specifying which languages to check (the easy way)

This query will look for the provided text in any of the languages specified. This uses the same search:value property as some earlier examples, and another search-specific property, search:languageCode.

{ "ceterms:name": { "search:value": "my credential's name", "search:languageCode": [ "en", "en-us", "en-gb" ] } }

Find credentials by keywords, specifying the desired combinations of language and keywords (the strict way)

This query will look for matches in all of the provided languages for any of the provided keywords for that language.

Note that because ceterms:keyword is provided as an object here, the language codes are AND-ed together. This means that every provided language must have at least one matching keyword in that language in order for the credential to be returned by the search.

{ "ceterms:keyword": { "en": [ "english keyword 1", "english keyword 2" ], "fr": [ "french keyword 1", "french keyword 2" ] } }

Find credentials by keywords, specifying the desired combinations of language and keywords (the looser way)

This query is identical to the previous example, except that it will return the credential if any of the provided combinations of language and keyword match the data.

{ "ceterms:keyword": { "en": [ "english keyword 1", "english keyword 2" ], "fr": [ "french keyword 1", "french keyword 2" ], "search:operator": "search:orTerms" } }

Find credentials by keywords, specifying the languages and keywords to check without specifying which language goes with which keyword

This query is similar to the previous two examples, except that every combination of language and keyword will be checked, and if any match is found, the credential will be returned.

{ "ceterms:keyword": { "search:value": [ "keyword 1", "keyword 2", "keyword 3" ], "search:languageCode": [ "en", "en-us", "en-gb", "fr", "ru" ] } }

Controlled Vocabularies

CTDL uses a variety of controlled vocabularies (RDF Concept Schemes) to convey a wide variety of information in a way that is easy and reliable to reference. These references use ceterms:CredentialAlignmentObjects to reference concepts in a way that allows some data about the concept to be stored within the credential's record, for ease of use and consumption (and to handle various edge cases that are beyond the scope of this guide). It's important to be aware of the presence of ceterms:CredentialAlignmentObject when constructing CTDL JSON queries.

Find credentials by audience type

This query will look for credentials that reference a particular ceterms:Audience via its ceterms:audienceType property.

{ "ceterms:audienceType": { "ceterms:targetNode": "audience:CurrentStudent" } }

Find credentials by via a list of audience types

This query is the same as the above example, except that it looks for a match in a list of provided terms. If any term matches, the credential will be returned.

{ "ceterms:audienceType": { "ceterms:targetNode": [ "audience:CurrentMilitary", "audience:FormerMilitary", "audience:FullTime" ] } }

The next query illustrates why it's important to remember the nature of ceterms:CredentialAlignmentObject and its usage when pointing to terms in a vocabulary. ceterms:CredentialAlignmentObject only has one value for its ceterms:targetNode property.

Find credentials that match an entire list of audience types (incorrect!)

The query will attempt to find multiple values in a single instance of ceterms:CredentialAlignmentObject, and will therefore fail. This is an example of what not to do.

{ "ceterms:audienceType": { "ceterms:targetNode": { "search:value": [ "audience:CurrentMilitary", "audience:FormerMilitary", "audience:FullTime" ], "search:operator": "search:andTerms" } } }

In order to require a match for multiple vocabulary terms, you will need to construct your query such that each term has its own ceterms:CredentialAlignmentObject as illustrated below.

Find credentials that match an entire list of audience types

This query requires a credential to have multiple values for its ceterms:audienceType property, via multiple instances of ceterms:CredentialAlignmentObject.

{ "ceterms:audienceType": { "search:value": [ { "ceterms:targetNode": "audience:CurrentMilitary" }, { "ceterms:targetNode": "audience:FormerMilitary" }, { "ceterms:targetNode": "audience:FullTime" } ], "search:operator": "search:andTerms" } }

Value Ranges

Sometimes, it may be useful to look for data that falls between certain ranges. The examples below demonstrate the use of four properties designed to enable range-based queries: search:greaterThan/search:greaterThanOrEqualTo and search:lessThan/search:lessThanOrEqualTo

Find credentials with a specific cost

This query will look for credentials with a very specific cost (via the ceterms:estimatedCost property and the ceterms:CostProfile.

{ "ceterms:estimatedCost": { "ceterms:currency": "USD", "ceterms:directCostType": { "ceterms:targetNode": "costType:AggregateCost" }, "ceterms:price": 1000 } }

Find credentials whose costs fall within a specified range (exclusive)

This query is identical to the above example, except that it uses a set of special properties to look for matches that fall within a range: search:greaterThan and search:lessThan.

Note that because these two properties appear within the same object, they are logically AND-ed together by default. This results in the range being constrained to the two provided values.

{ "ceterms:estimatedCost": { "ceterms:currency": "USD", "ceterms:directCostType": { "ceterms:targetNode": "costType:AggregateCost" }, "ceterms:price": { "search:greaterThan": 500, "search:lessThan": 2000 } } }

Find credentials whose costs fall within a specified range (inclusive)

This query is identical to the above example, except that it uses search:greaterThanOrEqualTo and search:lessThanOrEqualTo to include the extremes of the range.

Note: You can mix and match search:greaterThan/search:greaterThanOrEqualTo and search:lessThan/search:lessThanOrEqualTo.

Searching Across Objects

The Credential Registry contains a vast collection of "top-level" objects. These are objects that have their own URIs and can be referenced directly in the Registry. The CTDL/CTDL-ASN top-level objects in the Registry are:

Subclasses of ceterms:Credential, excluding the ceterms:Credential class itself ceterms:CredentialOrganization ceterms:QACredentialOrganization ceterms:AssessmentProfile ceterms:LearningOpportunityProfile ceterms:ConditionManifest ceterms:CostManifest ceasn:CompetencyFramework ceasn:Competency

It is often useful to query for one type of top-level object based on its connections to another top-level object. For instance, retrieving a list of all credentials offered by an organization that operates in a certain state, or finding all credentials that require a certain assessment, or all learning opportunities that teach a competency that contains a certain phrase. These objects all exist on their own in the registry, but the search API is configured to allow you to query for these objects as though they exist within each other. See below for some examples.

Find everything offered by an organization (by ID)

This query will look for all credentials, assessments, and/or learning opportunities that are offered by an organization, given the Credential Registry's URI for that organization. This assumes you have the URI for the organization (or can construct it from the organization's CTID).

{ "ceterms:offeredBy": { "@id": "https://credentialengineregistry.org/resources/ce-8e33b663-c422-4922-9388-9df318c1af09" } }

Find all assessments offered by an organization (by ID)

This query is identical to the above query, except that it restricts the result set to ceterms:AssessmentProfiles. You can use any kind of query for data in the top-level objects together - just make sure you look for the right things in the right places.

{ "@type": "ceterms:AssessmentProfile", "ceterms:offeredBy": { "@id": "https://credentialengineregistry.org/resources/ce-8e33b663-c422-4922-9388-9df318c1af09" } }

Find everything offered by an organization (by URL)

This query functions the same way as the above query, but it does not assume that you already know the relevant organization's URI or CTID. Since the default matching for text properties is to see if the data contains the text you provide, it's generally a good idea to leave off anything that might make such a URL too strict (such as http/https, www, and trailing slashes).

{ "ceterms:offeredBy": { "ceterms:subjectWebpage": "myorganizationsdomain.com" } }

Find everything offered by an organization (by name)

This query functions the same way as the above queries, but it looks for a match in the organization's name. Beware: if two or more organizations' names match the text you provide, you may get more credentials, assessments, and/or learning opportunities than you expect.

{ "ceterms:offeredBy": { "ceterms:name": "my organization's name" } }

Find all credentials that require a competency that contains a phrase

This query will look for any certificates or certifications that require any competency whose ceasn:competencyText property contains the provided text.

Note the need to account for the presence of the ceterms:CredentialAlignmentObject as the value for ceterms:targetCompetency.

{ "@type": [ "ceterms:Certificate", "ceterms:Certification" ], "ceterms:requires": { "ceterms:targetCompetency": { "ceterms:targetNode": { "ceasn:competencyText": "some competency text" } } } }

Find all bachelor degrees offered by one organization that require an assessment offered by another organization that assesses a competency belonging to a framework created by a third organization

This query demonstrates the flexibility offered by the search API while also highlighting the need to ensure that you query for the correct data in the right place.

Note the use of both CTDL (via ceterms:) and CTDL-ASN (via ceasn:) here.

{ "@type": "ceterms:BachelorDegree", "ceterms:offeredBy": { "ceterms:name": "Organization A" }, "ceterms:requires": { "ceterms:targetAssessment": { "ceterms:offeredBy": { "ceterms:name": "Organization B" }, "ceterms:assesses": { "ceterms:targetNode": { "ceasn:isPartOf": { "ceasn:creator": { "ceasn:name": "Organization C" } } } } } } }

References

Credential Engine Registry Github Repository: https://github.com/CredentialEngine/CredentialRegistry