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.

    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 a learning opportunity.
    Educational opportunities include required and optional programs, courses of study, and other structured experiences intended to serve as educational or training events.

    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 (http://lr-staging.learningtapestry.com/resources/) with the CTID. Together, these form the unique resource identifier (URI) for your entity, which looks like this: http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/ce-registry/envelopes/{envelope ID}

    For example:

    http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/ce-registry/search

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

    http://lr-staging.learningtapestry.com/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.

    http://lr-staging.learningtapestry.com/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

    http://lr-staging.learningtapestry.com/ce-registry/search?fts={value}

    For example:

    http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/ce-registry/search?from=3 months ago
    http://lr-staging.learningtapestry.com/resources/search?until=now
    http://lr-staging.learningtapestry.com/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

    http://lr-staging.learningtapestry.com/ce-registry/search?{key}={value}

    Examples:

    http://lr-staging.learningtapestry.com/ce-registry/search?ceterms:ctid=993292f5-4bb2-46cb-8e4d-470375cf58c1
    http://lr-staging.learningtapestry.com/resources/search?ceterms:name=My Credential Name
    http://lr-staging.learningtapestry.com/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:

    http://lr-staging.learningtapestry.com/ce-registry/search?ceterms:keyword=["Desired keyword"]

    To search within a list of objects:

    http://lr-staging.learningtapestry.com/ce-registry/search?ceterms:industryType=[{"ceterms:targetNodeName": "Food Manufacturing"}]

    Tools

    The following tools are available to assist developers in writing search queries:

    This tool provides fields for entry of search parameters, displays the actual query sent to the registry, and the results of a given query.
    This tool retrieves the record for a given CTID and renders it as a hierarchy of tables to provide a visualization of the JSON data.

    Publish Data

    Publishing data requires several things:

    Sign Up

    To be determined

    Get Your API Key

    To be determined

    Format Your Data

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

    Four Ways to Publish

    There are four major methods for publishing to the registry:

    The image below illustrates, at a high level, how these methods compare. Note that the "Formatting" column is simply a helper that returns CTDL-formatted data to your system and does not perform any publishing. It is included due to its relevance to the Third-Party publish method.

    There are four primary means of getting data into the Registry.

    Third-Party Publish

    The third-party publish method involves the use of a "Registry Assistant" API and associated "API Helper Class", and is offered by Workit. This helper class is a slimmed-down version of CTDL that uses a simplified structure and is intended to make it easier to build a system that publishes to the Registry. Your system will need to map to the properties and classes used by the API, and then send it to the Workit system.

    There are two API endpoints to send your data to:

    The Format endpoint will transform the data in the API Helper Class you send it to a fully-fleshed out CTDL metadata document in JSON-LD format. It will then return this to your system, enabling you to publish that data on your website, publish directly to the registry yourself, or take any other action you want.

    The Publish endpoint within the Registry Assistant API will first format your data as described above, then publish it to the Registry under Workit's account on your behalf. This is useful if you do not wish to worry about any further interaction with the data or with the Registry, but you will not have as much control over the process as you otherwise would.

    Registry Proxy Publish

    The registry proxy publish method requires your system to provide a properly-formatted CTDL document in JSON-LD format, and publish it directly to the Registry. Note that you can use the Format API endpoint discussed above to make it easier to obtain such a document, then send it to the Registry directly.

    This approach is suitable for systems that are capable of constructing CTDL metadata directly, and systems that wish to have more control over the publishing process. Under this process, the data will be published to the Registry under your system's Registry account, and will have no ties to the Workit application discussed above.

    This approach also allows you to use the full range of CTDL classes and properties, some of which may not be available in the Registry Assistant API. Note that the data you attempt to publish will still have to pass the validation testing performed by the Registry itself.

    Website/Crawler Publish

    The website/crawler publish method is the most optimum way for you to publish your metadata. In essence, your system formats CTDL metadata (either directly or via the Registry Assistant API's Format method), and then makes the resulting data available on the relevant webpage(s) of your website (preferably as a block of JSON-LD). The Credential Engine Registry crawler (still in development at this time) will then be able to read that data from your page, at which point it will take care of publishing it, much like the Registry Proxy Publish method above.

    There are several advantages to this method:

    Because this method ultimately results in linked data about Credentials both on the web and in the Registry, this is the preferred method for providers of Credential data to use.

    Self-Signed Publish

    the self-signed publish method gives you maximum control over the publishing and ownership of your data in the Registry, but requires additional steps to perform the publishing, as well as management by your system of the PGP keys used to publish your credentials. This method is not recommended unless you have a good reason to make use of it. Note that your CTDL metadata will still have to pass the same validation as any other method.

    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

    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 http://lr-staging.learningtapestry.com/resources/ce-e0959e98-78fd-495e-9189-ed7d3dafc70c

    Deleting Data

    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