Skip to content

Spring Boot properties ​

Every datum.* property the Spring Boot host reads, with its default and what it does. Set them in application.yml or application.properties, as environment variables or as command-line arguments, like any Spring Boot property.

yaml
datum:
  web:
    api:
      max-body-size: 2MB
      endpoints:
        submissions: true
        validate: true
  runtime:
    validation:
      time-limit: 5s
  forms:
    locations: classpath:/datum/forms/*.json
  tsa:
    enabled: true
    signer:
      self-signed: true

Spring Boot's relaxed binding applies. datum.web.api.max-body-size can also be written datum.web.api.maxBodySize, or as the environment variable DATUM_WEB_API_MAXBODYSIZE. Durations take the Spring forms (5s, 10m, PT1H), sizes take KB, MB and GB, and an enum takes its word in any case.

A value that cannot work stops the start and names the property, for example datum.web.throttle.limit is 0; it must be at least 1.. A few budgets are clamped instead: the message is logged once at WARN and the nearest allowed value is used. Each section below says which of the two applies.

The route switches are described on Spring Boot; the paths they open are listed on the wire.

Master switch and web ​

datum.enabled and everything under datum.web.*.

PropertyDefaultMeaning
datum.enabledtrueMaster switch. With false no Datum auto-configuration applies.
datum.web.api.path/apiWhere the JSON endpoints live. A leading slash is added and a trailing one removed; blank means the default.
datum.web.api.max-body-size1MBThe largest request body a JSON endpoint reads, counted on the raw stream before parsing. It must be at least 1B. The runtime then keeps it between 16KB and 64MB and logs a warning when it moves the value.
datum.web.api.problem-detailsfalseAnswer errors as RFC 9457 problem details (application/problem+json) with the same codes.
datum.web.api.busy-retry-after5sThe Retry-After carried by a 503 server.busy answer. Whole seconds from 1s to 1h; a fraction or a value outside that stops the start.
datum.web.api.endpoints.<key>offOne switch per endpoint, listed in the next table. Every endpoint is off until its key is true; a key that is not set is off.
datum.web.assets.enabledfalseServe the form and builder bundles from the classpath under the versioned assets path.
datum.web.assets.path/datum/assetsWhere the assets are served. Files live at {path}/{buildId}/.... Same normalisation as the API path.
datum.web.assets.cache-period365dThe max-age of the immutable asset answers. Not negative.
datum.web.assets.omit-featuresnoneA list of feature tokens whose files answer 404, added to what the build already left out.
datum.web.csrf.header-nameX-XSRF-TOKENThe request header the page glue sends the CSRF token in. The token itself is Spring Security's.
datum.web.csrf.cookie-nameXSRF-TOKENThe cookie the page glue reads the token from.
datum.web.csrf.meta-name_csrfThe name of the page meta tag the page glue reads the token from.
datum.web.throttle.enabledtrueThe built-in in-memory throttle on submission, validation, dry-run, PDF and passkey-registration routes. It is not created when the application supplies its own SubmissionThrottle bean.
datum.web.throttle.limit60Attempts allowed per window for one key. At least 1.
datum.web.throttle.window1mThe span the limit counts over. Longer than zero.
datum.web.throttle.byip, formWhat makes a key, in addition to the route kind: ip, form and principal (the signed-in user; user is accepted as a synonym). Any other word stops the start.
datum.web.throttle.limits.<kind>unsetA limit for one route kind that differs from limit. The kinds are submit, validate, test, pdf and register; another name stops the start, and each value is at least 1. Read only by the built-in throttle.
datum.web.throttle.max-keys10000The most windows the built-in throttle holds, from 16 to 10000000. When it is full the expired ones go first, then the oldest sixteenth.
datum.web.openapi.enabledtrueRegister Datum's springdoc groups when springdoc is on the classpath.
datum.web.openapi.group-prefixdatum-The prefix of the group names (datum-forms, datum-submissions and so on).

The built-in throttle counts in memory, so each application instance counts on its own. Behind a proxy, enable Spring's forwarded-header handling so the client address is the real one.

The endpoint switches ​

datum.web.api.endpoints.<key> takes these 11 keys. Paths are under datum.web.api.path.

KeyRoute
submissionsPOST /api/submissions, the full receive pipeline
validatePOST /api/submissions/validate, a page's or a journey's check
testPOST /api/submissions/test, the dry run
inspectPOST /api/inspect, the inspection of a definition
definitionGET /api/forms/{key}/definition and GET /api/forms/{key}/translations
data-sourcesGET /api/data-sources/{id}
pdfPOST /api/pdf
fillPOST /api/pdf/fill
signPOST /api/pdf/sign
verifyPOST /api/pdf/verify
certificateGET /api/server/certificate

The other routes have their own switches: datum.builder.enabled (POST /api/forms, PUT /api/forms/{key}, PUT /api/forms/{key}/translations), datum.tsa.enabled (POST /tsa, GET /tsa/certificate, GET /tsa/certificates) and datum.webauthn.enabled (the passkey routes under /api/webauthn).

Runtime ​

datum.runtime.*: which engine runs the sandbox and the PDF program, how the runtime starts and stops, and the budgets of the two programs. Budgets, slots and waits are clamped to their bounds with a logged warning. warm-up-runs, shutdown-grace, stop-grace and max-strays are rejected when negative.

PropertyDefaultMeaning
datum.runtime.engineendiveThe id of the engine that runs the programs. endive (in-process) is the only one shipped. An id no engine on the class path has stops the start and lists the engines found. Not read when the application supplies its own ProgramRuntime bean.
datum.runtime.fail-fasttrueStop the application context when the runtime cannot prove its programs at start. With false the application starts, health reports DOWN with the reason, and every run answers 503 until a recheck passes.
datum.runtime.warm-up-runs3Smoke runs made at start to warm the runtime up. 0 for none; negative stops the start.
datum.runtime.shutdown-grace10sHow long a shutdown waits for runs in flight before it cancels them. Not negative.
datum.runtime.startup-budget30sThe wall time of the proof runs at start and at a recheck (the version probes, the smoke run and the warm-up runs). A run gets the longer of this and its own budget. Whole seconds from 1s to 5m.
datum.runtime.verify-max-bytes20MBThe largest PDF the verify route reads; over it the answer is 413. From 1MB to 100MB. The route needs datum.web.api.endpoints.verify.
datum.runtime.stop-grace5sHow long a run that was stopped (at its time budget or by a shutdown) is given to end and close its instance before its output is read as it stands. Raise it on a slow host. Not negative.
datum.runtime.max-strays0How many stopped runs may outlive their grace before new runs are refused. 0 means one per CPU the JVM may use, at least two. Negative stops the start.
datum.runtime.validation.time-limit5sThe wall time of one validation run. Whole seconds, 1s to 60s.
datum.runtime.validation.memory32MBThe linear memory of one validation run, 4MB to 1GB.
datum.runtime.validation.concurrency0Validation runs at once, up to 64. 0 is one per CPU.
datum.runtime.validation.wait2sHow long a validation waits for a free slot before the answer is 503 server.busy. Whole seconds, 0 to 10; 0 refuses at once.
datum.runtime.pdf.time-limit15sThe wall time of one PDF run. Whole seconds, 1s to 300s.
datum.runtime.pdf.memory256MBThe linear memory of one PDF run, 32MB to 4GB.
datum.runtime.pdf.concurrency0PDF runs at once, up to 64. 0 is the smaller of two and the number of CPUs.
datum.runtime.pdf.wait2sHow long a PDF run waits for a free slot before 503 server.busy. Whole seconds, 0 to 10.
datum.runtime.programs.sandboxpackaged programA file: or classpath: resource to run instead of the packaged sandbox program. The version probe still proves it, and the actuator's recheck reads it again.
datum.runtime.programs.pdfpackaged programThe same for the PDF program.

The output size caps of a run are fixed and have no property.

Host options ​

datum.host.*: options the host sets on every validation run. They bind as enums, so a word the sandbox does not read stops the start with Spring's binding error naming the property.

PropertyDefaultMeaning
datum.host.formula-errorsfailWhat a formula that cannot be evaluated does. fail: the run fails. warn: the formula's value is empty and the run goes on.
datum.host.risky-patternsrefuseWhat a regular expression that repeats a repeat does. refuse: the pattern is refused. allow: the pattern runs.
datum.host.time-zoneJVM defaultThe zone today() and the clock-dependent rules read, as a zone id such as America/Toronto. Empty is the JVM's zone; an id that is not a zone stops the start.
datum.host.unknown-fieldsstripWhat an answer the form has no component for does. strip: it is dropped. keep: it is kept. reject: the submission is refused.
datum.host.log-levelwarnHow much of a run's log the program keeps and the host relays: off, error, warn, info or debug.

Submissions ​

datum.submissions.*: settings of the development defaults the submissions module supplies. An application that supplies its own store ignores them.

PropertyDefaultMeaning
datum.submissions.idempotency.memory-size10000How many accepted documents the in-memory idempotency store remembers (used when there is no DataSource and no store bean); past it the oldest is forgotten. From 16 to 10000000, otherwise the start stops.

Forms ​

datum.forms.*: where definitions are read and how they are cached. Values below their minimum stop the start.

PropertyDefaultMeaning
datum.forms.locationsclasspath:/datum/forms/*.jsonSpring resource patterns of the definition files the default repository reads.
datum.forms.snapshots.max-entries500The most snapshots the in-memory store keeps, least recently used out first. At least 1.
datum.forms.snapshots.public-copy-cache-size256The most public copies kept, by definition hash. At least 1.
datum.forms.data-sources.timeout15sHow long one provider call may take. Positive.
datum.forms.data-sources.max-threads16The most provider calls in flight at once; a hung provider can hold this many threads. At least 1.
datum.forms.too-costly-memory300sHow long a definition the sandbox could not check in time is refused without another run. From 1s to 1h.
datum.forms.cache.definitionno-storeThe Cache-Control of a definition answer. Not blank and no line breaks.
datum.forms.cache.snapshotfollows cache.definitionThe Cache-Control of the public copy of a version asked for by hash. Set a cacheable value only when the read routes are unauthenticated: a shared cache may then keep the answer, and the bytes of a public copy can change under the same hash after an upgrade.

Builder ​

datum.builder.*: whether this application is a place where forms are authored. See Spring Boot.

PropertyDefaultMeaning
datum.builder.enabledfalseServe the builder bundle and register the form write endpoints.
datum.builder.max-definition-size1MBThe largest definition a save reads, counted on the raw stream before parsing; over it the answer is 413. From 1B to 64MB.

JDBC ​

PropertyDefaultMeaning
datum.jdbc.initialize-schemaembeddedWhether the Datum modules create their tables when a JDBC store starts. embedded: only in an embedded in-memory database (H2, HSQL, Derby). always: in whatever database the stores use. never: not at all, for an application that runs the shipped scripts with Flyway or Liquibase. A module's script runs only when its first table is missing, so always never creates a table twice.

Bindings ​

datum.bindings.*: which design-system binding each form route is drawn by, and the PDF theme its PDF prints under. The host's configuration says it, never the form's definition.

yaml
datum:
  bindings:
    default: datum
    routes:
      contact: gcds
    catalog:
      gcds:
        label: GC Design System
        pdf-theme: gcds
    pdf-themes:
      gcds: classpath:/pdf/gcds.json
PropertyDefaultMeaning
datum.bindings.defaultdatumThe binding of a route with no override. Blank means datum.
datum.bindings.routes.<form-key>noneThe binding a form key is drawn by.
datum.bindings.catalog.<id>.labelthe idThe name shown where bindings are listed.
datum.bindings.catalog.<id>.pdf-themenoneThe PDF theme the binding suggests; none means the engine's own.
datum.bindings.pdf-themes.<id>noneA resource holding the JSON theme object of a suggested PDF theme.

The catalog starts with the datum binding the bundles carry, which suggests the engine's own PDF look. A PDF of a form carries its binding's PDF theme below the theme of the render call and of the layout.

PDF ​

datum.pdf.*: what the PDF service is built from. An unknown fonts or seal.certify word, or a signing.tsa.timeout under one second, stops the start.

PropertyDefaultMeaning
datum.pdf.enabledtrueWhether the PDF capability is on.
datum.pdf.fontsdefaultThe fonts a request carries unless the caller asks for another pack. default: DejaVu Sans and Sans Bold. standard: five faces (sans, bold, oblique, mono, mono bold). all: all seven faces.
datum.pdf.signing.ssl-bundlenoneThe name of a Spring Boot SSL bundle (spring.ssl.bundle.jks.<name> or .pem.<name>) whose key store holds the server's PDF signing key and chain. The bundle's key.alias and key.password pick and unlock the key.
datum.pdf.signing.retired-certificatesnoneA PEM resource with certificates the server signed with before a rotation; a signature by one verifies as site_retired.
datum.pdf.signing.trust-anchorsnoneA PEM resource of trust anchors; signers and timestamp authorities that chain to one verify as trusted.
datum.pdf.signing.tsa.urlnoneThe URL of a named timestamp server. Empty uses the in-process authority when it is active.
datum.pdf.signing.tsa.timeout10sHow long a whole timestamp request may take. At least 1s.
datum.pdf.signing.tsa.ssl-bundleJDK trustA Spring Boot SSL bundle for the TLS connection to the timestamp server: its trust store checks the server, and its key store, when it has one, presents a client certificate.
datum.pdf.signing.tsa.bearer-tokennoneA bearer token sent in the Authorization header. Never logged.
datum.pdf.signing.tsa.basic-usernoneThe user name for HTTP Basic authentication to the timestamp server.
datum.pdf.signing.tsa.basic-passwordnoneThe password for HTTP Basic authentication. Never logged.
datum.pdf.signing.tsa.policynoneThe reqPolicy object identifier (dotted) every request carries, for a server that issues under several policies. Unset asks for none. Read only with url.
datum.pdf.seal.enabledfalseSeal issued PDFs with the server's key.
datum.pdf.seal.layoutsall layoutsA list of the layouts to seal; empty seals every layout.
datum.pdf.seal.certifynoChangesThe kind of signature. noChanges: certifying, no change allowed afterwards. formFill: certifying, form filling allowed. annotate: certifying, form filling and annotations allowed. none: an approval signature, not a certifying one.
datum.pdf.seal.timestamptrueAsk a timestamp server for a token over the seal, when one is available.
datum.pdf.seal.reasonnoneThe signature's reason.
datum.pdf.seal.locationnoneThe signature's location.
datum.pdf.seal.visibleunsetfalse for an invisible signature; unset or true keeps the default appearance.
datum.pdf.seal.posted-answersfalseSeal the PDFs of posted, unstored answers (POST /api/pdf, /api/pdf/fill, /api/pdf/sign) with the server's key. Off, a throwaway test certificate seals them, so the server's key only vouches for documents the application itself issued.

Timestamp server ​

datum.tsa.*: the RFC 3161 timestamp server. Off by default: without enabled=true the routes answer 404.

PropertyDefaultMeaning
datum.tsa.enabledfalseTurn the timestamp server on.
datum.tsa.path/tsaWhere it answers; /certificate and /certificates hang below it.
datum.tsa.accessclientsWho may ask for a token. clients: a caller with a registered client key. open: anyone, with flood limits still applied per address.
datum.tsa.policythe Datum defaultThe policy object identifier tokens name.
datum.tsa.accepted-policiesnoneFurther policy identifiers a request may ask for with reqPolicy; the token then names the policy asked for. The issuing policy is always accepted. Any other one is refused with unacceptedPolicy.
datum.tsa.accuracy1sThe accuracy tokens state. Whole milliseconds from 0 to 60s; zero states none. A value outside that is clamped.
datum.tsa.max-request-size16KBThe largest request body read. From 1B to 1MB.
datum.tsa.flood.limit1000Tokens allowed per window, per client (per address for open requests). 0 turns the limit off.
datum.tsa.flood.window1hThe span the flood limit counts over; a fixed window. At least 1s.
datum.tsa.flood.failed-keys10Wrong client keys one address may present per hour before it is answered 429 with Retry-After: 3600. From 1 to 10000.
datum.tsa.signer.ssl-bundlenoneThe SSL bundle whose key store holds the server's timestamp signing key and chain. With neither this nor self-signed, every request is answered systemFailure and health is DOWN.
datum.tsa.signer.self-signedfalseMake a throwaway self-signed certificate at start. Development only: tokens verify against no one. Setting it together with ssl-bundle stops the start.
datum.tsa.client-storepropertiesWhere client keys live. properties: the clients list. jdbc: the datum_tsa_client table, which needs a DataSource.
datum.tsa.clientsnoneFor the properties store, the SHA-256 of each client key in lower-case hex, each optionally written label=hash. Keep only the hash, never the key.
datum.tsa.retired-certificatesnoneA list of PEM files (a Spring resource each) of certificates the server signed with before, served by /certificates.
datum.tsa.session-cookies*Cookie names that make a request a browser session's; such a request is refused with 403. The default * refuses a request that carries any cookie. A list of names refuses only those, whatever their case, and * in the list means any.
datum.tsa.allow-memory-storesfalseAcknowledge single-instance use of the in-memory serial allocator. Without a DataSource and the timestamp migration, or your own TsaSerialAllocator bean, the start is refused unless this is true.

Passkeys ​

datum.webauthn.*: passkey registration and passkey-signed submissions. Off by default: without enabled=true the routes answer 404. Unknown members under this prefix stop the start, and so does a word outside a setting's set. Nothing is taken from the request's Host header: until rp-id and origins are set the routes answer 503 signing.not_set_up and health is DOWN.

Site settings ​

PropertyDefaultMeaning
datum.webauthn.enabledfalseTurn passkeys on.
datum.webauthn.rp-idemptyThe relying-party id: the registrable domain passkeys are bound to, such as example.org. Empty means not set up.
datum.webauthn.rp-namethe rp-idThe name the browser shows for the site.
datum.webauthn.originsnoneThe origins a client may write, exactly: scheme, host and port, no path, such as https://forms.example.org.
datum.webauthn.anonymousfalseLet visitors who are not signed in make passkeys and sign.
datum.webauthn.register-at-submittrueLet people register a passkey when they submit a form. The Test context still may when this is false.
datum.webauthn.window600sHow long a signature may take to arrive. Whole seconds, at least one.
datum.webauthn.challenge-ttl300sHow long a registration challenge holds, which bounds the page's whole ceremony. From 10s to 1h.
datum.webauthn.path/api/webauthnThe base path of the endpoints; /challenge, /register and /passkeys hang below it. Must not be empty.
datum.webauthn.passkeyssitesite: a passkey signs for every form. form: only for the one it was made on.
datum.webauthn.secretemptyThe HMAC key of registration challenges: at least 32 bytes, and the same on every instance. Empty makes one at start, which one instance only can use.
datum.webauthn.label-pathemptyThe answer (a value path) that names a visitor's passkey, told to the page.
datum.webauthn.test-rolesnoneRoles, read from the Spring Security authentication (FORM_ADMIN matches ROLE_FORM_ADMIN), that may make a passkey in a form's Test context. Empty: nobody.
datum.webauthn.keep-years0Years signed submissions are kept at least, whatever retention says; 0 lets retention decide. From 0 to 100. For the application's own retention job.
datum.webauthn.resident-keyrequiredThe residentKey requirement a registration asks the authenticator for: required, preferred or discouraged. required gives a passkey the browser can offer without being told which.
datum.webauthn.challenge-skew60sHow far ahead of this server's clock a challenge's issue time may be, for a challenge made on another server whose clock runs ahead. From 0 to 5m.
datum.webauthn.signed-at-skew60sHow far apart the two signing times a signature carries (the result's and the assertion's) may be. From 0 to 10m.
datum.webauthn.anonymous-grace24hHow long an anonymous passkey that signed nothing is kept before the purge removes it. From 1h to 30d.
datum.webauthn.allow-memory-storesfalseAcknowledge single-instance use: the passkey, replay-guard and challenge stores may live in this process's memory. Without it the application refuses to start unless a SQL store is configured, because a replay guard in memory is one per process.

Form defaults ​

These apply to every form. datum.webauthn.forms.<key>.* overrides each per form.

PropertyDefaultMeaning
datum.webauthn.modeoffWhether a form's submissions are signed with a passkey. off: not signed. optional: a visitor may sign. required: a visitor must sign.
datum.webauthn.scopeenvelopeWhat a signature covers. envelope: the whole submission envelope. submission: the submission document. values: the answers only.
datum.webauthn.placementembeddedWhere signatures land, as the page is told (the verifier reads both). embedded: inside the submission. wrapper: wrapping the submission.
datum.webauthn.user-verificationpreferredThe user verification a signature asks for. required: the authenticator must verify the user. preferred: asked for, not demanded.
datum.webauthn.statementemptyThe statement the signer sees and signs; empty for none.
datum.webauthn.verifytrueWhether a signature that cannot be verified refuses the submission. An invalid signature always does.
datum.webauthn.unavailablerefuseWhat a required form does with a submission from a browser without passkeys. refuse: refuse it. accept: accept it unsigned.

Per-form overrides ​

datum.webauthn.forms.<key>.* takes the same seven members as the defaults above, with the same words. A member left unset keeps the default.

PropertyDefaultMeaning
datum.webauthn.forms.<key>.modethe default modeThis form's signing mode: off, optional or required.
datum.webauthn.forms.<key>.scopethe default scopeenvelope, submission or values.
datum.webauthn.forms.<key>.placementthe default placementembedded or wrapper.
datum.webauthn.forms.<key>.user-verificationthe default user-verificationrequired or preferred.
datum.webauthn.forms.<key>.statementthe default statementThe statement the signer sees and signs.
datum.webauthn.forms.<key>.verifythe default verifyWhether a signature that cannot be verified refuses the submission.
datum.webauthn.forms.<key>.unavailablethe default unavailablerefuse or accept.

A form key that contains a dot must be written in brackets, forms[my.form].mode. Written forms.my.form.mode it would be read as a form my with a member form, and the form meant to require a signature would sign nothing.

yaml
datum:
  webauthn:
    enabled: true
    rp-id: example.org
    origins: https://forms.example.org
    forms:
      grant:
        mode: required
        scope: values

MIT licence. Your forms, your data, your keys.