Credential Transparency Description Language (CTDL)
- Phil Barker, PJJK Limited & Cetis LLP
- Jeanne Kitchens, Credential Engine
- Stuart Sutton, Sutton & Associates Consulting
All terms (properties & classes) used in metadata descriptions that conform to the Credential Transparency Description Language (CTDL) must be assigned a unique URI. The term URIs that are assigned and managed by Credential Engine (CE) are grouped into collections known as CTDL namespaces. This document describes how term URIs are allocated by CE and the policies associated with CTDL namespaces.
This document uses of the following terminology:
- A property (RDF), class (RDFS), concept scheme (SKOS), or concept (SKOS).
- A Uniform Resource Identifier (URI) or Internationalized Resource Identifier (IRI).
- CTDL term
- A term that is declared and maintained by CE.
- term URI
- The URI that identifies a term.
- CTDL term URI
- The URI for a term that is declared and managed by CE.
- term name
- A unique lexical token assigned to a term. For all CTDL terms, the term name is appended to a CTDL namespace URI to create the CTDL term URI.
- term label
- A human-readable label assigned to a term that may or may not be lexically identical to the term name.
- CTDL namespace
- A collection of CTDL term URIs where each term is assigned a URI that starts with the same 'base URI'. The 'base URI' is known as the CTDL namespace URI. (Note that a CTDL namespace is not the same as an 'XML namespace').
- CTDL namespace URI
- The URI that identifies a CTDL namespace.
- CTDL term declaration
- A representation of one or more CTDL terms.
Term URIs are grouped into CTDL namespaces in order to ease the assignment of URIs to terms and to streamline their use in particular serializations. Note that the grouping of term URIs into CTDL namespaces is orthogonal to the grouping of terms into sets designed to meet other functional needs, e.g., as various types of vocabularies, particular profiles, or as specific graph shapes or record structures.
The CTDL namespace URI (base URI) for the collection of all CTDL properties, classes and concept schemes is:
The CTDL namespace URI (base URI) for the concept classes in the CTDL concept schemes (controlled vocabularies) are:
https://purl.org/ctdl/vocabs/actionStat/ https://purl.org/ctdl/vocabs/agentSector/ https://purl.org/ctdl/vocabs/array/ https://purl.org/ctdl/vocabs/assessMethod/ https://purl.org/ctdl/vocabs/assessUse/ https://purl.org/ctdl/vocabs/audience/ https://purl.org/ctdl/vocabs/audLevel/ https://purl.org/ctdl/vocabs/claimType/ https://purl.org/ctdl/vocabs/collectionCategory/ https://purl.org/ctdl/vocabs/compare/ https://purl.org/ctdl/vocabs/costType/ https://purl.org/ctdl/vocabs/credentialStat/ https://purl.org/ctdl/vocabs/creditUnit/ https://purl.org/ctdl/vocabs/deliveryType/ https://purl.org/ctdl/vocabs/financialAid/ https://purl.org/ctdl/vocabs/inputType/ https://purl.org/ctdl/vocabs/learnMethod/ https://purl.org/ctdl/vocabs/lifeCycle/ https://purl.org/ctdl/vocabs/logic/ https://purl.org/ctdl/vocabs/orgType/ https://purl.org/ctdl/vocabs/residency/ https://purl.org/ctdl/vocabs/scheduleFrequency/ https://purl.org/ctdl/vocabs/scheduleTiming/ https://purl.org/ctdl/vocabs/score/ https://purl.org/ctdl/vocabs/serviceType/
Some example CTDL term URIs
...is the CTDL term URI for the Industry Type property.
...is the CTDL term URI for the Digital Badge class.
...is the CTDL term URI for the Claim Type concept scheme (vocabulary) class.
...is the CTDL term URI for the Badge Claim concept (vocabulary term) class.
Borrowed Terms in CTDL
Effective 2022-7-18, Credential Engine, where possible, adopts terms from other well known and widely implemented RDF vocabularies. Doing so comes with responsibilities: firstly, to acknowledge where CTDL has benefitted from other people's work; secondly, not to damage the beneficial interoperability that reuse provides. To meet these responsibilities, CTDL uses the hierarchy of approaches provided by RDF for adopting terms from other vocabularies that ranges from "use as-is" through acknowledgement that one term was used as inspiration for another. The improvement in interoperability decreases down the hierarchy as the flexibility afforded increases:
- Use as-is: Use the term with the URI provided by the source vocabulary.
- Responsibilities: Nothing that is defined in the source vocabulary should be changed. Typically this includes, but is not limited to, the values for
rdfs:isDefinedBy. Comments about usage in CTDL descriptions may be added using the
skos:scopeNoteproperty, provided they do not conflict with anything from the source. The wording of these scope notes should make it clear that the comment applies only to use in CTDL (e.g., "In CTDL, this term...").
owl:equivalentProperty, or (for concepts in our vocabularies)
- Responsibilities: Equivalence means that while the definition may be phrased differently, every instance of one is also an instance of the other (the two terms are differently defined but co-extensive). For example, "Human" and "Person" may be defined differently, but in such a way that every "Human" is a "Person" and vice-versa. Any changes should not affect this equivalence (that includes changes that affect inferencing) so the domain and range of such properties should be identical to, or equivalent to, each other.
schema:domainIncludesare not used for inferencing, so their use comes with less responsibility.
rdfs:subPropertyOf, or (for concepts in our vocabularies)
- Responsibilities: Credential Engine should define a new term so that every instance of the subclass, subproperty, or narrow match is also an instance of the related term. For example, "Woman" may be defined to be a
rdfs:subClassOf"Human". Consideration should be given to the domain and range of properties when doing this.
schema:isBasedOnsimply as an acknowledgement that the new term was inspired by the existing term.
- Responsibilities: The main responsibility is to do this when approprate, but Credential Engine should not misattribute terms or define them in some way that misrepresents the stated source for such terms (for example, it would be wrong to say that
dcterms:titlewere the source for a term such as
example:titlewhere the latter term is used to address someone.
CTDL terms Change Policy
Changes to CTDL terms or term declarations will occur from time to time for a variety of reasons. Such changes have varying implications for CTDL term URIs and CTDL namespaces. The following kinds of changes are identified along with examples and associated implications.
In all cases, any changes to CTDL terms or term declarations will result in an update to the versioning information carried in the CTDL term declaration associated with that term.
Minor Editorial Errata
Errors of spelling, punctuation, or other clerical mistakes discovered in CTDL term declarations will be corrected without a comment period, following notification to the CTDL Technical Advisory Committee (TAC), as long as, in the judgment of the CE Technical Team, there are no implications for negative impact on users or applications that rely on those CTDL term declarations. If the CE Technical Team is uncertain as to potential negative impact of such a change, a comment period will be declared on notification of the TAC.
Correction of minor editorial errata will result in no changes to CTDL term URIs.
Semantic changes in CTDL terms
Changes of definitions within a CTDL term declaration will be reflected in the affected CTDL term declaration. If, in the judgment of the CE Technical Team, such changes of meaning are likely to have substantial impact on either machine processing of CTDL terms or the functional semantics of the terms, then these changes will be reflected in a change of URI for the CTDL term or terms in question. The URIs for any new CTDL namespaces resulting from such changes will conform to the CTDL namespace URI patterns defined above.
Addition of CTDL term declarations to existing CTDL namespaces
New CTDL term URIs will occasionally be added to existing CTDL namespaces. Addition of CTDL term URIs to existing CTDL namespaces will not trigger changes in CTDL namespace URIs.
Credential Engine (CE) recognizes that people and applications depend on the persistence of formal documents and machine processable schemas that have been made publicly available. In particular, the stability of CTDL term URIs and CTDL namespace URIs is critical to interoperability over time. Thus, the wide promulgation of this set of URIs dictates that they be maintained to support legacy applications that have adopted them.
A term may be assigned the status of Unstable for a period of time before being changed to Stable. The status of Unstable indicates that aspects of the term may change–including the term's semantics–or that the term may be deleted. The status of Stable triggers all of the prescriptions of this Namespace Policy including persistence.
- The term is in a development/comment period; changes are still possible.
- The term is liable to change at some point in the future, or may be deleted entirely. Use with caution.
- The term is relatively stable, and its documentation and meaning are not expected to change substantially.
- This term is marked as archaic. It is not considered typical of current best practice and therefore alternative expressions may be preferable.
New CTDL terms have a lifecycle that begins with a Pending status defined above. Pending terms are in development and not formally identified as CTDL terms and therefore are subject to change or may be removed. Terms advance from a Pending status after a defined comment period and will then have a status of either Stable or Unstable. Unstable terms could be substantially changed or deleted. Stable terms may be updated but not substantially and as these terms reach the end of their lifecycle can become Deprecated.
The Credential Transparency Description Language (CTDL) Namespace Policy is adapted from the Namespace Policy for the Dublin Core Metadata Initiative (DCMI).