feat(templates): enforce template usage, validate against `schema` by daniel-mader · Pull Request #330 · impierce/ssi-agent

daniel-mader · 2026-04-28T08:08:56Z

Description of change

Templates are required for credential issuance.
Credential configurations are manged implicitly through the templates.
Nested structures (such as in Open Badges 3.0) are flattened.
Some properties in the JSON Schema can be marked as "immutable" through schema_properties_attributes, so they are locked and can never be altered/removed.

BREAKING CHANGE

Require templateId when creating a credential. The two fields data_model and holder_type become immutable after the initial template creation.

Links to any relevant issues

Be sure to reference any related issues by adding fixes issue #.

How the change has been tested

Describe the tests that you ran to verify your changes.
Make sure to provide instructions for the maintainer as well as any relevant configurations.

Definition of Done checklist

Add an x to the boxes that are relevant to your changes.

I have followed the contribution guidelines for this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
I have successfully tested this change in a docker environment

… template schema Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/0be5f674-cb23-4ded-9213-9316747a140f Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/0be5f674-cb23-4ded-9213-9316747a140f Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

…enforce-templates

codecov-commenter · 2026-04-28T10:26:28Z

Codecov Report

❌ Patch coverage is 84.86974% with 151 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agent_api_http/src/v0/issuance/credentials.rs	76.10%	38 Missing ⚠️
agent_application/src/lib.rs	0.00%	36 Missing ⚠️
agent_api_http/src/v0/library/error.rs	0.00%	25 Missing ⚠️
...application/credential_configuration_projection.rs	94.33%	21 Missing ⚠️
agent_library/src/template/aggregate.rs	94.05%	18 Missing ⚠️
agent_api_http/src/lib.rs	0.00%	6 Missing ⚠️
agent_api_http/src/v0/templates/mod.rs	16.66%	5 Missing ⚠️
agent_library/src/template/views/mod.rs	83.33%	1 Missing ⚠️
agent_store/src/lib.rs	66.66%	1 Missing ⚠️

Files with missing lines	Coverage Δ
...v0/authorization/authorization_server/authorize.rs	`100.00% <ø> (ø)`
...p/src/v0/authorization/authorization_server/par.rs	`100.00% <ø> (ø)`
...src/v0/authorization/authorization_server/token.rs	`95.45% <ø> (ø)`
...tp/src/v0/issuance/credential_issuer/credential.rs	`97.02% <100.00%> (ø)`
.../src/v0/issuance/credential_issuer/notification.rs	`98.94% <100.00%> (+0.02%)`	⬆️
...v0/issuance/credential_issuer/token_status_list.rs	`98.13% <100.00%> (+0.01%)`	⬆️
...al_issuer/well_known/oauth_authorization_server.rs	`97.61% <100.00%> (+0.11%)`	⬆️
...tial_issuer/well_known/openid_credential_issuer.rs	`97.14% <100.00%> (+0.17%)`	⬆️
agent_api_http/src/v0/issuance/mod.rs	`100.00% <100.00%> (ø)`
agent_api_http/src/v0/issuance/nonce/mod.rs	`100.00% <100.00%> (ø)`
... and 14 more

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Co-authored-by: Copilot <copilot@github.com>

- Extend PropertyAttribute with `immutable: bool` (default false) - Auto-populate `immutable: true` for all OpenBadges 3.0 schema properties - Enforce immutable properties cannot be removed during UpdateSchema - Ensure immutable flag cannot be altered via UpdateSchemaPropertiesAttributes - Add NonRemovablePropertyViolation error with HTTP 409 Conflict mapping - Add tests for immutable enforcement, auto-population, and flag preservation Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/8907cf6d-663a-4880-9dd8-9699fbfa3e5b Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

…rcement Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/8907cf6d-663a-4880-9dd8-9699fbfa3e5b Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

…al mapping - Define default required OB3 properties: achievement.name, achievement.criteria.narrative - Auto-merge these into the schema when creating an OpenBadges 3.0 template - Inject fixed achievement.type="Achievement" during credential mapping - Add map_open_badges_input_to_credential() to transform flat template input to nested OBv3 structure - Integrate mapping into credential creation endpoint for OB3 templates - Add unit tests for mapping and schema merging Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/1932e429-576c-4b09-9988-fd8fc69574b0 Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

…dundant immutable assignment Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/1932e429-576c-4b09-9988-fd8fc69574b0 Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

… into feat/enforce-templates

Copilot

Pull request overview

Copilot reviewed 35 out of 36 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

coplat · 2026-05-08T07:59:28Z

                .type_url(type_url("templates#invalid-schema-properties-attributes"))
                .source(self)
                .finish(),
+            TemplateError::NonRemovablePropertyViolation(_) => ApiError::builder(StatusCode::CONFLICT)


These errors should be added to the problem details documentation. The type_url's should be "library#..." instead of "templates#".

coplat · 2026-05-08T09:09:59Z

+            warn!("Template view not yet initialized; skipping credential configuration sync for `{template_id}`");
+            return;
+        };
+        match query_handler(template_id, view).await {


The match arm skips Draft and Deleted but implicitly allows Published and Archived. Should this be intended for Archived?

We should indeed treat "Archived" as "read-only", but that has more implications. We're not actively supporting that at the moment, so we can leave it as is for now and properly cover it in an upcoming task. The main goal for now is to keep the credential configurations and template updates in sync.

coplat · 2026-05-08T09:43:45Z

+/// Panics if `schema` is not a JSON object. Callers must ensure the schema is an object
+/// (or default to `{"type": "object"}`) before calling this function.
+#[cfg(test)]
+fn merge_open_badges_defaults(schema: &mut serde_json::Value) {


this test fn seems to only be called by test_merge_open_badges_defaults_into_empty_schema. but since the actual production code seems to be using validate_open_badges_required_properties as opposed to this auto-merge logic, I think this could be removed as it doesn't reflect the actual production code

nanderstabel

Edit: nvm the comment below, I figured out I had to update the status to published 👌

When I Create a new Template:

curl --location 'http://localhost:3033/v0/templates/create-template' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data '{
    "title": "My Example Template",
    "credentialFormat": "w3c_vc_data_model_v1-1",
    "holderType": "organization"
}'

I assumed that a corresponding Credential Configuration would be created and included to the Credential Issuer Metadata, but when I hit:

curl --location 'http://localhost:3033/.well-known/openid-credential-issuer' \
--header 'X-API-KEY: {{API_KEY}}'

No new Credential Configuration (with title "My Example Template") is included in the Metadata. Is this expected, should I somehow trigger a Syncing command explicitly?

nanderstabel · 2026-05-08T08:20:50Z

-    DataModelUpdated,
    CreatorUpdated,
-    HolderTypeUpdated,


The event types can now also be removed from ssi-agent/agent_event_publisher_http/README.md

nanderstabel · 2026-05-11T11:09:50Z

+            vec!["VerifiableCredential".to_string()]
+        }
+        DataModel::OpenBadges3_0 => {
+            vec!["OpenBadgeCredential".to_string(), "AchievementCredential".to_string()]


For OpenBadges, the type value should be an array where the first item must be "VerifiableCredential" and the second item must me either "OpenBadgeCredential" OR "AchievementCredential" (I think in most cases we default to "OpenBadgeCredential") (see: https://www.imsglobal.org/spec/ob/v3p0#achievementcredential)

nanderstabel · 2026-05-11T11:24:36Z

+                .type_url(type_url("templates#immutable-property-violation"))
+                .source(self)
+                .finish(),
+            TemplateError::DisallowedOpenBadgesProperties(_) => ApiError::builder(StatusCode::BAD_REQUEST)
+                .title("Disallowed OpenBadges Schema Properties")
+                .type_url(type_url("templates#disallowed-open-badges-properties"))
+                .source(self)
+                .finish(),
+            TemplateError::MissingRequiredOpenBadgesProperties(_) => ApiError::builder(StatusCode::BAD_REQUEST)
+                .title("Missing Required OpenBadges Schema Properties")
+                .type_url(type_url("templates#missing-required-open-badges-properties"))
+                .source(self)
+                .finish(),
+            TemplateError::InvalidRequiredPropertyType(_) => ApiError::builder(StatusCode::BAD_REQUEST)
+                .title("Invalid Required Property Type")
+                .type_url(type_url("templates#invalid-required-property-type"))
+                .source(self)
+                .finish(),
+            TemplateError::MissingTitle => ApiError::builder(StatusCode::BAD_REQUEST)
+                .title("Missing Title")
+                .type_url(type_url("templates#missing-title"))


All these type_urls are supposed to point to a specific Problem Details, but there is no description for them in the /docs/problem-details/library.md file

nanderstabel · 2026-05-11T12:19:00Z

    pub credential: Value,
    #[serde(default)]
    pub is_signed: bool,
-    pub credential_configuration_id: String,


Not only the Credentials Endpoint includes the credential_configuration_id but also the Offers Endpoint includes the credential_configuration_ids property (in agent_api_http/src/v0/issuance/offers/mod.rs), which is only used for the JIT Credentials flow. I think for consistency it should be removed there as well (or for now add a TODO comment so we can address that at a later point).

nanderstabel · 2026-05-11T12:56:09Z

Since this PR makes makes Credential Configurations unusable in the API, it also does not make sense anymore to initialize those 'default' Credential Configurations on startup, so imo fn update_credential_configurations in agent_issuance/src/state.rs should be completely removed 🥳

nanderstabel · 2026-05-11T15:45:53Z

+            let path_elements: Vec<ClaimPathElement> = key
+                .split('.')
+                .map(|segment| ClaimPathElement::String(segment.to_string()))
+                .collect();
+
+            let path = ClaimPathPointer::try_new(path_elements).ok()?;


If the provided properties look like this:

"properties": { "age": {}, "name": {} }

then the claim path pointers will look like this:

["age"]

[name"]

but especially since this code is only executed when format == "vc+sd-jwt", it's more likely that the claim pat pointers end up as:

["credentialSubject", "age"]

["credentialSubject", name"]

…t/enforce-templates

nanderstabel · 2026-05-11T15:52:48Z

+    let claims = if format == "vc+sd-jwt" {
+        build_claims_from_schema(template)
+    } else {
+        None
+    };


Why only build claims when format == "vc+sd-jwt"? I think you can make it work for "dc+sd-jwt" as well if you rewrite this part to something like this:

let claims = if format == "vc+sd-jwt" { build_claims_from_schema(template, "credentialSubject."]) } else if format == "dc+sd-jwt" { build_claims_from_schema(template, "") } else { None };

where "credentialSubject." can be prepended to key to create the path_elements in fn build_claims_from_schema

related: https://github.com/impierce/ssi-agent/pull/330/changes#r3220225971

Co-authored-by: Copilot <copilot@github.com>

Copilot AI and others added 8 commits April 10, 2026 16:52

feat: require template_id when creating credentials, validate against…

a9fb88c

… template schema Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/0be5f674-cb23-4ded-9213-9316747a140f Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

fix: skip template schema validation for signed credentials

1dfcbc0

Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/0be5f674-cb23-4ded-9213-9316747a140f Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

refactor: simplify Box deref pattern in template schema check

18db00e

Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/0be5f674-cb23-4ded-9213-9316747a140f Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

feat: add template_id to request body

7706a1c

Merge branch 'copilot/require-template-id-for-credentials' into feat/…

0f9acb5

…enforce-templates

refactor: reorder, fix clippy issues

96e6882

build: refactor dependency

c6e56c2

refactor: provide state to router explicitly

0bfc4c8

daniel-mader self-assigned this Apr 28, 2026

daniel-mader added 3 commits April 28, 2026 11:04

fix: group /credentials endpoints

22104f6

test: template ID for tests

af5250e

Merge branch 'beta' into feat/enforce-templates

b26783a

daniel-mader mentioned this pull request Apr 28, 2026

feat(templates): enforce template usage, validate against schema #329

Closed

7 tasks

daniel-mader changed the title ~~feat(templates): enforce templates~~ feat(templates): enforce template usage, validate against schema Apr 28, 2026

daniel-mader added 5 commits April 28, 2026 11:15

docs: generate OpenAPI

8ce47be

refactor: replace qualifiers with imports

ab5ef60

refactor: imports

bf0b868

test: use UUID for template ID

c7986fd

fix: scope routes with version prefix

38cb96f

daniel-mader marked this pull request as ready for review April 28, 2026 10:42

daniel-mader requested a review from nanderstabel as a code owner April 28, 2026 10:42

daniel-mader marked this pull request as draft April 28, 2026 10:43

daniel-mader and others added 7 commits April 29, 2026 21:30

feat: manage credential configurations through templates

aa086d9

refactor: extract function

11a64af

Co-authored-by: Copilot <copilot@github.com>

refactor: consolidate loops and simplify allocation in immutable enfo…

53996e7

…rcement Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/8907cf6d-663a-4880-9dd8-9699fbfa3e5b Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

refactor: address code review - clarify expect messages and remove re…

f047936

…dundant immutable assignment Agent-Logs-Url: https://github.com/impierce/ssi-agent/sessions/1932e429-576c-4b09-9988-fd8fc69574b0 Co-authored-by: daniel-mader <45594838+daniel-mader@users.noreply.github.com>

feat: generate OpenAPI

b43a9c6

daniel-mader added 3 commits May 5, 2026 15:39

Merge remote-tracking branch 'origin/copilot/make-title-not-optional'…

43488d7

… into feat/enforce-templates

feat: generate OpenAPI

cf416be

test: fix types

c7cdb91

daniel-mader requested a review from Copilot May 5, 2026 14:05

daniel-mader marked this pull request as ready for review May 5, 2026 14:05

Copilot started reviewing on behalf of daniel-mader May 5, 2026 14:06 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread agent_library/src/template/aggregate.rs

Comment thread agent_issuance/src/application/credential_configuration_projection.rs

Comment thread agent_api_http/src/v0/templates/mod.rs

feat: remove Optional<> from required fields in Template

05d07a8

daniel-mader changed the title ~~feat(templates): enforce template usage, validate against schema~~ feat(templates): enforce template usage, validate against schema May 6, 2026

daniel-mader requested a review from coplat May 7, 2026 07:56

daniel-mader added 2 commits May 7, 2026 10:11

refactor: remove redundant code

1ec8445

feat: make tags and type optional for template updates

4d266f8

coplat reviewed May 8, 2026

View reviewed changes

nanderstabel requested changes May 11, 2026

View reviewed changes

nanderstabel reviewed May 11, 2026

View reviewed changes

Comment thread agent_api_http/src/v0/issuance/credentials.rs Outdated

nanderstabel reviewed May 11, 2026

View reviewed changes

Comment thread agent_issuance/src/application/credential_configuration_projection.rs

daniel-mader added 3 commits May 11, 2026 16:50

feat: address review comments

41f8a33

feat: remove deprecated code

b88870e

fix: include schema

95a4090

nanderstabel reviewed May 11, 2026

View reviewed changes

daniel-mader added 2 commits May 11, 2026 17:47

feat: address review comments

6f3891a

Merge remote-tracking branch 'origin/feat/enforce-templates' into fea…

651e184

…t/enforce-templates

nanderstabel reviewed May 11, 2026

View reviewed changes

daniel-mader and others added 6 commits May 11, 2026 18:33

fix: include credentialSubject prefix

a05f399

Co-authored-by: Copilot <copilot@github.com>

test: remove function only used in tests

1837041

Co-authored-by: Copilot <copilot@github.com>

test: adjust tests to new templates

d5f2ff3

Co-authored-by: Copilot <copilot@github.com>

docs: replace templates with library

1a21523

fix: always validate in credentialSubject

41da9e1

Co-authored-by: Copilot <copilot@github.com>

feat: use expiration defined in template

7f93fd9

Co-authored-by: Copilot <copilot@github.com>

Conversation

daniel-mader commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of change

BREAKING CHANGE

Links to any relevant issues

How the change has been tested

Definition of Done checklist

Uh oh!

codecov-commenter commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nanderstabel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nanderstabel commented May 11, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

daniel-mader commented Apr 28, 2026 •

edited

Loading

codecov-commenter commented Apr 28, 2026 •

edited

Loading

nanderstabel left a comment •

edited

Loading