Embedding CTDL in Websites
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:
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.
Follow the steps on the Embedding CTDL Step by Step page to embed your script.
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".
Converted Data
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
@contextfiles, 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.
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 Property | Registry Requirement | Mapping Description | schema.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 Property | Registry Requirement | Mapping Description | schema.org Defined Term Property |
|---|---|---|---|
| ceterms:targetNodeName | Optional | Extracted from Language Map | schema:name |
| ceterms:targetNodeDescription | Recommended Benchmark |
Extracted from Language Map | schema:description |
| ceterms:targetNode | Recommended Benchmark |
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 Property | Registry Requirement | Mapping Description | schema.org Offer Property |
|---|---|---|---|
| ceterms:name | Optional | Extracted from Language Map | schema:name |
| ceterms:description | Recommended Benchmark |
Extracted from Language Map | schema:description |
| ceterms:paymentPattern | Recommended Benchmark |
Extracted from Language Map | schema:disambiguatingDescription |
| ceterms:price | Recommended Benchmark |
Directly Copied | schema:price |
| ceterms:currency | Recommended Benchmark |
Directly Copied | schema:priceCurrency |
| ceterms:costDetails | Recommended Benchmark |
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 Property | Registry Requirement | Mapping Description | schema.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 Property | Registry Requirement | Mapping Description | schema.org Administrative Area Property |
|---|---|---|---|
| ceterms:name | Optional | Extracted from Language Map | schema:name |
| ceterms:description | Optional | Extracted from Language Map | schema:description |
| Address Properties | See Below | Mapped to schema:PostalAddress | schema:address |
| Geocoordinates Properties | See Below | Mapped to schema:GeoCoordinates | schema:geo |
| CTDL Place Property | Registry Requirement | Mapping Description | schema.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 Property | Registry Requirement | Mapping Description | schema.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" }
