Skip to main content

Configuration schemas

Configuration files name their format in $schema, for example https://eudiplo.dev/schemas/v4/PresentationConfigFile.schema.json. This page explains how these format versions work, how to bump one, and how the schemas are published. The file format itself is described in Configuration as code.

Format versions​

Each resource type has its own format version in CONFIG_FORMATS (packages/eudiplo-config-format/src/config-format.ts); it is independent of the application version. EUDIPLO 9.0 introduced the first bumps; IssuanceConfig v3 followed in 9.1, CredentialConfig v2 to v4, KeyChain v2, Client v2, KmsConfig v2, Tenant v2 to v4, IssuanceConfig v4 to v7, KeyChain v3 and v4, KeyChainDefaults v2, PresentationConfig v4 and v5 and TrustList v2 in 10.0, which also retired RegistrarConfig:

ResourceVersionChange
IssuanceConfigv2Optional offerLifetimeSeconds. A v1 file is a valid v2 file.
IssuanceConfigv3Optional verifierKeyPem (PEM public key) in walletProviderTrustLists entries. A v2 file is a valid v3 file.
IssuanceConfigv4Optional walletAttestationStatusCheckMode on the issuance configuration and its authorization servers. A v3 file is a valid v4 file.
IssuanceConfigv5Optional entity configuration fields in federation (entityTypes, authorityHints, entityKeyChainId, entityConfigurationLifetimeSeconds, trustMarks, entityMetadata, includeTrustChain). A v4 file is a valid v5 file.
IssuanceConfigv6The top-level signingKeyId is removed; the v5 → v6 step drops a set value with the warning ISSUANCE_SIGNING_KEY_ID_REMOVED and keeps token.signingKeyId with the warning AUTHORIZATION_SERVER_KEY_CHAIN_REQUIRED. Optional registrationCertificate.renewal.
IssuanceConfigv7registrationCertificate.mode and .renewal are removed: the issuer metadata carries the configured jwt only, as EUDIPLO no longer generates certificates at the sandbox registrar. The v6 → v7 step drops both, and a jwt that generate mode (the default) did not serve with the warning ISSUER_REGISTRATION_CERTIFICATE_JWT_DROPPED; an enabled certificate in generate mode without jwt gets the warning ISSUER_REGISTRATION_CERTIFICATE_NOT_GENERATED.
CredentialConfigv2x509 as frameworkType of schemaMeta.trustedAuthorities entries. A v1 file is a valid v2 file.
CredentialConfigv3fields[].constraints accept only JSON Schema validation and annotation keywords. The v2 → v3 step drops other keys with a warning and stops on claim patterns RE2 cannot run (CLAIM_PATTERN_UNSUPPORTED).
CredentialConfigv4config.display[] colors must be CSS Color Level 3 numerical values, and each locale may appear once; optional revokeWithWalletUnit. The v3 → v4 step trims colors and lowercases their function names, drops the ones wallets cannot read with the warning DISPLAY_COLOR_REMOVED and stops on a repeated locale (DISPLAY_LOCALE_DUPLICATE).
KeyChainv2Optional type (standalone, internalChain). A v1 file is a valid v2 file; a bare key chain file with type is read as v2 (bareFileVersion).
KeyChainv3Usage type federation. A v2 file is a valid v3 file; a bare key chain file with usage type federation is read as v3.
KeyChainv4Usage type authorizationServer. A v3 file is a valid v4 file; a bare key chain file with usage type authorizationServer is read as v4.
KeyChainDefaultsv2Optional authorizationServer entry. A v1 file is a valid v2 file; a bare key-chain-defaults.json with the entry is read as v2 (bareFileVersion).
Clientv2The roles audit:read, sessions:read, credentials:status and keys:manage. A v1 file is a valid v2 file.
KmsConfigv2Optional algorithms and defaultAlgorithm on providers. A v1 file is a valid v2 file; a bare kms.json with either field on a provider is read as v2 (bareFileVersion).
Tenantv2Optional defaultAccessKeyChainId. A v1 file is a valid v2 file; a bare info.json with the field is read as v2 (bareFileVersion). Only in development builds of 10.0.
Tenantv3defaultKeyChains map by usage type replaces defaultAccessKeyChainId; the v2 → v3 step moves it to defaultKeyChains.access. A bare info.json with defaultKeyChains is read as v3. Only in development builds of 10.0.
Tenantv4defaultKeyChains moves to the new resource KeyChainDefaults (key-chain-defaults.json, v1); the v3 → v4 step drops it with the warning DEFAULT_KEY_CHAINS_MOVED.
PresentationConfigv2registration_cert.body.provided_attestations is replaced by the registrar's provides_attestations (string array). The v1 → v2 step drops the old field with a warning.
PresentationConfigv3DCQL claim values accept integers and booleans besides strings and must be non-empty. A v2 file is a valid v3 file unless it has an empty values array.
PresentationConfigv4Optional allowedOrigins (web origins for Digital Credentials API requests), and etsi_tl values with format: lote, or trusted-list with signingCertificates and schemeTerritories for ETSI TS 119 612 Trusted Lists. A v3 file is a valid v4 file; a bare presentation file with allowedOrigins or an etsi_tl value with format is read as v4 (bareFileVersion).
PresentationConfigv5registration_cert holds the jwt and the purpose and privacy_policy a new certificate is requested with; id, body and the flat registrationCert* form fields are removed. The v4 → v5 step moves body.purpose and body.privacy_policy up a level (from the form fields when no registration_cert is set), drops id and the other body fields with the warning REGISTRATION_CERT_FIELD_REMOVED, drops incomplete purposes (REGISTRATION_CERT_PURPOSE_INCOMPLETE) and warns with REGISTRATION_CERT_NOT_REQUESTED when a certificate was requested from the registrar and no jwt is set. A bare presentation file with registration_cert.purpose or .privacy_policy is read as v5.
TrustListv2Entity info follows ETSI TS 119 602: info.country is an ISO 3166-1 alpha-2 code in capital letters (UK, EL, EU as exceptions), info.lang a lower-case RFC 5646 tag and info.uri an absolute URI; the required info.contactUri (e-mail address) and the new required info.website and optional info.phone form TEElectronicAddress (clause 6.5.3.2). v1 has no website, so the v1 → v2 step is report-only and always stops with TRUST_LIST_WEBSITE_MISSING; it also names every other value v2 refuses: TRUST_LIST_CONTACT_URI_MISSING/_INVALID, and TRUST_LIST_COUNTRY_INVALID, TRUST_LIST_LANGUAGE_INVALID (with the value to write, for example UK for gb) and TRUST_LIST_URI_INVALID.
All other resourcesv1

RegistrarConfig (registrar.json, v1 published by 9.x) is retired with the sandbox registrar integration. Its v1 snapshot stays published; a tenant folder file, a bundle document or a ZIP entry of this kind is skipped with the warning REGISTRAR_CONFIG_REMOVED instead of failing the import, and eudiplo config upgrade leaves it out of the upgraded folder. A kind is retired in RETIRED_CONFIG_FILES and RETIRED_TENANT_FOLDER_FILES (config-format.ts); withoutRetiredResources (config-bundle.ts) removes its documents from a bundle.

The backend and the CLI bundle every published snapshot (schemas/v*/) and never fetch schema URLs from files. Older files are upgraded on import, one version step at a time, through CONFIG_MIGRATIONS: the startup import and bundle imports (POST /api/config-bundles/plan and /import) accept warnings and stop on issues that need input; eudiplo config upgrade <file-or-folder> does the same offline. A file with a newer version than the running release supports is rejected, so 9.0 exports cannot be imported into 8.x.

Bump a format version​

Bump the version whenever the accepted content of a resource changes, including documentation-only changes to a published schema.

  1. Change the backend schema of the resource and increment its version in CONFIG_FORMATS.

  2. Add exactly one step from the previous version to CONFIG_MIGRATIONS in the same module. migrate(spec, metadata) returns the new spec, optionally new metadata, and issues: warning for lossy but automatic changes, required-input when a user must decide. Keep the resource identity. presentationConfigV1ToV2 is the reference.

  3. If stored data must change as well, add a database migration (Backend architecture).

  4. Regenerate the schemas and create the snapshot of the new version:

    pnpm gen:api # current schemas in schemas/*.schema.json
    pnpm schemas:snapshot PresentationConfig # writes schemas/v<N>/…; never overwrites an existing file
    pnpm schemas:sync # bundles schemas/v*/ into the config-format package
    pnpm --filter @eudiplo/cli assets:sync # copies schemas and templates into the CLI
  5. Bring the bundled demo tenant to the new version. eudiplo init --demo-tenant and eudiplo config tenant create --template demo copy assets/config/demo, so a file there that is behind fails eudiplo config upgrade --check in a fresh project. The CLI test generates configuration that needs no upgrade (apps/cli/test/runtime.test.ts) fails until you upgrade it from the repository root (dev runs in apps/cli, and the --output folder must not exist yet):

    pnpm --filter @eudiplo/cli dev config upgrade ../../assets/config/demo --output ../../tmp/demo-upgraded
    cp -R tmp/demo-upgraded/. assets/config/demo/ && rm -rf tmp/demo-upgraded
    pnpm --filter @eudiplo/cli assets:sync
  6. Add tests for the migration step (valid transformation, source and target validation, required input, running the upgrade twice) in packages/eudiplo-config-format and, for CLI behavior, apps/cli/test/config-upgrade.test.ts.

  7. Run the checks CI runs:

    pnpm schemas:check-contract # current DTOs match the committed schemas and snapshots
    pnpm schemas:check # bundled snapshots are in sync
    pnpm schemas:check-history origin/main # no snapshot of a release was changed
    pnpm schemas:check-ids # every snapshot has its eudiplo.dev $id and resolvable references
  8. Commit schema, snapshot, generated files, tests and documentation together, and describe the change in the upgrade guide of the next major: files exported by the new release cannot be imported into older ones. A migration step that rewrites the spec or metadata of a KeyChain document, or of a Client document with "secret": "!generate", makes such a document differ from the one last applied, so the next upsert or replace import applies it once more: CA keys get a new signing key, regenerate creates new key material and the client gets a new secret, which a startup import does not show. Say so in that guide too. A step that returns spec and metadata unchanged keeps them as they are.

schemas:snapshot without a resource name checks and snapshots every current resource. Running schemas:snapshot alone is not enough: schemas:check-contract fails when a DTO changed but the version was not bumped.

Immutable snapshots​

Files under schemas/v*/ are publication artifacts once a release ships them. Never edit or delete one; CI compares the snapshots of the latest release tag before the pull request base with the working tree (scripts/check-published-schemas.mjs) and fails on any change. A snapshot that no release has shipped yet can still change before the release, for example to rename a value; files written by a build of main in between may then need editing before they import. Each resource schema contains its dependencies in $defs, so one resource can move to a new version while the others stay. The schema's own $schema is the JSON Schema dialect; its $id is the public EUDIPLO URL that files reference.

Publishing​

eudiplo.dev serves the schemas at eudiplo.dev/schemas/…. The site is built in its own repository, EUDIPLO/website: its build checks out this repository, copies every schemas/v*/ snapshot, verifies the schema ids and references (the same checks as pnpm schemas:check-ids) and writes /schemas/index.json. Its _headers allows cross-origin reads and sets the JSON Schema content type; its 404.html keeps unknown versions from falling back to the home page.

Pushes to main here deploy the website preview with the schemas of that commit. A release here, or Versioned Release with deploy_site_only, deploys production with the schemas of the deployed commit. The website repository also deploys production on its own pushes and once a month, built from the head of main here. A version added on main can therefore go live before the release that introduces it; until that release ships it, the snapshot may still change (see Immutable snapshots). The website only builds from commits on main, and production always takes the CLI installer (apps/cli/install.sh) from the latest release.