Embedding CTDL in Websites

Last Updated on 5/10/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

The best and 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

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.

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

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 Publisher and downloading your published credential data from your organization's detail page.

Once you have the CTIDs for your credentials, you can:

  • Retrieve the CTDL credential data exactly as it appears in the Registry via the /graph/ URI for that CTID
    • Example: https://credentialengineregistry.org/graph/ce-72fd65b1-ddbe-4457-a328-069ee051620a
  • Retrieve the hybridized CTDL/EOCred data via an in-development API (to be announced; see this conversion widget for a preview)
  • Generate an embeddable script tag that will automatically inject the EOCred data into your webpage (see the Embed Script section below)

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.

Instructions for Embedding CTDL/EOCred Data

Adding your CTDL/EOCred data to the Credential Registry is easy. If you publish your data to the Credential Registry, you can take advantage of the tools Credential Engine offers to automate this process.

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:

  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

The template for the script tag looks like this:

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

For Example:

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

Once your script tag is formatted, just add it to the webpage for that credential. If you download the spreadsheet described above, you can simply copy and paste the script tag to the source code for the appropriate page for that credential.

Ideally, the script tag will be added to the the <head> for that webpage, but it will also work in the <body>. Now, when your webpage loads, you should see the process outlined above happen automatically.

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>

Step by Step Instructions

Follow these instructions to add the script 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 or Credential Publisher as described above.
    • The spreadsheet contains the following fields:
  2. Copy and paste the script into the source code for your 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 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.
    • It is recommended to 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.
    1. The validator will show that it has successfully detected the classes and properties from the schema.org namespace (e.g. schema:name)
    2. Click on each object listed by the validator to see the values of the properties for that object.
    3. 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".
      • 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.
      • There was an invalid type in your JSON-LD. - This is due to the tool expecting only schema.org types.
    4. 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.

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. This tool is based on an in-development API, and its results may change. 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".

This tool provides two distinct "flavors" of output:

  • Converted Properties Only (EOCred Alone): This returns only those properties from the CTDL data that map to the EOCred schema (your cake)
  • Merge and Replace (EOCred + CTDL): This returns all of the original data, but with every applicable property swapped out for its EOCred equivalent (your cake and ice cream)
Credential CTID

Source Data

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

Converted Data

Converted Properties Only

The data below has been converted from CTDL to EOCred. The "Converted Properties Only" option will display only those properties from the source document that could be converted directly to terms used by EOCred and schema.org.

Merge and Replace

The data below has been converted from CTDL to EOCred. The "Merge and Replace" option 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.

Testing Your JSON-LD

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.
Google Structured Data Testing Tool
You can ensure that crawlers can read your data with Google's 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. Note: The crawler may not recognize CTDL terms at this time (including the EducationalOccupationalCredential type itself), but an ongoing effort with schema.org is underway to improve this.
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:

CTDL Credential PropertyMapping Descriptionschema.org EOCred Property
@id Directly Copied @id
@type Mapped to schema:DefinedTerm schema:credentialCategory
ceterms:name Extracted from Language Map schema:name
ceterms:description Extracted from Language Map schema:description
ceterms:alternateName Extracted from Language Map schema:alternateName
ceterms:keyword Extracted from Language Map schema:keywords
ceterms:subjectWebpage Directly Copied schema:url
ceterms:subjectWebpage Directly Copied schema:mainEntityOfPage
ceterms:inLanguage Directly Copied schema:inlanguage
ceterms:image Directly Copied schema:image
ceterms:ownedBy Mapped via Lookup to the schema:Organization class schema:author
ceterms:offeredBy Mapped via Lookup to the schema:Organization class schema:provider
ceterms:copyrightHolder Mapped via Lookup to the schema:Organization class schema:copyrightHolder
ceterms:renewalFrequency Directly Copied schema:validFor
ceterms:dateEffective Directly Copied schema:datePublished
ceterms:ctid Mapped to schema:PropertyValue schema:identifier
ceterms:codedNotation Mapped to schema:PropertyValue schema:identifier
ceterms:alternativeIdentifier 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:exactMatch Mapped via Lookup to the schema:EducationalOccupationalCredential class schema:sameAs
ceterms:subject Mapped to schema:DefinedTerm schema:about
ceterms:audienceLevelType Mapped to schema:DefinedTerm schema:educationalLevel
ceterms:audienceType 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 Directly Copied schema:publishingPrinciples
ceterms:developmentProcess Directly Copied schema:publishingPrinciples
ceterms:maintenanceProcess Directly Copied schema:publishingPrinciples
ceterms:reviewProcess 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 PropertyMapping Descriptionschema.org Property Value Property
ceterms:name Extracted from Language Map schema:name
ceterms:description Extracted from Language Map schema:description
ceterms:identifierValueCode Directly Copied schema:value
ceterms:identifierValueCode Directly Copied schema:identifier
ceterms:identifierValueCode Directly Copied schema:termCode
ceterms:identifierType 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 PropertyMapping Descriptionschema.org Defined Term Property
ceterms:targetNodeName 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 PropertyMapping Descriptionschema.org Offer Property
ceterms:name Extracted from Language Map schema:name
ceterms:description 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 Directly Copied schema:url
ceterms:startDate Directly Copied schema:validFrom
ceterms:endDate 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 PropertyMapping Descriptionschema.org EOCred Property
@type Mapped to schema:DefinedTerm schema:credentialCategory
@id Directly Copied schema:sameAs
ceterms:name Extracted from Language Map schema:name
ceterms:description Extracted from Language Map schema:description
ceterms:subjectWebpage Directly Copied schema:url
ceterms:ctid 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 PropertyMapping Descriptionschema.org Administrative Area Property
ceterms:name Extracted from Language Map schema:name
ceterms:description Extracted from Language Map schema:description
Address PropertiesMapped to schema:PostalAddress schema:address
Geocoordinates PropertiesMapped to schema:GeoCoordinates schema:geo
CTDL Place PropertyMapping Descriptionschema.org Postal Address Property
ceterms:streetAddress Directly Copied schema:streetAddress
ceterms:addressLocality Directly Copied schema:addressLocality
ceterms:addressRegion Directly Copied schema:addressRegion
ceterms:postalCode Directly Copied schema:postalCode
ceterms:postOfficeBoxNumber Directly Copied schema:postOfficeBoxNumber
ceterms:addressCountry Directly Copied schema:addressCountry
CTDL Place PropertyMapping Descriptionschema.org Geo Coordinates Property
ceterms:geoURI Directly Copied schema:url
ceterms:latitude Directly Copied schema:latitude
ceterms:longitude 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" }