Table of Contents

Top

    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.

    Object Connections

    Data Design

    Mapping

    In using CTDL with your system, you will often need to map certain classes and properties to and from your system's data and the CTDL equivalents. To make this easier, you can use the CER Mapping Reference to quickly look up the most important classes and properties in CTDL.

    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

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

    Types of Credential

    Credential earned through work-based learning and earn-and-learn models that meet standards and are applicable to industry trades and professions.
    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.
    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.
    Recognition designed to be displayed as a marker of accomplishment, activity, achievement, skill, interest, association, or identity.
    Credential that designates requisite knowledge and skills of an occupation, profession, or academic program.
    Time-limited, renewable credential awarded by an authoritative body to an individual or organization for demonstrating the designated knowledge, skills, and abilities to perform a specific occupation.
    Academic credential conferred upon completion of a program or course of study, typically over multiple years at a college or university.
    Badge offered in digital form.
    Credential awarded by educational institutions for successful completion of a course of study or its equivalent.
    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.
    Credential awarded by examination that demonstrates that an individual has acquired secondary school-level academic skills.
    Credential awarded to skilled workers on successful completion of an apprenticeship in industry trades and professions.
    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.
    Credential awarded upon demonstration through apprenticeship of the highest level of skills and performance in industry trades and professions.
    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.
    Credential that addresses a subset of field-specific knowledge, skills, or competencies; often developmental with relationships to other micro-credentials and field credentials.
    Visual symbol containing verifiable claims in accordance with the Open Badges specification and delivered digitally.
    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.
    Credential assuring that an organization, program, or awarded credential meets prescribed requirements and may include development and administration of qualifying examinations.
    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.
    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

    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

    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

    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.
    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.

    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 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 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).

    Find Data

    In most cases, you will be coming to the Registry to find data. If you know the identifier for the data you want, you can Get the record. Otherwise, you can Search for the data.

    Get Record

    You can get a record from the registry directly by its envelope ID with the following syntax:

    https://sandbox.credentialengineregistry.org//ce-registry/envelopes/{envelope ID}

    For example:

    https://sandbox.credentialengineregistry.org//ce-registry/envelopes/993292f5-4bb2-46cb-8e4d-470375cf58c1

    Search API

    The Credential Engine Registry offers an open search API to make it easy to find information. To use this API, structure one or more URL parameter tokens and send an HTTP GET request to the appropriate API endpoint.

    Endpoints

    To search the registry, use:

    https://sandbox.credentialengineregistry.org//ce-registry/search

    To search for a specific type of data within a specific community, use:

    https://sandbox.credentialengineregistry.org//ce-registry/{type}/search

    Parameters

    The following are available as parameters for use in a search API query:

    Empty Search

    An empty search will match all records in the registry.

    https://sandbox.credentialengineregistry.org//ce-registry/search

    Full-Text Search

    Tries to find anything in the record related to the term.

    Parameter: fts

    Value: Any URL-encoded text string

    https://sandbox.credentialengineregistry.org//ce-registry/search?fts={value}

    For example:

    https://sandbox.credentialengineregistry.org//ce-registry/search?fts=some%20text%20value

    Paging

    Control the number of results per page, as well as which page of results to return.

    Parameters: page and per_page

    Values: page takes a number indicating which page of results to return, starting with 1. per_page takes a number indicating how many results per page to return. For example:

    https://sandbox.credentialengineregistry.org//resources/search?per_page=20&page=2

    Note that the response headers will include URLs for the next and previous pages, as well as the total number of results. For example:

    Content-Length: 227025
    Content-Type: application/json
    Link: <http://localhost:9292/search?page=1&per_page=20>; rel="first", <http://localhost:9292/search?page=1&per_page=20>; rel="prev", <http://localhost:9292/search?page=12&per_page=20>; rel="last", <http://localhost:9292/search?page=3&per_page=20>; rel="next"
    Per-Page: 20
    Total: 223

    Filter by Date Range

    Find results that were published before and/or after the specified dates.

    Parameters: from and until.

    Values: Both from and until take ISO 8601 DateTime strings. For example:

    https://sandbox.credentialengineregistry.org//ce-registry/search?from=2016-07-20T00:00:00Z&until=2016-07-31T23:59:59Z

    The API will also attempt to parse natural language values, but this is not recommended:

    https://sandbox.credentialengineregistry.org//ce-registry/search?from=3 months ago
    https://sandbox.credentialengineregistry.org//resources/search?until=now
    https://sandbox.credentialengineregistry.org//resources/search?from=february 1st&until=last week

    Find by Any Field

    Search a specific field for a value.

    Parameter: The URL-encoded CTDL key to look for

    Value: The URL-encoded value of the CTDL key

    https://sandbox.credentialengineregistry.org//ce-registry/search?{key}={value}

    Examples:

    https://sandbox.credentialengineregistry.org//ce-registry/search?ceterms:ctid=993292f5-4bb2-46cb-8e4d-470375cf58c1
    https://sandbox.credentialengineregistry.org//resources/search?ceterms:name=My Credential Name
    https://sandbox.credentialengineregistry.org//resources/search?ceterms:description=Text to look for

    You can query on nested fields by providing a URL-encoded, JSON object that the desired records should contain. For example, to search in the keywords array:

    https://sandbox.credentialengineregistry.org//ce-registry/search?ceterms:keyword=["Desired keyword"]

    To search within a list of objects:

    https://sandbox.credentialengineregistry.org//ce-registry/search?ceterms:industryType=[{"ceterms:targetNodeName": "Food Manufacturing"}]

    Tools

    The following tool is available to assist developers in writing search queries. Additional tools will be released as they become available:

    This tool provides fields for entry of search parameters, displays the actual query sent to the registry, and the results of a given query.

    Publish Data

    Publishing data requires several things:

    Sign Up

    In order to publish data you must first register your organization. To add your organization:

    Get Your API Key

    Refer to this section in the Registry Assistant page.

    Format Your Data

    To publish your data, it must be all of the following:

    The good news is that the Registry Assistant API will shield from needing to know these low level details.

    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.

    Follow the instructions on the Registry Assistant API Handbook page to get started.

    Validation

    In order for data to be successfully used by consumers of data from the Registry, it must all share a common format. This is so that consuming systems do not need to be overly burdened with conditional handling of the variety of options offered by a flexible structure like JSON.

    For instance, many properties could contain 1 or more values, and these properties could be encoded as singular items or single-value lists, and either would be considered valid JSON. However, a consuming system would need to have certain checks in place to handle this scenario, since it would not know whether to expect a single item or an array that might contain 0-n items. If it were guaranteed that this field would always be an array, even if there was only one item, then coding for this property is greatly simplified.

    In order to alleviate this and other such issues, a strict validation is enforced on all data being published to the registry. This validation is performed via an impelementation of JSON Schema that uses a Credential Engine Registry "profile" of CTDL. This simply means that the Credential Registry uses most of CTDL, with certain constraints on things like multiplicity and required fields, so that publishing and consuming systems can reliably communicate using the same structure.

    A page is currently under development that describes the CER profile in greater detail, and is unfortunately not available yet. However, the following links provide the actual JSON Schema used to validate the data attempts to make it into the Registry:

    Updating Existing Data

    This section is not applicable when using the Registry Assistant API.

    Versions of records in the Registry are associated with each other by a CTID that is shared by all versions of a resource. Individual versions are identified by their Registry Envelope ID, which is unique to each envelope. Making an update in the Registry means sending a new, complete record with an existing CTID.

    Updates in the Registry are handled by storing updated versions of the metadata along with previous versions. By default, when a CTID is requested, the Registry will return the most recent available record for it. Previous versions are available through special API calls, and will not be returned by default. Partial updates (for example, updating a single field within an existing record) are not supported - you will need to provide the entire replacement record when publishing an update.

    To update existing records in the Registry, you will need three things:

    Make a PUT request to the resource's URI with the replacement resource record as its payload. For example:

    PUT https://sandbox.credentialengineregistry.org//resources/ce-e0959e98-78fd-495e-9189-ed7d3dafc70c

    Deleting Data

    This section is not applicable when using the Registry Assistant API.

    To delete a resource in the Registry that you own or have rights to, you will need the following:

    Make a DELETE request with the following payload:

    {
      "envelope_community":"ce_registry",
      "delete_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJkZWxldGUiOnRydWV9.CEdAcsR-qKrjmwXHdxxJWsrH2zltQzhyfv8R0Adm08ckWpXNw4ZDEzJFCMP8QP4p_Qaun5rmK6IoFXA_xtTJ_xGVtLEVXt5ajpgyUubbgVj33nUxxPhCWhjHWssbdw6wYIUl2Ny0nKU5jSDt-eiJ3bhAtykFzi3teqqM3sl8OQEMPwxSrxTevJxpFcT0874Ymb5_8bjQ_GygqvD_dx6z3vy9UkS6ZffYb_CCYub1u-nFD9kHb7mhLZwAuOEA5DOGJT4pflK8rdAJUz9OwyMAO4yRK2ZYvjPBNkQPyNIBzescGTI8P7FkoE2JRVsPwuh5wncnSmE7XLsjr84pioAWkQ",
      "delete_token_format":"json",
      "delete_token_encoding":"jwt",
      "delete_token_public_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp32A8vGxAxwgVM1pLNUb\nPH0WPB1tX6ASoyOcXvCuW0cTHGdxnbYY+3TbLmjBQSUiznUXWGO3eqTK9YU8kKAo\nApXtOZNwjBLxp5K3xZNjGv9mryqWiGN4IPQWvTR2lvLmPpNOPEhJETL9Hq9Lzzzk\nV0R/bdd2+5WxF83gV9tSH1FfmrEF5RZk8QoLCxdWxmymwF69M6AjV8KQnbZJazYK\n7dbei60Bs8Hy8OV23ehiW5kvUt7DUPBKxVtHvTySE2Ntmd/0Ib/s2bCIfZGJv2ts\nMerRRr665jRCQ43xU043qSPBLUa7TlWWiyqi5UUiWAlyPHXtxaaDJUajIYJD/1os\nCwIDAQAB\n-----END PUBLIC KEY-----\n"
    }

    For example:

    http DELETE /ce_registry/resources/urn:ctid:e0959e98-78fd-495e-9189-ed7d3dafc70c
    http DELETE /resources/urn:ctid:e0959e98-78fd-495e-9189-ed7d3dafc70c

    You should receive one of two responses:

    Registry Archive

    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.

    References