Rich Skill Descriptor Standards Implementation Recommendations

Introduction

In order to create an ecosystem of recognition around skills, where Achievements, Pathways, and Learner Records make machine-readable references to skills and allow systems to take action based on the skills learners hold, it is important for implementers to use skills in common ways. RSDs build on CTDL-ASN to enable skill authors to publish definitions that can be referenced from digital credentials (including those that appear in learner records), pathways, and job profiles. Partners in an interoperable skills ecosystem may use CTDL/CTDL-ASN and/or other vocabularies and web standards to present skills descriptors and related concepts. This document provides the Open Skills Network's technical guidance on approaches for publishing and making use of this data, taking best advantage of available data standards.

Below are examples of use cases that sytems working with skills may implement, with recipes for how OSN members recommend those sytems might implement those use cases in a harmonized interoperable manner. Examples and usage notes provide guidance for how these concepts should be understood and used.

Publish a Rich Skill Descriptor

As an educational institution, I would like to publish a skill that is taught, assessed, and recognized by the organization in machine-readable interoperable format so that it can be referenced in other resources by the organization and employers

The concept of a single skill or competency, expressed with rich metadata and alignment, is the foundation of a skills vocabulary. Organizations or individuals in different roles in the skills ecosystem may find it useful to publish a skill definition. That includes employers, individual educators, educational institutions, industry consortia or professional associations, or collaborations between these different roles.

Some of these publishers may at times describe the concept of a skill using different terminology, such as competency, learning outcome or standard, but what is shared between all of these models is the possibility for each skill to be associated with a canonical URL where it is made available and the ability to retrieve descriptive metadata that expresses the full meaning of the skill definition.

Recipe: Publish a Rich Skill Descriptor with CTDL-ASN/CTDL

CTDL-ASN and CTDL are published by Credential Engine. These vocabularies provide extensive attributes with which to describe credentials, competencies or skills, organizations and other related concepts.

RSD Property	Field Name	Data Type	Description	Term IRI
id	ID	URI	Canonical URL that uniquely identifies the skill, from which more information may be retrieved.	`@id`
skillName	Skill Name	String	Short name or label for the skill.	ceasn:competencyLabel
skillStatement	Skill Statement	String[SkillStatement]	Skills description written in standard syntax.	ceasn:competencyText
keywords	Keywords	Array[String]	List of keyword strings to enhance searchability.	ceterms:keyword
category	Category	String	A category in which this RSD is filed, in the local vocabulary defined by the issuer	ceasn:competencyCategory
author	Author	String	A person or organization chiefly responsible for the intellectual or artistic content of this skill	ceasn:author
creator	Creator	URI	A person or organization primarily responsible for making this resource. This is the canonical identifier of the source of the skill.	ceasn:creator
alignments	Alignments	Array[String:URI]	indicates alignment or overlap of this RSD to one or more underlying standards, skills, or competencies identified in other frameworks or data sources (i.e.,Emsi; Burning Glass; LinkedIn; Workday), each of which is uniquely identified by a URI. Each entry may be just the URI or may contain descriptive metadata about the alignment target.	ceasn:majorAlignment *
certifications	Certifications	Array[Credential]	Field for associating external certifications to RSDs	ceasn:alignFrom
occupations	Occuption Data Categories	Array[String:JobCode]	indicates skill alignment to releveant job roles/occupations aligned to an external categorization like BLS SOC or O*NET	ceterms:occupationType
employers	Employers	Array [Employment Outcome Profile]	indicates support for a skill by specific employers who employ people who hold the skill	ceterms:employmentOutcome
ctid	Credential Transparency Identifier	Array[String]	Unique Credential Transparency Identifier assigned by the creator perhaps through publication to the Credential Engine Registry. Uniqueness can only be guaranteed for entities submitted to the Credential Engine Registry.	ceterms:ctid
license	License	URI	A legal document giving official permission to do something with this resource.	ceasn:license
derivedFrom	Derived From	URI or RSD	An indicator that the present RSD is a derivative work of another RSD.	ceasn:derivedFrom

Available alignment types include majorAlignment, broadAlignment, exactAlignment, minorAlignment, narrowAlignment, and prerequisiteAlignment. The most simple or default recommendation is majorAlignment, which implies a close but not exact match.

Skill Statement

A skill statement is a string that expresses information about who the skill applies to, the nature of the skill itself, and the context in which it is applied, together, e.g.: "{Subject} {Predicate} {Context}". Consistent formatting assists interoperability of RSDs across organizations and the development of common usage of RSDs valued in common.

   The learner saves copies of documents to their local machine.

Component	Description
subject	Who this skill applies to, e.g "the learner"
predicate	The part of the statement that shows the action, knowledge, or ability at the core of the skill, e.g. "saves copies"
context	Supporting descriptive language to clarify the context in which the skill applies, e.g. "to their local machine"

Example RSD

   {
    "@context": "https://rsd.openskillsnetwork.org/context-v1.json",
    "id": "https://osmt.example.com/skills/9cd84455-2086-4f41-bcac-6d518beeb6ac",
    "type": "RichSkillDescriptor",
    "author": "https://osmt.example.com/organization",
    "skillName": "Document Saving",
    "skillStatement": "The learner saves copies of documents to their local machine.",
    "alignments": [{"id": "https://skillsource.example.com/base-skills/simple-compuhacking", "name": "Simple Compuhacking"}],
    "employers": [{"name": "Acme, Inc."}],
    "keywords": ["documents", "file operations", "computer basics"],
    "category": "Productivity Software",
    "certifications": [{"id": "https://credentials.example.com/supersaver", "name": "DocumentAlliance SuperSaver"}],
    "occupations": [{"codedNotation": "13-2080", "targetNodeName": "Tax Examiners, Collectors and Preparers, and Revenue Agents"}],
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "derivedFrom": {
      "id": "https://anotherosmt.example.com/skills/ee5dc142-ad25-4153-ab7f-2960e3e07639",
      "author": "https://anotherosmt.example.com/organization",
      "license": "https://creativecommons.org/licenses/by/4.0/"
    }
   }

Recipe: Publish a Rich Skill Descriptor with CASE-LD

CASE is a specification published by IMS Global that enables organizations to describe a competency or skill framework. The "CASE-LD" JSON-LD binding for the CASE service definition enables CASE data to be published as JSON-LD for semantic web needs without any significant modification to the JSON expressed by the various endpoints.

To publish an RSD with CASE-LD, return the data described by the CASE-LD CFItem endpoint from the RSD's canonical URL. To express information about a framework in which a skill appears, you may also implement the CFDocument endpoint to express authorship information across one or more RSDs. Terms below are defined in the CASE JSON-LD context.

If the implementer is also implemnting the CASE 1.0 REST API, the canonical URL of the RSD should be the value of the url property in the CFItem objects expressed in those REST endpoints, in order to inform REST API clients of the canonical URLs.

RSD Property	Field Name	Data Type	Description	Term IRI
id	ID	URI	Canonical URL that uniquely identifies the skill, from which more information may be retrieved.	`@id`
identifier	Code	String	An identifying code, local to the RSD's publisher for this item.	`case:identifier`
lastChangeDateTime	Code	String	A timestamp in ISO-8601 format, fully qualified with time zone indicator of the last point in time a change was reflected in this published object.	`case:lastChangeDateTime`
CFDocumentURI	Framework	LinkURI	A link back to the Framework/Collection object, which describes the authorship of this RSD.	`case:CFDocumentURI`
educationLevel	Education Level	Array of Strings	A list of education levels like `"03"` that are the level at which this RSD is expressed.	`case:educationLevel`
fullStatement	Code	String	The full skill statement, expressing a learner's capability, knowledge, and/or experience.	`case:fullStatement`
abbreviatedStatement	Code	String	A short label for the skill.	`case:abbreviatedStatement`
language	Language	String (Language Code)	A language identifier code such as `en` or `es-mx` describing the language in which the RSD is published.	`case:abbreviatedStatement`
licenseURI	License	LinkURI	A link to a legal document controlling permission to do something with the CFItem.	`case:licenseURI`
associationSet	Associations (Alignments)	Array of AssociationSets	Associations (alignments) of this RSD to other entities	`case:associationSet`

LinkURI Properties

A LinkURI object is a CASE-LD concept that expresses a relationship between the present document and another document.

LinkURI Property	Field Name	Data Type	Description	Term IRI
type	type	`LinkURI`	The exact string `LinkURI`, expressing that this link is a LinkURI	`@type`
targetId	Target ID	URI	URI of the object that is the target of this link, such as a CFDocument that is the target of a CFDocumentURI link from a CFItem.	`case:targetId`
identifier	Code	String	An identifying code, local to the RSD's publisher for this item.	`case:identifier`
title	Title	String	The name of the linked entity.	`case:title`

AssociationLink Properties

A LinkURI object is a CASE-LD concept that expresses a relationship between the present document and another document. One such relationship type might be to reference a work from which the present RSD is derived.

LinkURI Property	Field Name	Data Type	Description	Term IRI
type	type	`AssociationLink`	The exact string `AssociationLink`, expressing that this link is an association/alignment.	`@type`
targetId	Target ID	URI	URI of the object that is the target of this link, such as another CFItem.	`case:targetId`
identifier	Code	String	An identifying code, local to the RSD's publisher for this item.	`case:identifier`
title	Title	String	The name of the linked entity.	`case:title`

Example RSD published using CASE-LD

{
    "@context": "https://purl.imsglobal.org/spec/case/v1p0/context/imscasev1p0_context_v1p0.jsonld",
    "type": "CFItem",
    "id": "https://case.example.com/skills/9cd84455-2086-4f41-bcac-6d518beeb6ac",
    "identifier": "9cd84455-2086-4f41-bcac-6d518beeb6ac",
    "lastChangeDateTime": "2020-01-10T18:40:58+00:00",
    "CFDocumentURI": {
        "type": "LinkURI",
        "title": "IMS CLR Demo Framework",
        "identifier": "17927658-3246-11ea-97fb-0242c0a83003",
        "targetId": "https://case.example.com/skills/framework1"
    },
    "abbreviatedStatement": "Document Saving",
    "fullStatement": "The learner saves copies of documents to their local machine.",
    "conceptKeywords": ["documents", "file operations", "computer basics"],
    "language": "en",
    "licenseURI" : {
        "title" : "Creative Commons Attribution (CC-BY) 4.0",
        "identifier" : "CC-BY 4.0",
        "uri" : "https://creativecommons.org/licenses/by/4.0/"
    },
    "associationSet": [
        {
            "type": "AssociationLink",
            "targetId": "https://skillsource.example.com/base-skills/simple-compuhacking",
            "associationType": "isRelatedTo",
            "title": "Simple Compuhacking"
        }
    ]
}

Publish a Collection

A collection of skills bundles a number of skills together for a particular purpose or presentation.

Recipes:
CTDL-ASN/CTDL

Recipe: Publish a Collection with CTDL-ASN/CTDL

CTDL-ASN and CTDL are published by Credential Engine. These vocabularies provide extensive attributes with which to describe credentials, competencies or skills, organizations and other related concepts. Terms from CTDL appear below with the prefix ceterms and terms from CTDL-ASN appear with the prefix ceasn. This document provides the Open Skills Network's technical guidance on approaches for publishing and making use of this data, taking best advantage of available data standards.

Collection Property	Field Name	Data Type	Description	Term IRI
id	ID	URI	Canonical URL that uniquely identifies the collection, from which more information may be retrieved.	`@id`
name	Name	String	A descriptive name for the collection	`@id`
description	Description	URI	Brief explanation of the scope and purpose of the collection.	ceasn:description
author	Author	URI	A person or organization chiefly responsible for the content of this collection	ceasn:author
skills	Skills	Array[RichSkillDescriptor]	The skills contained within a collection. They are all at the top level with no hierarchy.	ceasn:hasTopChild
license	License	URI	A legal document giving official permission to do something with this resource.	ceasn:license

Example Collection

{
  "@context": "https://rsd.openskillsnetwork.org/context-v1.json",
  "id": "https://osmt.example.com/collections/35b6ff86-2974-4dc6-be17-68fef37c86cd",
  "type": "Collection",
  "name": "Office Productivity Skills",
  "description": "Skills for people who work in offices, generally at desks, on office chairs, often using computers.",
  "author": "https://osmt.example.com/organization",
  "skills": [
    {
      "id": "https://osmt.example.com/skills/9cd84455-2086-4f41-bcac-6d518beeb6ac",
      "type": "RichSkillDescriptor",
      "author": "https://osmt.example.com/organization",
      "skillName": "Document Saving",
      "skillStatement": "The learner saves copies of documents to their local machine.",
      "isMemberOf": "https://osmt.example.com/collections/35b6ff86-2974-4dc6-be17-68fef37c86cd",
      "alignments": [{"id": "https://skillsource.example.com/base-skills/simple-compuhacking", "name": "Simple Compuhacking"}],
      "employers": [{"name": "Acme, Inc."}],
      "keywords": ["documents", "file operations", "computer basics"],
      "category": "Productivity Software",
      "certifications": [{"id": "https://credentials.example.com/supersaver", "name": "DocumentAlliance SuperSaver"}],
      "occupations": [{"codedNotation": "13-2080", "targetNodeName": "Tax Examiners, Collectors and Preparers, and Revenue Agents"}],
      "license": "https://creativecommons.org/licenses/by/4.0/"
    }
  ]
}

Align a Credential to RSDs

As an issuer of credentials that recognize the achievement of skills, I would like to include a reference to one or more RSDs that a credential recognizes in the credential achievement description metadata.

There are many contexts in which alignment is useful. Higher ed institutions would like to describe the skills recognized by a credential they issue. This serves the purpose of communicating to potential earners what skills are taught in curriculum, as well as communicating to the potential employers of learners who gain this credential what skills have been achieved. For most purposes of alignment, the achievement level of a skill is binary, rather than on a sliding scale. That means there is a threshold level of attainment that is required in order to award a credential that recognizes that skill, and this is the same basic level that is referenced in other objects that align to a skill, such as a job position description. There may be more advanced use cases for alignment of skills that indicate an achievement level of the skill that the credential recognizes that will be described separately.

Recipe: Align a Credential to an RSD with Open Badges 2.0

There are multiple approaches in different web standards communities for interoperable, portable, and verifiable digital credentials, but a common pattern is an assertion awarded to an individual who the issuer asserts has achieved a particular learning goal, whether that is a skill, learning objective, assessment, certification, or other criteria.

In the below example, an Open Badges achievement definition is a BadgeClass with criteria that represents the assessment of an underlying RSD, which the credential aligns to. Note that the OB vocabulary terms targetName and targetDescription are used to represent the RSD terms skillName and skillStatement respectively. When processing an example that may contain extra information such as this, the relying party is encouraged to separately fetch the RSD itself from the targetUrl to ensure that a canonical set of metadata is saved, based on the latest expression of the RSD author's intent. This approach may be used within an Open Badges BadgeClass to align to an RSD expressed using any recipe to Publish a Rich Skill Descriptor as long as there is a canonical URL for that RSD where it may be retrieved in machine-readable format. The native Open Badges terms are recommended for best compatibility with systems designed to read that format.

{
  "@context": ["https://w3id.org/openbadges/v2"],
  "id": "https://badges.example.com/badges/document-saving-1",
  "type": "BadgeClass",
  "name": "Document Savvy",
  "description": "A basic skill of working on a computer is managing files. Recipients of this badge can save documents.",
  "criteria": {"narrative": "Pass the document saving performance demonstration assessment."},
  "issuer": "https://osmt.example.com/organization",
  "alignment": [{
     "targetUrl": "https://osmt.example.com/skills/9cd84455-2086-4f41-bcac-6d518beeb6ac",
     "targetName": "Document Saving",
     "targetDescription": "The learner saves copies of documents to their local machine."
   }]
}

Recipe: Align a Credential to an RSD with CTDL/CTDL-ASN

CTDL-ASN has no classes for Credentials, so we fall back to CTDL for that data. These Credentials use CTDL's alignment system to indicate alignment to a RSD expressed as a CTDL-ASN Competency.

 {"TODO": true}

Recognize Achievement of an RSD

As an educational institution, I want to award a defined achievement credential to a single learner. As my organization defined this specific achievement, which is tied to a particular learning experience and/or assessment, my organization is the only one that may recognize that learners have achieved its criteria. Other organizations may recognize the same skill by defining their own credentials that are aligned to it.

Recipe: Recognize Achievement of a Credential Aligned to an RSD with Open Badges 2.0

There are multiple approaches in different web standards communities for interoperable, portable, and verifiable digital credentials, but a common pattern is an assertion awarded to an individual who the issuer asserts has achieved a particular learning goal, whether that is a skill, learning objective, assessment, certification, or other criteria. In the below example, there is an assertion of an Open Badges achievement definition that is a BadgeClass with criteria that represents the assessment of an underlying RSD, which the credential aligns to. Note that the OB vocabulary term targetName is used alongside the canonical RSD term skillName.

{
  "@context": ["https://w3id.org/openbadges/v2", "https://rsd.openskillsnetwork.org/context-v1.json"],
  "recipient": {
    "type": "email",
    "salt": "yUv2eMsVpQ1Y2uIU",
    "hashed": true,
    "identity": "sha256$0fdde2f81fcb3b06e50ca0d53d6bc2f5b576d027ddc7b4200455b99ce42e08c9"
  },
  "id": "https://badges.example.com/assertions/document-saving-1/abc123",
  "badge": {
    "id": "https://badges.example.com/badges/document-saving-1",
    "type": "BadgeClass",
    "name": "Document Savvy",
    "description": "A basic skill of working on a computer is managing files. Recipients of this badge can save documents.",
    "criteria": {
      "narrative": "Pass the document saving performance demonstration assessment."
    },
    "issuer": "https://badges.example.com/organization",
    "alignment": [{
      "targetUrl": "https://osmt.example.com/skills/9cd84455-2086-4f41-bcac-6d518beeb6ac",
      "type": "RichSkillDescriptor",
      "author": "https://osmt.example.com/organization",
      "skillName": "Document Saving",
      "targetName": "Document Saving",
      "skillStatement": "The learner saves copies of documents to their local machine.",
      "alignments": ["https://skillsource.example.com/base-skills/simple-compuhacking"],
      "keywords": ["documents", "file operations", "computer basics"],
      "category": "Productivity Software",
      "occupations": ["13-0000", "13-2000", "13-2010", "13-2030", "13-2040", "13-2060", "13-2080"]
    }]
  },
  "verification": {
    "type": "hosted"
  }
}

Recipe: Recognize Achievement of a Credential Aligned to an RSD with Open Badges 3.0

In OB 3.0, the skill can be represented more directly in the model. A Skill Assertion credential is just like a basic OpenBadgeCredential in how an Achievement is included, except that it makes a claim referencing an Achievement that is generic to allow for use by many possible issuers. It is likely of achievementType Competency. The Achievement here is aligned to a Competency registered on the Credential Registry and described in CTDL. A Skill might have been defined by one organization (the creator of the Achievemeent) and then issued by another. In OB 3.0, image is optional. The Achievement might not even have one, in which case, often a placeholder image will be rendered.

          {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
              "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json",
              "https://w3id.org/security/suites/ed25519-2020/v1"
            ],
            "id": "http://1edtech.edu/credentials/3732",
            "type": [
              "VerifiableCredential",
              "OpenBadgeCredential"
            ],
            "name": "Document Savvy",
            "credentialSubject": {
              "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
              "type": "AchievementSubject",
              "achievement": {
                "id": "https://example.com/achievements/math/linear-1",
                "type": "Achievement",
                "alignment": [
                  {
                    "type": "Alignment",
                    "targetName": "DocumentSaving",
                    "targetType": "ceasn:Competency",
                    "targetUrl": "https://credentialfinder.org/competency/ce-6369c51f-4d86-4592-a761-8b32ae70a045"
                  }
                ],
                "achievementType": "Competency",
                "creator": {
                  "id": "https://example.com/issuers/123767",
                  "type": "Profile",
                  "name": "Example Industry Group",
                  "url": "https://example.com",
                  "description": "Example Industry Group is a consortium of luminaries who publish skills data for common usage.",
                  "email": "info@exammple.com"
                },
                "criteria": {
                  "narrative": "Pass the document saving performance demonstration assessment."
                },
                "description": "A basic skill of working on a computer is managing files. Recipients of this badge can save documents.",
                "name": "Document Savvy"
              }
            },
            "issuer": {
              "id": "did:web:badges.example.com:organization",
              "type": "Profile",
              "name": "Example Issuer",
              "url": "https://example.com/",
              "description": "Example Issuer is a well-known recognizer of skills",
              "image": {
                "id": "https://example.com/logo.png",
                "type": "Image",
                "caption": "Example Issuer Logo"
              },
              "email": "example@example.com"
            },
            "issuanceDate": "2022-07-01T00:00:00Z",
            "credentialSchema": [
              {
                "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
                "type": "1EdTechJsonSchemaValidator2019"
              }
            ],
            "proof": [
              {
                "type": "Ed25519Signature2020",
                "created": "2023-03-10T08:44:41Z",
                "verificationMethod": "did:web:badges.example.com:organization",
                "proofPurpose": "assertionMethod",
                "proofValue": "z3n3prnXsp6GDaJ2zKerQgd5qB7cE2Z4dynvnddgCLbs6hy3a5kcQPeTniVFcHSLwZ7A6ihh2FYxKJvBCPSQihcfP"
              }
            ]
          }

Endorse a Skill

As an organization that makes use of open skills, I would like to offer my support to an RSD that is a good fit for my community's needs.

As an employer, I want to endorse a specific skill, so that educational institutions teach, assess, and recognize those skills for their learners.

In order for skills data to be interoperable, common usage of the same skills across multiple producer and consumer roles in the ecosystem is needed. Endorsement can be a valuable signal of support for the use of certain existing skill definitions.

Recipes:
Open Badges 3.0 Endorsement

Recipe: Endorse a Skill with Open Badges 3.0 EndorsementCredential

Any issuer may produce an EndorsementCredential targeting a skill. See documentation

{
  "@context": [
    "https://rsd.openskillsnetwork.org/context-v1.json",
    "https://www.w3.org/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "type": [
    "VerifiableCredential",
    "EndorsementCredential"
  ],
  "issuer": {
    "id": "did:example:statedepartmentofed",
    "type": [
      "Profile"
    ],
    "name": "Big State Department of Education"
  },
  "issuanceDate": "2022-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "https://exampleframework.example.com/skills/123",
    "type": [
      "EndorsementSubject"
    ],
    "endorsementComment": "Example Framework's 'SharePoint Collaboration' skill definition is widely used in enterprise organizations.",
    "starRating": {"ratingValue": 5}
  },
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/endorsementcredential.json",
      "type": "1EdTechJsonSchemaValidator2019"
    },
    {
      "id": "https://state.gov/schema/endorsementcredential.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ]
}