Skip to main content

Changelog

November 27, 2025​

API v0.40.11, Java SDK v0.40.11

Introducing credential schema management​

This release introduces a comprehensive suite of tools to manage the entire lifecycle of your credential structures. Credential schemas act as immutable blueprints for your data, ensuring consistency across your ecosystem and facilitating interoperability with external partners.

With this release, you can now:

  • Define schemas once and use them across different credential formats
  • Publish schemas to make them publicly verifiable and discoverable
  • Version your data models to evolve them over time without breaking existing credentials

Get started with the Schema Management Overview and dive into Managing Schemas.

Breaking changes​

This release introduces several breaking changes to improve schema management and support multiple credential formats:

  1. Structured claim values: The values property in drafts now uses a structured format (CredentialClaimValues) with type hints instead of accepting arbitrary data. This resolves serialization and deserialization issues when working with different credential formats and ensures type safety.

  2. Renamed schema model: We replaced the DraftSchema model with ClaimsSchema. While structurally similar, ClaimsSchema uses clearer, less ambiguous parameter names to better support multiple credential formats.

  3. Schema reference updates: We renamed the schema property in draft creation requests to meta_schema. This property now accepts either:

    • Schema definitions (MetaSchema) for temporary schemas during development
    • URLs to published schemas for production use
Backward compatibility

To avoid disruption from the introduced breaking changes, we support the previous version of the API (v0.38.0) alongside the new version to provide a migration period.

If you use one of the SDKs (TypeScript or Java), it automatically enables backward compatibility for all versions lower than v0.40.0. You do not need to take any action.

If you use the API directly, include the HTTP header X-Truvity-OAS-Version: 0.38.2 in all requests to enable backward compatibility.

Deprecation timeline

We will support the old version of the API for up to 3 months. We encourage all customers to update their integrations to the latest version during this period.

Read the migration guide here.

warning

We may decommission the old API sooner if all active customers migrate before the 3-month period ends.

API​

  • New: Credential Schemas API for managing, versioning, and publishing credential schemas. Key operations include:

    • POST /schemas (SchemaCreate) - Create schema definitions
    • PATCH /schemas/{id}/publish (SchemaPublish) - Publish schemas to make them immutable and publicly verifiable
    • POST /schemas/search (SchemaSearch) - Search for schemas
    • POST /published-schemas/search (PublishedSchemaSearch) - Search for published schemas

  • New: GET /credentials/{id}/values (GetCredentialClaimValues) - Retrieve claim values from issued credentials in a unified, format-independent structure (matching the structure used for draft values).

SDK​

Java SDK​

  • New: Full support for credential schema management capabilities:

    • Methods for creating, publishing, and versioning schemas
    • VcDecorator.publishSchema() method for making schemas production-ready
    • Enhanced schema referencing when creating drafts

  • New: Schema definition decorators:

    • @VcSchema - Define schemas, specify publication settings (slug and version), and associate them with user-defined types (UDTs). Learn more
    • @VcExternalSchema - Reference external JSON-LD vocabularies and JSON schemas for interoperability with other SSI ecosystems. Learn more

  • Deprecation: The @VcContext decorator. We will remove this in a future release. Migrate to @VcSchema for improved schema management.

  • Fix: API error responses now properly display human-readable error messages instead of object hashes.

TypeScript SDK​

  • Note: Full support for the new schema management is coming soon. This release focuses on Java SDK capabilities.

Documentation​

  • New section: Schema Management - Comprehensive documentation covering the meta-schema model, temporary vs. stable schemas, publication lifecycle, and schema governance principles.

  • New guides:

Migration to version 0.40.XX​

For direct API users​

Follow these steps to update your API integration:

1. Update draft value structure​

What changed: the values property now requires a structured format with explicit type information.

Action required: instead of passing arbitrary JSON objects, wrap each claim value with type information:

{
  "values": {
    "firstName": {
      "kind": "STRING",
      "value": "John"
    },
    "age": {
      "kind": "NUMBER",
      "value": 30
    }
  }
}

This applies to:

  • POST /drafts (DraftCreate) - DraftCreateRequest.data.values
  • PATCH /drafts/{id} (DraftUpdate) - DraftUpdateRequest.data.values
  • ResourceDraft.data.values (in all draft-related API responses)
2. Update schema references in drafts​

What changed: we restructured schema management to support both temporary and published schemas.

ResourceDraft.data changes:

  • Removed: schema property
  • Added:
    • meta_schema: string - URL reference to a published schema
    • json_ld_vocabs: string[] - JSON-LD vocabulary URLs for semantic definitions
    • vcdm_json_schemas: string[] - JSON Schema URLs for validation (following the W3C vc-json-schema specification)

DraftCreateRequest.data changes:

  • Added:

    • meta_schema?: string - URL of a published schema. Required unless you use the schema property for temporary schemas.

    • json_ld_vocabs?: string[] - Override or supplement JSON-LD vocabularies from the published schema. Enables mixing platform and external vocabularies.

      Example:

      "json_ld_vocabs": [
        "https://ssi.truvity.com/tenants/123/vocab/passport/v1",
        "https://www.w3.org/ns/credentials/examples/v2"
      ]

    • vcdm_json_schemas?: string[] - Override JSON Schema validation from the published schema. Useful for external schemas or custom validation rules not supported by the meta-schema.

  • Updated:

    • schema - Now optional (type changed from required DraftSchema to optional { schema: ClaimsSchema, slug?, version? }). Use this for temporary schemas during development. You must provide either schema or meta_schema.
3. Update search operations​

The POST /drafts/search (DraftSearch) operation now returns draft resources using the structure described above. Update your response parsing logic accordingly.

For SDK users (Java)​

Follow these steps to migrate your SDK-based integration:

1. Update your SDK version​

Upgrade to SDK version 0.40.0 or higher:

<!-- Maven -->
<dependency>
    <groupId>com.truvity</groupId>
    <artifactId>sdk</artifactId>
    <version>0.40.11</version>
</dependency>
tip

The SDK automatically enables backward compatibility for versions lower than v0.40.0. Existing applications will continue to work during the migration period.

2. Update decorator usage​

Replace @VcContext with @VcSchema:

- @VcContext(name = "Passport", namespace = "urn:example")
+ @VcSchema
  class Passport {
      @NotEmpty
      String passportNumber;

      String nationality;
  }

If using search capability: if your app searches for credentials by context name, temporarily add the @VcSchemaJsonLdTermName decorator to maintain compatibility while you transition to published schemas:

  @VcSchema
+ @VcSchemaJsonLdTermName("Passport")
  class Passport {
      @NotEmpty
      String passportNumber;

      String nationality;
  }
note

The @VcSchemaJsonLdTermName decorator preserves the JSON-LD term name for backward compatibility. Once you publish your schema, you can remove this decorator as the published schema includes the term definition.

3. Publish your schemas​

For production deployments, publish your schemas to ensure immutability and verifiability:

VcDecorator<Passport> passportDecorator = client.vcDecorator(Passport.class);

// Publish the schema
passportDecorator.publishSchema();

Learn more about schema publication and versioning in the Publication and Versioning guide.