Schemas, Types, & Categories

Using Open Badge v3 Contexts

To create a credential following the Open Badge v3 specification:

1. Include the OB v3 context in your @context array:

   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
   ]

2. Add required credential types:

   "type": ["VerifiableCredential", "OpenBadgeCredential"]

3. Structure your credentialSubject with appropriate types:

   "credentialSubject": {
     "id": "did:example:recipient123",
     "type": ["AchievementSubject"],
     "achievement": {
       "id": "https://example.org/achievements/123",
       "type": ["Achievement"],
       "name": "Achievement Name",
       "description": "Achievement description",
       "criteria": {
         "narrative": "Description of criteria for earning this achievement"
       }
     }
   }

Extending Context with Custom Fields

You can extend the context to add custom fields using two methods:

Method 1: Embedded Context

Include custom definitions directly in the credential:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context.json",
    {
      "skills": "https://example.org/terms/skills",
      "Skill": "https://example.org/terms/Skill",
      "proficiencyLevel": "https://example.org/terms/proficiencyLevel"
    }
  ],
  "type": ["VerifiableCredential", "OpenBadgeCredential"],
  "credentialSubject": {
    "id": "did:example:recipient123",
    "type": ["AchievementSubject"],
    "achievement": {
      "id": "https://example.org/achievements/123",
      "type": ["Achievement"],
      "name": "Programming Skills"
    },
    "skills": [
      {
        "type": ["Skill"],
        "name": "JavaScript",
        "proficiencyLevel": "Advanced"
      }
    ]
  }
}

Method 2: Remote Context

Reference an external context file:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context.json",
    "https://example.org/contexts/skills.json"
  ],
  "type": ["VerifiableCredential", "OpenBadgeCredential"],
  "credentialSubject": {
    "id": "did:example:recipient123",
    "skills": [
      {
        "id": "https://example.org/skills/js",
        "proficiencyLevel": "Advanced"
      }
    ]
  }
}

The remote context file (skills.json) would define the terms:

{
  "@context": {
    "skills": "https://example.org/terms/skills",
    "Skill": "https://example.org/terms/Skill",
    "proficiencyLevel": {
      "@id": "https://example.org/terms/proficiencyLevel",
      "@type": "xsd:string"
    }
  }
}

Achievement Types & Categories

Our system uses Achievement Types to organize and categorize user credentials. This document explains how to work with standard and custom types and ensure they integrate seamlessly into the platform.

Categories We Support

Our system organizes achievements into predefined categories to ensure they are properly grouped and displayed. Below is the list of supported categories:

Category	Identifier	Description
Achievement	Achievement	Generic accomplishments.
ID	ID	Identifiers such as student or employee IDs.
Learning History	Learning History	Records of educational achievements.
Work History	Work History	Records of professional experience.
Social Badges	Social Badges	Recognition tied to social or community participation.
Membership	Membership	Memberships in organizations or groups.
Accomplishment	Accomplishment	Specific completed tasks or goals.
Accommodation	Accommodation	Support or adjustments made for individuals.
Family	Family	Recognition tied to family relationships or contributions.

Standard Achievement Types

Overview

Standard AchievementTypes are predefined achievement types that do not include the ext: prefix. These types are sourced directly from the IMS Global Open Badges v3 AchievementType Enumeration. These types are directly recognized by the system and are mapped to predefined categories without additional transformation.

Here is the complete list of predefined achievement types supported on our platform

AchievementType (String)	Category (String)
'Achievement'	'Achievement'
'Assessment'	'Achievement'
'Award'	'Achievement'
'Badge'	'Achievement'
'Certificate'	'Achievement'
'Certification'	'Achievement'
'CommunityService'	'Achievement'
'Competency'	'Achievement'
'Degree'	'Achievement'
'MicroCredential'	'Achievement'
'License'	'ID'
'Membership'	'Membership'
'ApprenticeShipCertificate'	'Work History'
'JourneymanCertificate'	'Work History'
'MasterCertificate'	'Work History'
'Assignment'	'Learning History'
'AssociateDegree'	'Learning History'
'BachelorDegree'	'Learning History'
'CertificateOfCompletion'	'Learning History'
'CoCurricular'	'Learning History'
'Course'	'Learning History'
'Diploma'	'Learning History'
'DoctoralDegree'	'Learning History'
'FieldWork'	'Learning History'
'GeneralEducationDevelopment'	'Learning History'
'LearningProgram'	'Learning History'
'MasterDegree'	'Learning History'
'ProfessionalDoctorate'	'Learning History'
'QualityAssuranceCredential'	'Learning History'
'ResearchDoctorate'	'Learning History'
'SecondarySchoolDiploma'	'Learning History'

Custom Credential Types

Custom AchievementTypes, include the ext: prefix and allow for user-defined or external achievements. These custom types must adhere to specific formatting rules.

Rules for Custom Types

1. Prefix: Custom types must begin with ext:.

2. Validation: Custom types must match the regex:

   ^([a-zA-Z]+\s*){3,25}$

3. Structure: Custom types follow this format:

   ext:LCA_CUSTOM:<CategoryType>:<TransformedAchievementType>

   Example: ext:LCA_CUSTOM:Learning History:The_Coolest_Dog

---

Formatting Logic

Custom types are formatted using helper functions:

Capitalize Words

Converts lowercase strings like cool cat to Cool Cat:

const capitalizeWordsAfterSpace = (str: string): string => {
    return str.replace(/(?:^|\s)\w/g, (match) => match.toUpperCase());
};

Replace Spaces with Underscores

Converts "Cool Cat" to "Cool_Cat":

const replaceWhiteSpacesWithUnderscores = (str: string): string => {
    return str.replace(/\s+/g, '_');
};

Construct the Final Type

Combines the category and transformed achievement type:

const constructCustomType = (categoryType: string, customAchievementType: string) => {
    const capitalized = capitalizeWordsAfterSpace(customAchievementType);
    const transformed = replaceWhiteSpacesWithUnderscores(capitalized);
    return `ext:LCA_CUSTOM:${categoryType}:${transformed}`;
};

Example:

constructCustomType("Learning History", "The Coolest Dog");
// Output: ext:LCA_CUSTOM:Learning History:The_Coolest_Dog

---

Internal Handling of Custom Types

Custom types are processed internally using the following helper functions:

Check if a Type is Custom

This function checks if a given type string contains the LCA_CUSTOM identifier:

export const isCustomType = (str: string): boolean => {
    const regex = /LCA_CUSTOM/;
    const result = regex.test(str);
    return result;
};

Extract Achievement Type from Custom Type

This function extracts the specific achievement type from a custom type string:

export const getAchievementTypeFromCustomType = (str: string) => {
    // ie: str -> "ext:LCA_CUSTOM:Learning History:The_Coolest_Dog";
    const regex = /^((?:[^:]+:){3})([^:]+)/;
    const result = str.match(regex)?.[2]; // "The_Coolest_Dog"
    return result;
};

Extract Category Type from Custom Type

This function extracts the category type from a custom type string:

export const getCategoryTypeFromCustomType = (str: string) => {
    // ie: str -> "ext:LCA_CUSTOM:Learning History:The_Coolest_Dog";
    const regex = /(?:[^:]*:){2}([^:]*)(?::|$)/;
    const result = str.match(regex)?.[1]; // "Learning History"
    return result;
};

---

FAQ

Can I create new categories?

No, our system only supports the following pre defined categories

export const CATEGORIES = {    
    Achievement: 'Achievement',
    ID: 'ID',
    LearningHistory: 'Learning History',
    WorkHistory: 'Work History',
    SocialBadge: 'Social Badge',
    Membership: 'Membership',
    Accomplishment: 'Accomplishment',
    Accommodation: 'Accommodation',
    Family: 'Family',
};

How do I validate a custom type?

Use the CUSTOM_TYPE_REGEX to ensure compliance:

/^([a-zA-Z]+\s*){3,25}$/;

You can also test the formatting of your custom type to ensure it works internally:

1. Check if the type is custom: Use the isCustomType function:

   const isCustom = isCustomType('ext:LCA_CUSTOM:Learning History:The_Coolest_Dog');
   console.log(isCustom); // Output: true

2. Extract the achievement type: Use the getAchievementTypeFromCustomType function:

   const achievementType = getAchievementTypeFromCustomType('ext:LCA_CUSTOM:Learning History:The_Coolest_Dog');
   console.log(achievementType); // Output: The_Coolest_Dog

3. Extract the category type: Use the getCategoryTypeFromCustomType function:

   const categoryType = getCategoryTypeFromCustomType('ext:LCA_CUSTOM:Learning History:The_Coolest_Dog');
   console.log(categoryType); // Output: Learning History