Embedding CTDL in Websites

Last Updated on 6/18/2019

Introduction

When a search engine crawls your website, one of the things it looks for is embedded, structured data in a format and schema that the crawler understands. Such data allows the search engine to have a greater degree of confidence in the data it retrieves about the page compared to the normal, human-readable text data that it processes. This can lead to benefits to users looking for the data your site offers, and benefits to your site by increasing the chances that such users will see your site in the results for that search engine.

In addition to the rich description that CTDL enables, it can be made even more powerful by combining it with terms from Schema.org and publishing the resulting data on your website for search engine crawlers to discover. Schema.org, a collaborative of the major Web search engines including Google, Bing, Yahoo and Yandex, provides a common, universal set of types and properties that can be used by any website in the world, and which, if properly implemented, are understood by search engines. Using these terms on your website will eliminate much of the "guess work" that search engines must perform in order to determine the content of your web pages. Combining Schema.org terms with CTDL terms gives you the best of both worlds - optimal search engine discovery through a small but precise set of Schema.org properties and rich description through the addition of CTDL.

Google and Bing officially prefer data that is provided in the JSON-LD format.

Credential Engine makes it easy to express your credential data in CTDL using JSON-LD.

Understanding the Educational/Occupational Credential Schema

Development of the Schema.org schema of types and properties is the ongoing product of global crowd sourcing of expertise and was well underway when the work on CTDL began. From it's beginning, CTDL was developed following many, if not all, of the design principles set out by Schema.org and the result is that there is significant class and property overlap with Schema.org's recently approved Educational/Occupational Credential class (EOCred for short) and the classes and properties describing a credential in CTDL. So, in combination, Schema.org's EOCred provides the cake and CTDL provides the ice cream.

It is possible to convert a number of CTDL properties directly to terms used by the EOCred class, making it easy to use data from the Credential Registry on your website. Credential Engine offers an automated process to accomplish this, which works with any credential published to the Credential Registry.

Even though not all of the properties have an EOCred equivalent, search engines and other crawlers may nevertheless be able to interpret (or simply ignore) the unconverted properties.

Embedding Process

There are several ways to approach embedding EOCred data on your website, depending on:

  • Whether or not your data is published to the Credential Registry (and if not, whether or not you intend to publish it)
  • Whether or not your website's system is capable of making HTTP requests as part of building a page requested by the client (and if so, whether or not you want to fetch and embed the data server-side)

The simplest way to embed CTDL/EOCred data on your website just takes a few steps:

  1. Publish your data to the Credential Registry
  2. Get your Credential CTIDs
  3. Embed the automatic script tag in your webpages

Publish to the Credential Registry

There are a number of ways to publish. Review the Publishing section of the Credential Registry Handbook for details.

While it's possible to generate CTDL/EOCred data without publishing to the Registry, doing so is not recommended. The CTDL schema is deep and evolving, and the best way to ensure that your data will work with systems that use CTDL is to publish your data to the Credential Registry.

Getting Your CTIDs

All data published to the Credential Registry is identified with a unique CTID. This CTID is used to look up data in the Registry. You can easily retrieve the CTIDs for all of the credentials you publish by logging into the Credential Engine Accounts System and downloading your published credential data from the "Download Data" tab of your dashboard.

Some important notes to keep in mind:

  • If you publish to the Registry via the Registry Assistant API, the CTID for each credential you publish is also returned to your system as part of the publishing process.
  • The downloadable spreadsheet of CTIDs for your credentials also includes all of the items listed above, preformatted for each CTID for your convenience.
  • It is strongly recommended to store the CTID for each of your credentials within your own system's database, as CTIDs have a number of uses beyond just embedding data.
  • If you publish additional credentials, you will need to download the summary data again.

Instructions for Embedding CTDL/EOCred Data

Once you've published your data to the Credential Registry and obtained the CTIDs for your credentials, you can take advantage of the tools Credential Engine offers to automate this process.

Option One: Embeddable Script

Many websites offer an "embeddable" snippet of HTML you can place on your webpage to include things like a widget, article, or video player on your site while the data is hosted elsewhere. Credential Registry offers similar functionality for credential data via a simple script tag - except that only search engines will be able to see it.

If you downloaded a spreadsheet in the previous step, you can just copy the script tag from it. Otherwise, you can generate it using the template below. In either case, this script tag will automatically:

  1. Retrieve the CTDL/EOCred combined data for that CTID
  2. Create a JSON-LD script tag in the <head> of your webpage and inject the CTDL/EOCred data into it
  3. Trigger any custom functionality you wish to add

Depending on the details of how your website is managed, you can find step-by-step instructions in the next two sections.

Once your script tag is formatted, just add it to the webpage for that credential and Test your JSON-LD. If it works, then you're all set!

Copying From the Spreadsheet

Follow these instructions to add the script tag to your website. You will need one instance of the script tag on each page for each credential.

  1. Get the embeddable script from the Accounts System's Download Data tab the or Credential Publisher's Organization Summary page.
  2. Copy and paste the preformatted script tag for the credential from the spreadsheet into the source code for that credential's web page.
    • If you manage invdividual pages for each credential (e.g. static HTML), you will need to assign the appropriate script to each page based on that credential's CTID. The spreadsheet also provides the name for each credential to help you match them up.
    • If your website is data/template-driven, and your data contains the CTID for each of your credentials, update your template with the script tag and appropriate code to insert the CTID for that page's credential into the URL for the src parameter for that script tag.
    • You may also implement a javascript function to be called when the data is loaded (see above). This will not affect whether crawlers detect the data, but may be useful for:
      • Detecting that the data has loaded
      • Logging the data
      • Displaying the JSON data, if it is appropriate to do so on your page
      • Performing client-side functions with the data
      • Debugging and testing
  3. Use the Google Structured Data Testing Tool to validate the metadata.
Using a Template-Driven Page

Template-driven websites may be able to simply inject the CTID for the credential into an otherwise pre-formatted script tag that is part of the page's template.

The template for the script tag looks like this:

<script type="text/javascript" src="https://credentialfinder.com/registry/ctdltoeocred/script/[Your CTID]" defer async></script>

If you want to trigger a javascript function on your page when the data is loaded, you can include an onload parameter as shown below. This will pass the CTID, the data that was loaded, and a reference to the JSON-LD tag that was injected into your page to the function you call:

<script type="text/javascript" src="https://credentialfinder.com/registry/ctdltoeocred/script/[Your CTID]?onload=[Your Custom Function]" defer async></script>

For Example:

<script type="text/javascript" src="https://credentialfinder.com/registry/ctdltoeocred/script/ce-5d322af3-3aeb-4823-b9ac-758656a17b51?onload=credentialLoaded" defer async></script>

Option Two: Embedding JSON-LD Server-Side

Many template/data-driven websites and some Content Management Systems offer access to programming languages to add functionality to web pages. If your site can be programmed to make HTTP requests and embed extra data as part of the on-demand page building process, you also have the option to fetch the EOCred data server-side and embed it directly into the page - no javascript needed.

  1. Obtain the CTID for the credential, usually from a database
  2. Make an HTTP request to the URL below, using that CTID
  3. The request will return the raw JSON-LD EOCred data. Insert this into a <script type="application/ld+json"></script> tag on your page.

Retrieve raw EOCred data via this URL template:

https://credentialfinder.com/registry/ctdltoeocred/json/[Your CTID]

For Example:

https://credentialfinder.com/registry/ctdltoeocred/json/ce-5d322af3-3aeb-4823-b9ac-758656a17b51

Embedded JSON-LD

The end result of the embedding process will be totally invisible to you and your users - but search engines will see it. If you examine the code of your page after embedding the data, it would look like this:

Sample HTML page:

<!DOCTYPE html> <html> <head> <title>Excellent Credential</title> <meta charset="utf-8" /> <script type="application/ld+json"> { "@context": "http://credreg.net/ctdl/schema/context/json", "@id": "https://credentialengineregistry.org/graph/ce-e22e4f54-7553-4b1b-9d56-7abc598a316e" "@graph": [ { "@type": "schema:EducationalOccupationalCredential", "schema:credentialCategory": { "@type": "schema:DefinedTerm", "schema:name": "Certification", "schema:url": "http//credreg.net/ctdl/terms/Certification" }, "schema:name": "Excellent Certification", "schema:description": "This credential serves to...", "ceterms:ctid": "ce-"e22e4f54-7553-4b1b-9d56-7abc598a316e", "schema:sameAs": "https://credentialengineregistry.org/resources/ce-e22e4f54-7553-4b1b-9d56-7abc598a316e" } ] } </script> </head> <body> <h1>Excellent Credential</h1> <p>This credential serves to...</p> </body> </html>

Testing and Tools

There are a number of tools to help develop, debug, and test your data throughout the process of embedding your data.

CTDL to EOCred Conversion Widget

The tool below provides an easy way to see exactly what any credential published to the Registry looks like when represented using the EOCred/CTDL properties. It is included here for debugging purposes, or for simple curiosity. To use it, paste a credential's CTID into the box below and click "Convert".

Credential CTID

Source Data

The original source data for the CTID you provided will appear below.

Converted Data

The data below has been converted from CTDL to EOCred. This will combine the converted properties together with the original source data's properties, and remove the source data's properties where they have been translated to EOCred. The result is a document that hybridizes EOCred and CTDL.

EOCred Embedding Tester

The Embedding Tester is a simple tool that allows you to see what your data should look like if it is correctly embedded in your page. Simply add a CTID.

Google Structured Data Testing Tool

You can ensure that crawlers can read your data with Google Structured Data Testing Tool. This tool will show you exactly what Google's search crawler sees when it crawls your webpage, and is an excellent way to ensure your data is correct.

Keep the following in mind while testing your data with this tool:

  • The validator will show that it has successfully detected the classes and properties from the schema.org namespace (e.g., schema:name)
  • Click on each object listed by the validator to see the values of the properties for that object.
  • Due to the specialized nature of this tool, you can expect to see the following errors. This is normal, and should not affect discovery by search engines.
    • The type schema:EducationalOccupationalCredential is not a known type to Google. - This is because EOCred is still pending in schema.org, so Google's system does not recognize the type. Properties within the object should still be recognized.
    • Unspecified Type for language maps. - The tool does not read remote @context files, so it does not detect that these properties have been defined with "@container": "@language".
    • There was an invalid type in your JSON-LD. - This is due to the tool expecting only schema.org types.
    • Non-schema.org classes and properties are not recognized. - This is because the tool is not designed to recognize classes or properties that do not come from the schema.org namespace. Notice, however, that it can still read the values of these properties.
  • If the tool does not detect your data, or if you see errors unlike those above, contact the Credential Engine Technical Team. We will assist in troubleshooting the problem.

Other Testing Tools

Once your JSON-LD is embedded in your web page, you should test it to ensure that search engine crawlers detect it properly. Here are some tools to help you do so:

JSON-LD Playground
You can test the formatting of your JSON-LD with the official JSON-LD Playground tool. This will provide details about any issues with your data.
Yandex Testing Tool
Provides a validation tool similar to the Google Structured Data Testing Tool, powered by the Yandex search system.
RDF Translator
This is a multi-format tool for structured markup. It provides translations between data formats ranging from RDF/XML to RDFa or Microdata. This service allows for conversions triggered either by URI or by direct text input. It also includes a REST API for developers.
W3C RDF Validation Service
This service doesn't validate JSON-LD, but can validate RDF XML produced by running JSON-LD through the RDF Translator linked above. It can also provide a helpful visual of the data.
Easy RDF Converter
A tool for converting RDF data between multiple formats (JSON, XML, etc.).
Additional Tools
You may find additional useful tools here.
Validation Tools Comparison
Provides a listing, comparison, and review of several validation tools, from an RDF perspective.

Mapping Details

The following information describes how CTDL Credential properties are mapped to EOCred properties.

This table covers properties at the top level of the credential. Many properties here involve other objects with mappings described in subsequent tables. See this table and the tables below for a complete overview of the mapping.

CTDL Credential PropertyRegistry RequirementMapping Descriptionschema.org EOCred Property
@id Required Directly Copied @id
@type Required Mapped to schema:DefinedTerm schema:credentialCategory
ceterms:name Required Extracted from Language Map schema:name
ceterms:description Required Extracted from Language Map schema:description
ceterms:alternateName Optional Extracted from Language Map schema:alternateName
ceterms:keyword Extracted from Language Map schema:keywords
ceterms:subjectWebpage Required Directly Copied schema:url
ceterms:subjectWebpage Required Directly Copied schema:mainEntityOfPage
ceterms:inLanguage Required Directly Copied schema:inLanguage
ceterms:image Optional Directly Copied schema:image
ceterms:ownedBy Required Mapped via Lookup to the schema:Organization class schema:author
ceterms:offeredBy Required Mapped via Lookup to the schema:Organization class schema:provider
ceterms:copyrightHolder Optional Mapped via Lookup to the schema:Organization class schema:copyrightHolder
ceterms:renewalFrequency Optional Directly Copied schema:validFor
ceterms:dateEffective Directly Copied schema:datePublished
ceterms:ctid Required Mapped to schema:PropertyValue schema:identifier
ceterms:codedNotation Optional Mapped to schema:PropertyValue schema:identifier
ceterms:hasPart Mapped via Lookup to the schema:EducationalOccupationalCredential class schema:hasPart
ceterms:isPartOf Mapped via Lookup to the schema:EducationalOccupationalCredential class schema:isPartOf
ceterms:exactAlignment Optional Mapped via Lookup to the schema:EducationalOccupationalCredential class schema:sameAs
ceterms:subject Optional Mapped to schema:DefinedTerm schema:about
ceterms:audienceLevelType Mapped to schema:DefinedTerm schema:educationalLevel
ceterms:audienceType Optional Mapped to schema:DefinedTerm schema:audience
ceterms:recognizedBy Mapped via Lookup to the schema:Organization class schema:recognizedBy
ceterms:approvedBy Mapped via Lookup to the schema:Organization class schema:recognizedBy
ceterms:accreditedBy Mapped via Lookup to the schema:Organization class schema:recognizedBy
ceterms:administrationProcess Optional Directly Copied schema:publishingPrinciples
ceterms:developmentProcess Optional Directly Copied schema:publishingPrinciples
ceterms:maintenanceProcess Optional Directly Copied schema:publishingPrinciples
ceterms:reviewProcess Optional Directly Copied schema:publishingPrinciples
ceterms:estimatedCost Mapped to schema:Offer schema:offers
ceterms:jurisdiction Mapped to schema:AdministrativeArea schema:validIn
ceterms:requires Mapped to schema:DefinedTerm schema:competencyRequired

Mapping: Alternative Identifier

The ceterms:alternativeIdentifier for a CTDL credential is transformed into a schema:PropertyValue in order to enable capturing the data contained in the ceterms:IdentifierValue class.

CTDL Identifier Value PropertyRegistry RequirementMapping Descriptionschema.org Property Value Property
ceterms:name Optional Extracted from Language Map schema:name
ceterms:description Optional Extracted from Language Map schema:description
ceterms:identifierValueCode Optional Directly Copied schema:value
ceterms:identifierValueCode Optional Directly Copied schema:identifier
ceterms:identifierValueCode Optional Directly Copied schema:termCode
ceterms:identifierType Optional Directly Copied schema:propertyID

The properties for the resulting schema:PropertyValue object look like this:

{ "@type": "schema:PropertyValue", "schema:name": "Custom Identifier", "schema:description": "This is the description for my custom identifier", "schema:value": "123abc", "schema:identifier": "123abc", "schema:termCode": "123abc", "schema:propertyID": "https://my-custom-identifier.com/identifier/123abc", }

Mapping: Coded Notation

The ceterms:codedNotation value for a CTDL credential is transformed into a schema:PropertyValue .

The properties for the resulting schema:PropertyValue object look like this:

{ "@type": "schema:PropertyValue", "schema:name": "Coded Notation", "schema:value": "1.B3.9.5-7a", "schema:identifier": "1.B3.9.5-7a", "schema:termCode": "1.B3.9.5-7a", "schema:propertyID": "https://purl.org/ctdl/terms/codedNotation" }

Mapping: Controlled Values

Several properties in CTDL leverage controlled values from other sources to convey their values. These include competency frameworks, concept schemes, and other structured data sources. These properties convey their values in CTDL via ceterms:CredentialAlignmentObject objects, which are translated to schema:DefinedTerm objects.

CTDL Credential Alignment Object PropertyRegistry RequirementMapping Descriptionschema.org Defined Term Property
ceterms:targetNodeName Optional Extracted from Language Map schema:name
ceterms:targetNodeDescription Extracted from Language Map schema:description
ceterms:targetNode Directly Copied schema:url

The properties for the resulting schema:DefinedTerm object look like this:

{ "@type": "schema:DefinedTerm", "schema:name": "Associates Degree Level", "schema:url": "https://purl.org/ctdl/vocabs/audLevel/AssociatesDegreeLevel", }

Note that the required competencies for a credential are retrieved by examining all of the ceterms:ConditionProfile objects for that credential's ceterms:requires property, and looking for values in the ceterms:ConditionProfile's ceterms:targetCompetency property.

An example competency reference translated from a ceterms:CredentialAlignmentObject to a schema:DefinedTerm would look like this:

{ "@type": "schema:DefinedTerm", "schema:description": "Can tie shoes effectively", "schema:url": "https://credentialengineregistry.org/resources/ce-460b10db-f8d7-4e9b-a6e0-d98227fa0d77", }

Mapping: Cost Profile

The ceterms:estimatedCost property for a CTDL credential is transformed into a schema:Offer in order to enable capturing the data contained in the ceterms:CostProfile class.

CTDL Cost Profile PropertyRegistry RequirementMapping Descriptionschema.org Offer Property
ceterms:name Optional Extracted from Language Map schema:name
ceterms:description Required Extracted from Language Map schema:description
ceterms:paymentPattern Extracted from Language Map schema:disambiguatingDescription
ceterms:price Directly Copied schema:price
ceterms:currency Directly Copied schema:priceCurrency
ceterms:costDetails Required Directly Copied schema:url
ceterms:startDate Optional Directly Copied schema:validFrom
ceterms:endDate Optional Directly Copied schema:validThrough

The properties for the resulting schema:Offer object look like this:

{ "@type": "schema:Offer", "schema:name": "Costs for Certificate", "schema:description": "The costs for the certificate are defined here", "schema:disambiguatingDescription": "Every month, on the fourth", "schema:price": 500, "schema:priceCurrency": "USD", "schema:validFrom": "2019-1-1", "schema:validThrough": "2019-12-31", "schema:url": "https://example.com/costprofile/details/abc12345", }

Mapping: Credential Type

The @type value for a CTDL credential is transformed into a schema:PropertyValue in order to enable it to reference the appropriate type in the CTDL schema. This is then used as the value for the EOCred's schema:credentialCategory property.

The properties for the resulting schema:PropertyValue object look like this:

{ "@type": "schema:PropertyValue", "schema:name": "Bachelor Degree", "schema:propertyID": "https://purl.org/ctdl/terms/BachelorDegree", "schema:termCode": "ceterms:BachelorDegree", }

Mapping: CTID

The schema:ctid value for a CTDL credential is transformed into a schema:PropertyValue in order to enable it to be identified as a CTID. Note that the value of the CTID is used as the value of both the schema:value and schema:identifier properties within this object. Other properties in this object are used to ensure this identifier is unquestionably represented as a CTID.

The properties for the resulting schema:PropertyValue object look like this:

{ "@type": "schema:PropertyValue", "schema:name": "Credential Transparency Identifier", "schema:alternateName": "CTID", "schema:value": "ce-3366b49b-93b9-450d-bcb6-fd45913357c3", "schema:identifier": "ce-3366b49b-93b9-450d-bcb6-fd45913357c3", "schema:propertyID": "https://purl.org/ctdl/terms/ctid" }

Mapping: Data Lookup

Data that references external resources (typically organizations, such as the organization that owns/offers a credential) will be looked up in the registry and a summary of that object's data will be included in the output's @graph array during the translation process. This data typically includes:

CTDL Credential PropertyRegistry RequirementMapping Descriptionschema.org EOCred Property
@type Required Mapped to schema:DefinedTerm schema:credentialCategory
@id Required Directly Copied schema:sameAs
ceterms:name Optional Extracted from Language Map schema:name
ceterms:description Optional Extracted from Language Map schema:description
ceterms:subjectWebpage Optional Directly Copied schema:url
ceterms:ctid Optional Mapped to schema:PropertyValue schema:identifier

Mapping: Jurisdiction

The schema:jurisdiction for a CTDL credential is transformed into a schema:AdministrativeArea in order to describe where a credential is useful and/or valid.

In CTDL, the value of a ceterms:jurisdiction is ceterms:JurisdictionProfile , which contains a ceterms:mainJurisdiction property, the value of which is a is ceterms:Place . This data is translated to a schema:AdministrativeArea. The ceterms:Place class also embodies sets of properties that are translated to the schema:PostalAddress and schema:GeoCoordinates classes. Instances of these classes are created as needed during the translation process and used as values for the schema:address and schema:geo properties, respectively, of schema:AdministrativeArea.

CTDL Place PropertyRegistry RequirementMapping Descriptionschema.org Administrative Area Property
ceterms:name Optional Extracted from Language Map schema:name
ceterms:description Optional Extracted from Language Map schema:description
Address PropertiesSee BelowMapped to schema:PostalAddress schema:address
Geocoordinates PropertiesSee BelowMapped to schema:GeoCoordinates schema:geo
CTDL Place PropertyRegistry RequirementMapping Descriptionschema.org Postal Address Property
ceterms:streetAddress Optional Directly Copied schema:streetAddress
ceterms:addressLocality Optional Directly Copied schema:addressLocality
ceterms:addressRegion Optional Directly Copied schema:addressRegion
ceterms:postalCode Optional Directly Copied schema:postalCode
ceterms:postOfficeBoxNumber Optional Directly Copied schema:postOfficeBoxNumber
ceterms:addressCountry Optional Directly Copied schema:addressCountry
CTDL Place PropertyRegistry RequirementMapping Descriptionschema.org Geo Coordinates Property
ceterms:geoURI Optional Directly Copied schema:url
ceterms:latitude Optional Directly Copied schema:latitude
ceterms:longitude Optional Directly Copied schema:longitude

The properties for the resulting schema:AdministrativeArea object look like this:

{ "@type": "schema:AdministrativeArea", "schema:name": "Area Name", "schema:description": "This is the description for a given area.", "schema:address": { "@type": "schema:PostalAddress", "schema:streetAddress": "ABC 123 Street", "schema:addressLocality": "Some City", "schema:addressRegion": "Some State", "schema:postalCode": 12345, "schema:addressCountry": "USA" }, "schema:geo": { "@type": "schema:GeoCoordinates", "schema:url": "http://www.geonames.org/4896861", "schema:latitude": "40.00032", "schema:longitude": "-89.25037" } }

Mapping: Language Maps

Any time a CTDL property's data is embodied in a JSON-LD language map (e.g. ceterms:name or cterms:keyword), the mapping process will, by default, attempt to extract the first english string (via en, en-us, etc.) and use its value(s) in the resulting EOCred data.

For example:

{ "ceterms:name": { "en": "My data", "fr": "mes données" } }

becomes:

{ "schema:name": "My data" }

If no english string is found, the first value in the language map is used:

{ "ceterms:name": { "fr": "mes données", "ru": "мои данные" } }

becomes:

{ "schema:name": "mes données" }