feat: [LC-1350] - Add OBv3 Support to Boost Templates: evidence, alignment, source

[gerardopar]

Overview

🎟 Relevant Jira Issues

📚 What is the context and goal of this PR?

This PR extends our core Boost credential templates (boost, boostID) to support additional Open Badges v3 fields — aligning more closely with OBv3 interoperability standards and enriching issued credentials with deeper context.

Note: While this update is primarily focused on enabling Open Syllabus integration — leveraging course metadata, learning outcomes, and assigned works — the design is intentionally extensible. These fields (evidence, alignment, source) are generalized and can support other credentialing contexts in the future.

1. adds evidence:
   • Supports an array of Evidence objects (e.g. course syllabi, textbooks, project URLs), compliant with OBv3 format.
   • Docs:Evidence
2. alignment:
   • Injects learning outcomes and subject mappings as Alignment objects, including OpenSyllabus fields and CFSubject
     classifications.
   • Docs:Alignment
3. source:
   • Adds institutional metadata as a Profile object (e.g. Santa Monica College), including name, description, logo, address, and parent org (e.g. Open Syllabus).
   • Docs:Source

🥴 TL; RL:

💡 Feature Breakdown (screenshots & videos encouraged!)

🛠 Important tradeoffs made:

🔍 Types of Changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Chore (refactor, documentation update, etc)

💳 Does This Create Any New Technical Debt? ( If yes, please describe and add JIRA TODOs )

• No
• Yes

Testing

🔬 How Can Someone QA This?

1. Generate a Boost credential with
   • evidence
   • alignment
   • source
2. Paste output into JSON-LD Playground and ensure valid expansion.

// --- Hardcoded OBv3 alignment (field + learning outcomes)
            credentialPayload.alignment = [
                {
                    type: ['Alignment'],
                    targetName: 'Computer Science',
                    targetType: 'CFSubject',
                    targetFramework: 'Open Syllabus Field Classification',
                },
                {
                    type: ['Alignment'],
                    targetName: 'write algorithms to solve basic scripting problems',
                    targetType: 'LearningOutcome',
                    targetFramework: 'Open Syllabus',
                },
                {
                    type: ['Alignment'],
                    targetName:
                        'design and implement client-side programs using JavaScript to enhance and add interactivity to Web pages',
                    targetType: 'LearningOutcome',
                    targetFramework: 'Open Syllabus',
                },
                {
                    type: ['Alignment'],
                    targetName:
                        'use the following features of Dynamic HTML: Cascading Style Sheets, object model and collections, event model code basic AJAX Web applications',
                    targetType: 'LearningOutcome',
                    targetFramework: 'Open Syllabus',
                },
            ];

            // --- Hardcoded OBv3 evidence (syllabus + books)
            credentialPayload.evidence = [
                {
                    id: 'https://analytics.opensyllabus.org/singleton/syllabi?id=3676492023643',
                    type: ['Evidence'],
                    name: 'JavaScript and Dynamic HTML (CS 81) – Santa Monica College',
                    description:
                        'This programming course teaches the fundamentals of computer programming with the JavaScript language, the standard for client-side Web programming. It offers a thorough treatment of programming concepts with programs that yield visible or audible results in Web pages and Web-based applications. It shows how to use Core and Client-Side JavaScript and the Document Object Model to build interactive, high-performance Web sites.',
                    genre: 'CourseSyllabus',
                    audience: 'educators',
                },
                {
                    id: 'urn:isbn:0131450913',
                    type: ['Evidence'],
                    name: 'How to Program by Deitel',
                    genre: 'Textbook',
                    audience: 'learners',
                },
                {
                    id: 'https://openlibrary.org/works/OL1915197W',
                    type: ['Evidence'],
                    name: 'Programming the World Wide Web by Robert W. Sebesta',
                    genre: 'Textbook',
                    audience: 'learners',
                },
                {
                    id: 'urn:isbn:9781590282038',
                    type: ['Evidence'],
                    name: 'JavaScript Concepts and Techniques by Tina Spain McDuffie',
                    genre: 'Textbook',
                    audience: 'learners',
                },
            ];

            // --- Hardcoded OBv3 source (institution)
            credentialPayload.source = {
                type: ['Profile'],
                id: 'https://opensyllabus.org/institution/17884',
                name: 'Santa Monica College',
                description:
                    'Santa Monica College (SMC) is a public community college in Santa Monica, California. Founded as a junior college in 1929, SMC enrolls over 30,000 students in more than 90 fields of study...',
                url: 'http://www.smc.edu/Pages/Home.aspx',
                image: 'https://upload.wikimedia.org/wikipedia/en/thumb/9/97/Santa_Monica_College_seal.svg/500px-Santa_Monica_College_seal.svg.png',
                address: {
                    type: ['Address'],
                    addressLocality: 'Santa Monica',
                    addressRegion: 'California',
                    addressCountry: 'United States',
                },
            };

📱 🖥 Which devices would you like help testing on?

🧪 Code Coverage

Documentation

📜 Gitbook

📊 Storybook

✅ PR Checklist

• Related to a Jira issue (create one if not)
• My code follows style guidelines (eslint / prettier)
• I have manually tested common end-2-end cases
• I have reviewed my code
• I have commented my code, particularly where ambiguous
• New and existing unit tests pass locally with my changes
• I have made corresponding changes to gitbook documentation

🚀 Ready to squash-and-merge?:

• Code is backwards compatible
• There is not a "Do Not Merge" label on this PR
• I have thoughtfully considered the security implications of this change.
• This change does not expose new public facing endpoints that do not have authentication

✨ PR Description

Purpose: Add Open Badges v3 support to Boost Templates by implementing evidence, alignment, and source fields according to OBv3 specification.

Main changes:

• Added new type definitions for Evidence, Alignment, and Source following OBv3 specification
• Updated VC_TEMPLATES template functions to accept and conditionally include evidence, alignment, and source parameters
• Created conditional spread operators to only include OBv3 fields when values are provided

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using. We'd love your feedback! 🚀}

[changeset-bot]

🦋 Changeset detected

Latest commit: 74de342

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages

Name	Type
@learncard/vc-templates-plugin	Patch
@learncard/init	Patch
@learncard/network-brain-service	Patch
@learncard/learn-cloud-service	Patch
@learncard/chapi-example	Patch
@learncard/create-http-bridge	Patch
@learncard/cli	Patch
@learncard/react	Patch
learn-card-discord-bot	Patch
@learncard/network-brain-client	Patch
@learncard/learn-cloud-client	Patch
@learncard/learn-cloud-plugin	Patch
@learncard/snap-chapi-example	Patch
@learncard/network-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	74de342
🔍 Latest deploy log	https://app.netlify.com/projects/learncarddocs/deploys/68dffbef7130f100083f6d5d

[gitstream-cm]

✨ PR Review

The PR successfully adds Open Badges v3 support with evidence, alignment, and source fields to boost templates. The implementation follows OBv3 specifications and includes proper conditional spreading logic.

1 issues detected:

🐞 Bug - Empty objects could be spread into credentials when alignment or source are empty but truthy

Details: The conditional spreading for alignment and source fields will include empty objects in the credential if they are truthy but empty. This could result in credentials with empty alignment/source objects that may not conform to Open Badges v3 specifications.
File: packages/plugins/vc-templates/src/templates.ts (152-154)

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using. We'd love your feedback! 🚀}

[gitstream-cm]

🐞 Bug - Empty Object Spreading: Add checks to ensure alignment and source objects have meaningful content before spreading them, similar to the evidence array check that verifies both existence and length.

Suggested change

	...(alignment && { alignment }),
	},
	...(source && { source }),
	...(alignment && Object.keys(alignment).length > 0 && { alignment }),
	},
	...(source && Object.keys(source).length > 0 && { source }),

[gitstream-cm]

🥷 Code experts: TaylorBeeston

gerardopar, TaylorBeeston have most 👩‍💻 activity in the files.
gerardopar, TaylorBeeston have most 🧠 knowledge in the files.

See details

packages/plugins/vc-templates/src/templates.ts

Activity based on git-commit:

	gerardopar	TaylorBeeston
OCT
SEP	7 additions & 7 deletions
AUG
JUL	558 additions & 534 deletions	191 additions & 563 deletions
JUN
MAY

Knowledge based on git-blame:
TaylorBeeston: 75%
gerardopar: 25%

packages/plugins/vc-templates/src/types.ts

Activity based on git-commit:

	gerardopar	TaylorBeeston
OCT
SEP	6 additions & 0 deletions
AUG
JUL	3 additions & 0 deletions	4 additions & 1 deletions
JUN
MAY

Knowledge based on git-blame:
gerardopar: 60%
TaylorBeeston: 33%

✨ Comment /gs review for LinearB AI review. Learn how to automate it here.

[gitstream-cm]

✨ PR Review

The PR successfully adds OBv3 support fields (evidence, alignment, source) to Boost templates. However, there's a critical type mismatch between the alignment field definition and its expected usage pattern based on the PR description.

2 issues detected:

🐞 Bug - Type definition doesn't match the expected usage pattern and OBv3 specification requirements.

Details: The alignment field is defined as a single Alignment object, but the PR description and OBv3 specification indicate it should be an array of Alignment objects. This mismatch could cause runtime errors and non-compliance with OBv3 standards.
File: packages/plugins/vc-templates/src/types.ts (138-138)

🧹 Maintainability - Inconsistent type safety patterns across related interface definitions reduce code maintainability.

Details: The Evidence interface uses a tuple type to ensure at least one element, while Source and Alignment use simple string arrays that could be empty. This inconsistency makes the codebase harder to maintain and could lead to OBv3 compliance issues.
File: packages/plugins/vc-templates/src/types.ts

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using. We'd love your feedback! 🚀}