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:
| Resource | Version | Change |
|---|---|---|
IssuanceConfig | v2 | Optional offerLifetimeSeconds. A v1 file is a valid v2 file. |
IssuanceConfig | v3 | Optional verifierKeyPem (PEM public key) in walletProviderTrustLists entries. A v2 file is a valid v3 file. |
IssuanceConfig | v4 | Optional walletAttestationStatusCheckMode on the issuance configuration and its authorization servers. A v3 file is a valid v4 file. |
IssuanceConfig | v5 | Optional entity configuration fields in federation (entityTypes, authorityHints, entityKeyChainId, entityConfigurationLifetimeSeconds, trustMarks, entityMetadata, includeTrustChain). A v4 file is a valid v5 file. |
IssuanceConfig | v6 | The 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. |
IssuanceConfig | v7 | registrationCertificate.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. |
CredentialConfig | v2 | x509 as frameworkType of schemaMeta.trustedAuthorities entries. A v1 file is a valid v2 file. |
CredentialConfig | v3 | fields[].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). |
CredentialConfig | v4 | config.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). |
KeyChain | v2 | Optional type (standalone, internalChain). A v1 file is a valid v2 file; a bare key chain file with type is read as v2 (bareFileVersion). |
KeyChain | v3 | Usage type federation. A v2 file is a valid v3 file; a bare key chain file with usage type federation is read as v3. |
KeyChain | v4 | Usage type authorizationServer. A v3 file is a valid v4 file; a bare key chain file with usage type authorizationServer is read as v4. |
KeyChainDefaults | v2 | Optional authorizationServer entry. A v1 file is a valid v2 file; a bare key-chain-defaults.json with the entry is read as v2 (bareFileVersion). |
Client | v2 | The roles audit:read, sessions:read, credentials:status and keys:manage. A v1 file is a valid v2 file. |
KmsConfig | v2 | Optional 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). |
Tenant | v2 | Optional 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. |
Tenant | v3 | defaultKeyChains 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. |
Tenant | v4 | defaultKeyChains moves to the new resource KeyChainDefaults (key-chain-defaults.json, v1); the v3 → v4 step drops it with the warning DEFAULT_KEY_CHAINS_MOVED. |
PresentationConfig | v2 | registration_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. |
PresentationConfig | v3 | DCQL 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. |
PresentationConfig | v4 | Optional 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). |
PresentationConfig | v5 | registration_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. |
TrustList | v2 | Entity 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 resources | v1 |
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.
-
Change the backend schema of the resource and increment its
versioninCONFIG_FORMATS. -
Add exactly one step from the previous version to
CONFIG_MIGRATIONSin the same module.migrate(spec, metadata)returns the newspec, optionally newmetadata, andissues:warningfor lossy but automatic changes,required-inputwhen a user must decide. Keep the resource identity.presentationConfigV1ToV2is the reference. -
If stored data must change as well, add a database migration (Backend architecture).
-
Regenerate the schemas and create the snapshot of the new version:
pnpm gen:api # current schemas in schemas/*.schema.jsonpnpm schemas:snapshot PresentationConfig # writes schemas/v<N>/…; never overwrites an existing filepnpm schemas:sync # bundles schemas/v*/ into the config-format packagepnpm --filter @eudiplo/cli assets:sync # copies schemas and templates into the CLI -
Bring the bundled demo tenant to the new version.
eudiplo init --demo-tenantandeudiplo config tenant create --template democopyassets/config/demo, so a file there that is behind failseudiplo config upgrade --checkin a fresh project. The CLI testgenerates configuration that needs no upgrade(apps/cli/test/runtime.test.ts) fails until you upgrade it from the repository root (devruns inapps/cli, and the--outputfolder must not exist yet):pnpm --filter @eudiplo/cli dev config upgrade ../../assets/config/demo --output ../../tmp/demo-upgradedcp -R tmp/demo-upgraded/. assets/config/demo/ && rm -rf tmp/demo-upgradedpnpm --filter @eudiplo/cli assets:sync -
Add tests for the migration step (valid transformation, source and target validation, required input, running the upgrade twice) in
packages/eudiplo-config-formatand, for CLI behavior,apps/cli/test/config-upgrade.test.ts. -
Run the checks CI runs:
pnpm schemas:check-contract # current DTOs match the committed schemas and snapshotspnpm schemas:check # bundled snapshots are in syncpnpm schemas:check-history origin/main # no snapshot of a release was changedpnpm schemas:check-ids # every snapshot has its eudiplo.dev $id and resolvable references -
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
specormetadataof aKeyChaindocument, or of aClientdocument with"secret": "!generate", makes such a document differ from the one last applied, so the nextupsertorreplaceimport applies it once more: CA keys get a new signing key,regeneratecreates 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 returnsspecandmetadataunchanged 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.