Skip to content

Spring Boot ​

The Spring Boot starters add Datum's server side to your own application: the form definition served by id, submissions validated by the same program the page runs, the form and builder assets, PDF render, fill, sign and verify, an RFC 3161 timestamp server and passkey-signed submissions. Every route is off until you switch it on, and who may call it is your Spring Security configuration, not a Datum policy. The server hosts page compares the hosts.

Requirements ​

The group id is io.github.stephenott. Java 17 or newer, Spring Boot 4, Spring MVC or WebFlux. The starters bring no web stack, so add spring-boot-starter-webmvc or spring-boot-starter-webflux yourself. On JDK 24 and newer the JVM wants native access for the sandbox runtime: add Enable-Native-Access: ALL-UNNAMED to the jar's manifest, which Spring Boot's repackaging keeps, or start the JVM with --enable-native-access=ALL-UNNAMED. The artifacts are not on Maven Central yet, so build and install the reactor under integrations/jvm first (mvn install from that folder, after the browser assets are built).

Dependencies ​

Import the BOM once, then add the starter you need.

xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.stephenott</groupId>
      <artifactId>datum-bom</artifactId>
      <version>${datum.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>io.github.stephenott</groupId>
  <artifactId>datum-spring-boot-starter-submissions</artifactId>
</dependency>
StarterUse it for
datum-spring-boot-starter-submissionsThe form is on your page and the server validates what it submits
datum-spring-boot-starter-uiThe same, and the server also serves the form and builder assets and the page glue
datum-spring-boot-starter-pdfPDF render, fill, sign and verify
datum-spring-boot-starter-timestampAn RFC 3161 timestamp server, standalone
datum-spring-boot-starter-webauthnPasskey ceremonies and signed-submission verification

The smallest application ​

Put the form definition on the class path as src/main/resources/datum/forms/intake.json; its id is its key. Then supply the one thing the starter leaves to you, what to do with an accepted submission.

java
@SpringBootApplication
public class Application {

    public static void main(String[] args) { SpringApplication.run(Application.class, args); }

    @Bean SubmissionHandler handler(Submissions submissions) {
        return accepted -> {
            String id = submissions.save(accepted.formKey(), accepted.submissionKey(),
                accepted.canonicalDocument(), accepted.digest());
            return new SubmissionReceipt(id, "REF-" + id, null);
        };
    }
}

Submissions stands for your own storage. Without a handler bean the default logs the form and a digest, stores nothing and warns at start. Store under a unique key on the form and submissionKey(), because a retried attempt may reach the handler twice.

Switching routes on ​

A starter on the class path maps nothing. Each route group has a property, and a route that is off answers the framework's own 404.

yaml
datum:
  web:
    api:
      endpoints:
        submissions: true
        validate: true
        definition: true

The log lists what is on at start, under the logger datum.web.

Paths sit under datum.web.api.path (default /api), except the assets (datum.web.assets.path, default /datum/assets), the timestamp server (datum.tsa.path, default /tsa) and the passkey routes (datum.webauthn.path, default /api/webauthn).

PropertyMaps
datum.web.api.endpoints.submissionsPOST /submissions
datum.web.api.endpoints.validatePOST /submissions/validate
datum.web.api.endpoints.definitionGET /forms/{key}/definition, GET /forms/{key}/translations
datum.web.api.endpoints.data-sourcesGET /data-sources/{id}
datum.web.api.endpoints.testPOST /submissions/test, the dry run
datum.web.api.endpoints.inspectPOST /inspect
datum.web.api.endpoints.pdf, .fill, .sign, .verifyPOST /pdf, /pdf/fill, /pdf/sign, /pdf/verify
datum.web.api.endpoints.certificateGET /server/certificate
datum.web.assets.enabledThe bundles and datum-host.js under /datum/assets
datum.builder.enabledPOST /forms, PUT /forms/{key}, PUT /forms/{key}/translations, and the builder files
datum.tsa.enabledPOST /tsa, GET /tsa/certificate, GET /tsa/certificates
datum.webauthn.enabled/api/webauthn/*, with datum.webauthn.rp-id, rp-name and origins

POST /submissions/validate checks a journey or one page of it. The body is { document, scope, pageId? }: scope is required and is journey or page, and pageId goes with page only. Anything else is a 400. The verdict is a 200 { accepted, errors, notes? }. errors holds only what blocks, and warnings and info go in notes, which is left out when empty. A run that fails is not a verdict, so it is never a 422. Both routes answer it with a 503 and the run's code: wasm.execution_error, outcome_too_large, or definition.tooDeep when the form itself nests too deep. The other 503s are server.busy, server.unavailable and validator_unavailable. Only server.busy carries Retry-After, because retrying the others does not help. The PDF routes and POST /inspect answer a failed run the same way. A 422 always means the answers were judged and refused. The full shapes are on the wire.

An error body is { errors: [ { field?, code, message? } ] }. field is there only when the error names a component, so a form-level error carries none. message is the sandbox's own wording for a finding, sent as it came, on a check's 200 and on a submission's 422. A message that a hook gave belongs to the finding that hook raised, and it never replaces the sandbox's.

Every property, with its default and bounds, is on Spring Boot properties. The ones met most often: datum.forms.locations (default classpath:/datum/forms/*.json), datum.web.api.max-body-size (1MB), datum.web.api.problem-details (RFC 9457 errors), datum.runtime.validation.time-limit (5s) and memory (32MB), datum.host.time-zone, and datum.web.throttle.limit (60 per 1m). A value that cannot work stops the start and names the property. datum.enabled=false removes the beans and the runtime too.

Beans you bind ​

Each of these is optional and replaces its default. The routes, bodies and codes they take part in are on the wire.

BeanWhat it does
SubmissionHandlerStores the accepted submission and returns the receipt
FormDefinitionRepositoryWhere forms live; the default is read-only over datum.forms.locations
DefinitionSnapshotStore, TranslationCatalogStore, DataSourceProviderThe versions a submission is judged against, by hash; the host's translation catalogue for a form; option lists a form loads
SubmissionThrottle, SubmissionIdempotencyStoreOne limit across instances; answering a retried attempt with its first receipt
PdfSigner, PdfFonts, PdfTemplateSourceThe PDF seal key, fonts and template bytes
Timestamper, PdfTrustPolicyWhere the PDF seal gets its timestamps; which anchors, revocation checking and validation time decide that a signer is trusted
TsaKeyMaterial, TsaSerialAllocator, TsaClientStoreThe timestamp server's signing key, its serial numbers and the clients allowed to ask
PasskeyRepository, PasskeyUseStore, PasskeySubjectResolver, PasskeyThrottleStored passkeys, the replay guard, who a request is, and the limit on challenges and registrations
ErrorTranslatorTurns an exception Datum does not know into an answer; asked in bean order before the built-in mapping
HostContextProviderThe values the form's host. names read, worked out from the request; see the host context
DatumStartupCheckA note the host says once at start
SandboxDecorator, PdfKernelDecoratorWrap the sandbox or the PDF program the runtime built, for instrumentation

The stores of the timestamp server and passkeys refuse to start in memory unless datum.tsa.allow-memory-stores or datum.webauthn.allow-memory-stores acknowledges one instance. Server hosts lists everything that has to be shared when there is more than one.

With a DataSource and spring-jdbc the stores are SQL. Scripts for H2, PostgreSQL and MySQL ship under META-INF/datum/db/migration/{vendor} and work with Flyway or Liquibase. datum.jdbc.initialize-schema is embedded by default, which makes the tables only in an in-memory database; set never in production. Mark a data source @DatumDataSource when the application has several. Signing keys come from a Spring Boot SSL bundle named in datum.pdf.signing.ssl-bundle or datum.tsa.signer.ssl-bundle.

Hooks, in order ​

Every capability runs a request through the same kinds of hook. *Customizer beans run before the engine or the store is asked and may adjust a draft or refuse. *Validator beans run after the engine answered and may add errors or warnings. One handler does the effect, and Spring events follow it and never veto.

A submission goes through SubmissionPreCheck (anti-spam, quotas, per-form access), then HostOptionsCustomizer, SandboxRulesProvider and SandboxContextContributor, then your HostContextProvider, then the sandbox, then SubmissionSignatureCheck, then SubmissionValidator, then your handler. Customizers each see what the one before left, and the first refusal stops the rest. Validators all run, so every error is reported at once. Beans with equal @Order keep no promised order, so declare @Order where position matters.

Each capability has its own hooks, all of the same two kinds:

CapabilityCustomizers (before)Validators (after)
SubmissionsSubmissionPreCheck, HostOptionsCustomizer, SandboxRulesProvider, SandboxContextContributor, SubmissionSignatureCheckSubmissionValidator
FormsDefinitionCustomizer, on the public copy on its way to a fillernone
BuilderBuilderSaveCustomizer, before the kernel checks a saveBuilderSaveValidator, after
PDFPdfRequestCustomizer, which adjusts env, options, hostContext, attachments and fontsPdfResultValidator, which judges the PDF before it leaves and, when the server seals, before the seal
Timestamp serverTimestampRequestCustomizer: refuse a client, choose a policy among the accepted ones, state another accuracynone
PasskeysRegistrationCustomizer, at the challenge and at the registration; SignatureCheckCustomizer, which can only tighten a form's signature checkRegistrationValidator, after the ceremony verified a passkey and before it is stored

A pre-check refuses by returning PreCheckDecision.Reject with a code and a message, answered 403 unless it says otherwise. Any other hook refuses with a HookRefusedException: forbidden answers 403, conflict 409 and invalid 422, with an errors body of field, code and message. Listen to an event with @EventListener; a failing listener is logged and never changes the answer. The events are SubmissionValidatedEvent, SubmissionRejectedEvent, SubmissionThrottledEvent, SubmissionRedeliveredEvent, JourneyCheckedEvent, SubmissionSignatureVerifiedEvent, FormDefinitionSavedEvent, PdfRenderedEvent, PdfVerifiedEvent, TimestampIssuedEvent, TimestampRefusedEvent, PasskeyRegisteredEvent, PasskeyRevokedEvent, DatumRuntimeReadyEvent and SandboxRunInterruptedEvent.

The host context ​

A rule can read a fact about the visit, such as host.role = "admin". The page's own hostContext is only for display: a client can set it to anything, and a submission does not carry it. The server works the values out itself. Declare one HostContextProvider bean that reads the request, for example the signed-in person:

java
@Bean
HostContextProvider hostContext() {
    return request -> {
        if (!(request.submission().principal() instanceof Authentication auth)) {
            return Optional.empty();
        }
        boolean admin = auth.getAuthorities().stream().anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN"));
        return Optional.of(Map.of("role", admin ? "admin" : "user"));
    };
}

It is asked once for each submission, journey check, dry run and PDF. request.submission() also has the headers and the client address, and request.formKey() says which form it is. Nothing in the request body is ever read for it.

Empty means no context. Rules that read host. are then left unjudged, as before: a field shown only to some people is not required. A map, even an empty one, is a context: every such rule is judged, and a name it does not hold has no value. A provider that throws, or returns something that is not plain JSON data within 64 levels, refuses the request with 503 server.unavailable, runs nothing and logs the cause. A retry of a submission already accepted keeps its first answer. Two HostContextProvider beans stop the application at start.

Securing the routes ​

With spring-boot-starter-security on the class path, DatumRequestMatchers (servlet) and DatumExchangeMatchers (WebFlux) give your filter chain one matcher per capability: formsRead(), builderReads(), builderWrites(), dataSources(), submissions(), validate(), dryRun(), inspect(), pdf(), pdfVerify(), passkeys(), tsa(), assets() and all().

java
@Bean
SecurityFilterChain chain(HttpSecurity http, DatumRequestMatchers datum, DatumSecurityResponses responses) throws Exception {
    return http
        .authorizeHttpRequests(requests -> requests
            .requestMatchers(datum.builderWrites(), datum.builderReads(), datum.dryRun(), datum.inspect()).hasRole("EDITOR")
            .requestMatchers(datum.formsRead(), datum.submissions(), datum.validate(), datum.assets()).permitAll()
            .anyRequest().authenticated())
        .httpBasic(Customizer.withDefaults())
        .exceptionHandling(exceptions -> exceptions
            .defaultAuthenticationEntryPointFor(responses.authenticationEntryPoint("Basic realm=\"forms\""), datum.all())
            .defaultAccessDeniedHandlerFor(responses.accessDeniedHandler(), datum.all()))
        .build();
}

DatumSecurityResponses (DatumServerSecurityResponses on WebFlux) answers a refusal on Datum's routes as JSON, 403 access.denied or 401 unauthorized. Where the form is in the body of a request, a matcher cannot see it, so refuse one form to one person in a SubmissionPreCheck, which receives the form key and the principal. Without a security chain every route that is on is open, and the start logs a warning when the builder writes, the passkey routes or the timestamp server would be.

Behind a proxy set server.forward-headers-strategy so the throttle sees the client address. responses.recipes() has the cookie CSRF setup the page glue reads.

The builder write endpoints ​

datum.builder.enabled=true on the UI starter serves the builder and three write routes: POST /api/forms, PUT /api/forms/{key} and PUT /api/forms/{key}/translations, plus the author's copy of a form at GET /api/forms/{key}/definition?public=false. A save is checked by the sandbox kernel before it is stored, and a save made against an out-of-date version is refused with 409 form.outdated. The request and reply bodies, headers and codes are on the wire. Secure builderWrites() and builderReads(), because the author's copy of a form includes its server-secret rules. The default repository is read-only, so supply a FormDefinitionRepository that can save, or a save answers 501 forms.readOnly. Limit the size of a definition with datum.builder.max-definition-size.

Serving the form from the host ​

datum.web.assets.enabled serves host.json, the page glue datum-host.js and the bundles under the build id. Server hosts shows the page code and lists every DatumHost method.

Drafts ​

The starters do not serve draft routes. A server: draft store calls four routes you write yourself; they are described on Drafts.

Sealing PDFs and timestamps ​

The server seals the PDFs it issues with its own key. The key comes from a Spring Boot SSL bundle.

yaml
spring:
  ssl:
    bundle:
      jks:
        pdf-seal:
          keystore: { location: file:/etc/datum/seal.p12, password: "${SEAL_PASSWORD}", type: PKCS12 }
          key: { alias: seal, password: "${SEAL_PASSWORD}" }
datum:
  pdf:
    signing:
      ssl-bundle: pdf-seal
    seal:
      enabled: true
      timestamp: true
PropertyDoes
datum.pdf.signing.ssl-bundleThe bundle holding the seal key and its chain. seal.enabled without a key is a start-up warning.
datum.pdf.seal.enabled, .layouts, .certify, .reason, .location, .visibleTurn the seal on, limit it to some layouts, and set what the signature says.
datum.pdf.seal.timestampAsk for a timestamp token over each seal. It needs a timestamp source; without one the start warns.
datum.pdf.signing.tsa.url, .bearer-token, .basic-user, .basic-password, .ssl-bundle, .policyUse a timestamp server you name.
datum.pdf.signing.trust-anchors, .retired-certificatesAnchors the verify route builds a chain to, and the certificates the seal key replaced.
datum.pdf.seal.posted-answersSeal the PDFs of posted, unstored answers with the real key. Off, a throwaway test certificate seals them.

With datum.pdf.signing.tsa.url unset, the seal uses the in-process timestamp authority, which exists only when the timestamp starter is on the class path and datum.tsa.enabled is true. The timestamp server needs its own key (datum.tsa.signer.ssl-bundle) and a policy, and decides who may ask with datum.tsa.access: clients (the default) requires a client key, kept as a SHA-256 in datum.tsa.clients or the datum_tsa_client table, and open lets anyone ask within the flood limits. Every property is on Spring Boot properties.

Requiring a passkey signature ​

With the passkey starter and datum.webauthn.enabled=true, a form can require the person to sign with a passkey. Set the site's rp-id and origins, a datum.webauthn.secret of at least 32 bytes, and then per form:

yaml
datum:
  webauthn:
    enabled: true
    rp-id: example.org
    origins: [https://forms.example.org]
    forms:
      intake:
        mode: required

mode is off, optional or required; unavailable says whether a browser that cannot sign is refused or accepted unsigned. The other per-form keys (scope, placement, user-verification, statement, verify) and the site settings are on Spring Boot properties. The routes are on the wire, and the page side is on Signing.

Observability ​

Expose what you need, for example management.endpoints.web.exposure.include=health,info,datum. The datum health component has one member per check, with runtime the one a readiness group should use. /actuator/datum reports the runtime and, on POST, rechecks it without a restart. Meters include datum.runs, datum.submissions and datum.throttled. With an ObservationRegistry Datum reports datum.submission, datum.sandbox.run, datum.pdf.run, datum.pdf and datum.tsa.issue, and no answer, byte or digest is ever a tag. With springdoc every enabled route is documented, one group per capability, such as datum-forms, datum-submissions and datum-pdf.

Testing ​

Add datum-spring-boot-starter-test in test scope. @AutoConfigureDatum gives a test context with a fake runtime in place of the sandbox, and fixture forms with testForms = true. DatumMockMvc and DatumWebTestClient are the request helpers.

To check a running deployment against the wire contract, run datum-host-check from the conformance suite, which needs no JDK. The same checks ship as JUnit contracts in the datum-host-tck module, which reads the same datum.tck.* settings.

sh
datum-host-check --endpoint https://forms.example --capabilities submissions,submissions-test,forms,assets

Every property is on Spring Boot properties, and every route on The wire.

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