Skip to main content

Work with an external schema

Truvity credential schemas are designed for interoperability with other self-sovereign identity (SSI) ecosystems and industry standards. This page provides a practical guide on how to work with schema definitions that originate outside of the Truvity platform.

You can use external schemas in two ways:

  1. Using the SDK: The recommended method for defining schemas programmatically within your code.
  2. Using the API: The method for advanced users or for creating schemas with a non-SDK client.
important

Considerations and limitations:

  • Validation responsibility: When referencing external schemas, the Truvity platform does not validate your UDT structure against the external schemas at compile time or upon issuance. It is your responsibility to ensure that your UDT claim definitions accurately match the external schema structure.

  • Developer experience improvement: Despite the lack of compile-time validation, using UDTs still significantly improves developer experience compared to manual JSON manipulation for external schemas, as it handles basic type-safe serialization and deserialization.

  • UDT generation: Direct UDT generation from arbitrary external schemas is currently not supported.

Using the SDK​

Prerequisites

The @VcExternalSchema decorator allows you to specify external JSON-LD vocabularies and JSON schemas that your UDT should reference during credential issuance. This decorator is used in conjunction with the @VcSchema decorator to define an external schema.

Augmenting a managed schema​

This method is useful when your Truvity-managed schema needs to use terms or contexts from a well-known external semantic definition.

@VcSchema(slug = "proof-of-identity")
@VcExternalSchema(
    jsonLdVocabs = {
        VcSchema.jsonLdVocabUrl, // Special symbol: SDK will replace with the URL of the published JSON-LD context
        "https://www.w3.org/ns/credentials/examples/v2", // An example external w3.org context
    }
)
class ProofOfIdentity {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;
}

Using a fully external schema​

This method is useful when you want to create a UDT that is based entirely on external schemas. The UDT in this case acts as a type-safe wrapper for the external schema.

@VcSchema
@VcExternalSchema(
        jsonLdVocabs = {"https://www.w3.org/ns/credentials/examples/v2"},
        vcJsonSchemas = {"https://example.com/schemas/email.json"})
class ProofOfIdentity {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;
}

Using the API​

Prerequisites

For direct API access, you can reference external schemas when you create a draft using the POST /drafts endpoint. The request payload has json_ld_vocabs and vcdm_json_schemas properties that you can use to reference external schemas directly:

{  
    "data": {
        "vcdm_json_schemas": [
            "https://example.com/schemas/email.json"
        ],
        "values": {
            "emailAddress": {
                "kind": "STRING",
                "value": "john.doe@example.com"
            }
        }
    }
}

Further reading​