Spring Boot properties
Every datum.* property the Spring Boot host reads, with its default and what it does. Set them in application. or application., as environment variables or as command-line arguments, like any Spring Boot property.
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: trueSpring Boot's relaxed binding applies. datum. can also be written datum., or as the environment variable DATUM_. Durations take the Spring forms (5s, 10m, PT1), 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.. 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. and everything under datum..
| Property | Default | Meaning |
|---|---|---|
datum. | true | Master switch. With false no Datum auto-configuration applies. |
datum. | /api | Where the JSON endpoints live. A leading slash is added and a trailing one removed; blank means the default. |
datum. | 1 | The largest request body a JSON endpoint reads, counted on the raw stream before parsing. It must be at least 1. The runtime then keeps it between 16 and 64 and logs a warning when it moves the value. |
datum. | false | Answer errors as RFC 9457 problem details (application/) with the same codes. |
datum. | 5s | The Retry-After carried by a 503 server. answer. Whole seconds from 1s to 1h; a fraction or a value outside that stops the start. |
datum. | off | One 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. | false | Serve the form and builder bundles from the classpath under the versioned assets path. |
datum. | /datum/ | Where the assets are served. Files live at {path}/. Same normalisation as the API path. |
datum. | 365d | The max-age of the immutable asset answers. Not negative. |
datum. | none | A list of feature tokens whose files answer 404, added to what the build already left out. |
datum. | X-XSRF-TOKEN | The request header the page glue sends the CSRF token in. The token itself is Spring Security's. |
datum. | XSRF-TOKEN | The cookie the page glue reads the token from. |
datum. | _csrf | The name of the page meta tag the page glue reads the token from. |
datum. | true | The 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 Submission bean. |
datum. | 60 | Attempts allowed per window for one key. At least 1. |
datum. | 1m | The span the limit counts over. Longer than zero. |
datum. | ip, form | What 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. | unset | A 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. | 10000 | The 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. | true | Register Datum's springdoc groups when springdoc is on the classpath. |
datum. | datum- | 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. takes these 11 keys. Paths are under datum..
| Key | Route |
|---|---|
submissions | POST /api/, the full receive pipeline |
validate | POST /api/, a page's or a journey's check |
test | POST /api/, the dry run |
inspect | POST /api/, the inspection of a definition |
definition | GET /api/ and GET /api/ |
data-sources | GET /api/ |
pdf | POST /api/ |
fill | POST /api/ |
sign | POST /api/ |
verify | POST /api/ |
certificate | GET /api/ |
The other routes have their own switches: datum. (POST /api/, PUT /api/, PUT /api/), datum. (POST /tsa, GET /tsa/, GET /tsa/) and datum. (the passkey routes under /api/).
Runtime
datum.: 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.
| Property | Default | Meaning |
|---|---|---|
datum. | endive | The 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 Program bean. |
datum. | true | Stop 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. | 3 | Smoke runs made at start to warm the runtime up. 0 for none; negative stops the start. |
datum. | 10s | How long a shutdown waits for runs in flight before it cancels them. Not negative. |
datum. | 30s | The 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. | 20 | The largest PDF the verify route reads; over it the answer is 413. From 1 to 100. The route needs datum.. |
datum. | 5s | How 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. | 0 | How 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. | 5s | The wall time of one validation run. Whole seconds, 1s to 60s. |
datum. | 32 | The linear memory of one validation run, 4 to 1. |
datum. | 0 | Validation runs at once, up to 64. 0 is one per CPU. |
datum. | 2s | How long a validation waits for a free slot before the answer is 503 server.. Whole seconds, 0 to 10; 0 refuses at once. |
datum. | 15s | The wall time of one PDF run. Whole seconds, 1s to 300s. |
datum. | 256 | The linear memory of one PDF run, 32 to 4. |
datum. | 0 | PDF runs at once, up to 64. 0 is the smaller of two and the number of CPUs. |
datum. | 2s | How long a PDF run waits for a free slot before 503 server.. Whole seconds, 0 to 10. |
datum. | packaged program | A 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. | packaged program | The same for the PDF program. |
The output size caps of a run are fixed and have no property.
Host options
datum.: 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.
| Property | Default | Meaning |
|---|---|---|
datum. | fail | What a formula that cannot be evaluated does. fail: the run fails. warn: the formula's value is empty and the run goes on. |
datum. | refuse | What a regular expression that repeats a repeat does. refuse: the pattern is refused. allow: the pattern runs. |
datum. | JVM default | The zone today() and the clock-dependent rules read, as a zone id such as America/. Empty is the JVM's zone; an id that is not a zone stops the start. |
datum. | strip | What an answer the form has no component for does. strip: it is dropped. keep: it is kept. reject: the submission is refused. |
datum. | warn | How much of a run's log the program keeps and the host relays: off, error, warn, info or debug. |
Submissions
datum.: settings of the development defaults the submissions module supplies. An application that supplies its own store ignores them.
| Property | Default | Meaning |
|---|---|---|
datum. | 10000 | How many accepted documents the in-memory idempotency store remembers (used when there is no Data and no store bean); past it the oldest is forgotten. From 16 to 10000000, otherwise the start stops. |
Forms
datum.: where definitions are read and how they are cached. Values below their minimum stop the start.
| Property | Default | Meaning |
|---|---|---|
datum. | classpath:/datum/ | Spring resource patterns of the definition files the default repository reads. |
datum. | 500 | The most snapshots the in-memory store keeps, least recently used out first. At least 1. |
datum. | 256 | The most public copies kept, by definition hash. At least 1. |
datum. | 15s | How long one provider call may take. Positive. |
datum. | 16 | The most provider calls in flight at once; a hung provider can hold this many threads. At least 1. |
datum. | 300s | How long a definition the sandbox could not check in time is refused without another run. From 1s to 1h. |
datum. | no-store | The Cache-Control of a definition answer. Not blank and no line breaks. |
datum. | follows cache. | The 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.: whether this application is a place where forms are authored. See Spring Boot.
| Property | Default | Meaning |
|---|---|---|
datum. | false | Serve the builder bundle and register the form write endpoints. |
datum. | 1 | The largest definition a save reads, counted on the raw stream before parsing; over it the answer is 413. From 1 to 64. |
JDBC
| Property | Default | Meaning |
|---|---|---|
datum. | embedded | Whether 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.: 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.
datum:
bindings:
default: datum
routes:
contact: gcds
catalog:
gcds:
label: GC Design System
pdf-theme: gcds
pdf-themes:
gcds: classpath:/pdf/gcds.json| Property | Default | Meaning |
|---|---|---|
datum. | datum | The binding of a route with no override. Blank means datum. |
datum. | none | The binding a form key is drawn by. |
datum. | the id | The name shown where bindings are listed. |
datum. | none | The PDF theme the binding suggests; none means the engine's own. |
datum. | none | A 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.: what the PDF service is built from. An unknown fonts or seal. word, or a signing. under one second, stops the start.
| Property | Default | Meaning |
|---|---|---|
datum. | true | Whether the PDF capability is on. |
datum. | default | The 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. | none | The name of a Spring Boot SSL bundle (spring. or .pem.<name>) whose key store holds the server's PDF signing key and chain. The bundle's key. and key. pick and unlock the key. |
datum. | none | A PEM resource with certificates the server signed with before a rotation; a signature by one verifies as site_. |
datum. | none | A PEM resource of trust anchors; signers and timestamp authorities that chain to one verify as trusted. |
datum. | none | The URL of a named timestamp server. Empty uses the in-process authority when it is active. |
datum. | 10s | How long a whole timestamp request may take. At least 1s. |
datum. | JDK trust | A 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. | none | A bearer token sent in the Authorization header. Never logged. |
datum. | none | The user name for HTTP Basic authentication to the timestamp server. |
datum. | none | The password for HTTP Basic authentication. Never logged. |
datum. | none | The req object identifier (dotted) every request carries, for a server that issues under several policies. Unset asks for none. Read only with url. |
datum. | false | Seal issued PDFs with the server's key. |
datum. | all layouts | A list of the layouts to seal; empty seals every layout. |
datum. | no | The kind of signature. no: certifying, no change allowed afterwards. form: certifying, form filling allowed. annotate: certifying, form filling and annotations allowed. none: an approval signature, not a certifying one. |
datum. | true | Ask a timestamp server for a token over the seal, when one is available. |
datum. | none | The signature's reason. |
datum. | none | The signature's location. |
datum. | unset | false for an invisible signature; unset or true keeps the default appearance. |
datum. | false | Seal the PDFs of posted, unstored answers (POST /api/, /api/, /api/) 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.: the RFC 3161 timestamp server. Off by default: without enabled=true the routes answer 404.
| Property | Default | Meaning |
|---|---|---|
datum. | false | Turn the timestamp server on. |
datum. | /tsa | Where it answers; /certificate and /certificates hang below it. |
datum. | clients | Who may ask for a token. clients: a caller with a registered client key. open: anyone, with flood limits still applied per address. |
datum. | the Datum default | The policy object identifier tokens name. |
datum. | none | Further policy identifiers a request may ask for with req; the token then names the policy asked for. The issuing policy is always accepted. Any other one is refused with unaccepted. |
datum. | 1s | The accuracy tokens state. Whole milliseconds from 0 to 60s; zero states none. A value outside that is clamped. |
datum. | 16 | The largest request body read. From 1 to 1. |
datum. | 1000 | Tokens allowed per window, per client (per address for open requests). 0 turns the limit off. |
datum. | 1h | The span the flood limit counts over; a fixed window. At least 1s. |
datum. | 10 | Wrong client keys one address may present per hour before it is answered 429 with Retry-After: 3600. From 1 to 10000. |
datum. | none | The SSL bundle whose key store holds the server's timestamp signing key and chain. With neither this nor self-signed, every request is answered system and health is DOWN. |
datum. | false | Make a throwaway self-signed certificate at start. Development only: tokens verify against no one. Setting it together with ssl-bundle stops the start. |
datum. | properties | Where client keys live. properties: the clients list. jdbc: the datum_ table, which needs a Data. |
datum. | none | For 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. | none | A list of PEM files (a Spring resource each) of certificates the server signed with before, served by /certificates. |
datum. | * | 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. | false | Acknowledge single-instance use of the in-memory serial allocator. Without a Data and the timestamp migration, or your own Tsa bean, the start is refused unless this is true. |
Passkeys
datum.: 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. and health is DOWN.
Site settings
| Property | Default | Meaning |
|---|---|---|
datum. | false | Turn passkeys on. |
datum. | empty | The relying-party id: the registrable domain passkeys are bound to, such as example.. Empty means not set up. |
datum. | the rp-id | The name the browser shows for the site. |
datum. | none | The origins a client may write, exactly: scheme, host and port, no path, such as https://forms.. |
datum. | false | Let visitors who are not signed in make passkeys and sign. |
datum. | true | Let people register a passkey when they submit a form. The Test context still may when this is false. |
datum. | 600s | How long a signature may take to arrive. Whole seconds, at least one. |
datum. | 300s | How long a registration challenge holds, which bounds the page's whole ceremony. From 10s to 1h. |
datum. | /api/ | The base path of the endpoints; /challenge, /register and /passkeys hang below it. Must not be empty. |
datum. | site | site: a passkey signs for every form. form: only for the one it was made on. |
datum. | empty | The 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. | empty | The answer (a value path) that names a visitor's passkey, told to the page. |
datum. | none | Roles, read from the Spring Security authentication (FORM_ matches ROLE_), that may make a passkey in a form's Test context. Empty: nobody. |
datum. | 0 | Years 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. | required | The resident requirement a registration asks the authenticator for: required, preferred or discouraged. required gives a passkey the browser can offer without being told which. |
datum. | 60s | How 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. | 60s | How far apart the two signing times a signature carries (the result's and the assertion's) may be. From 0 to 10m. |
datum. | 24h | How long an anonymous passkey that signed nothing is kept before the purge removes it. From 1h to 30d. |
datum. | false | Acknowledge 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. overrides each per form.
| Property | Default | Meaning |
|---|---|---|
datum. | off | Whether a form's submissions are signed with a passkey. off: not signed. optional: a visitor may sign. required: a visitor must sign. |
datum. | envelope | What a signature covers. envelope: the whole submission envelope. submission: the submission document. values: the answers only. |
datum. | embedded | Where signatures land, as the page is told (the verifier reads both). embedded: inside the submission. wrapper: wrapping the submission. |
datum. | preferred | The user verification a signature asks for. required: the authenticator must verify the user. preferred: asked for, not demanded. |
datum. | empty | The statement the signer sees and signs; empty for none. |
datum. | true | Whether a signature that cannot be verified refuses the submission. An invalid signature always does. |
datum. | refuse | What a required form does with a submission from a browser without passkeys. refuse: refuse it. accept: accept it unsigned. |
Per-form overrides
datum. takes the same seven members as the defaults above, with the same words. A member left unset keeps the default.
| Property | Default | Meaning |
|---|---|---|
datum. | the default mode | This form's signing mode: off, optional or required. |
datum. | the default scope | envelope, submission or values. |
datum. | the default placement | embedded or wrapper. |
datum. | the default user-verification | required or preferred. |
datum. | the default statement | The statement the signer sees and signs. |
datum. | the default verify | Whether a signature that cannot be verified refuses the submission. |
datum. | the default unavailable | refuse or accept. |
A form key that contains a dot must be written in brackets, forms[my.. Written forms. it would be read as a form my with a member form, and the form meant to require a signature would sign nothing.
datum:
webauthn:
enabled: true
rp-id: example.org
origins: https://forms.example.org
forms:
grant:
mode: required
scope: values