Submissions and replies
The form on your page shows the basic round trip: the form raises datum-submit, the page delivers the answers and the server's reply goes back in. This page goes deeper into the parts of it that matter when the server is slow, unreachable or strict.
What datum-submit carries
The event fires after the form has validated and locked itself. It fires for a refused submit too, so a listener checks accepted first. Its detail holds:
| Property | What it is |
|---|---|
accepted | Whether the answers passed validation. A listener returns early when it is false: the form shows its own errors. |
submission | The envelope, present when accepted. See The envelope. |
errors | The errors that refused the submit, as the form holds them (see the shape under datum-validated). An accepted submit has none. |
result | The runtime's whole answer: accepted, errors, canonical (the same object as submission), signatures, signed, submission, and handler when a submission handler registered by a plugin threw. A page that wants the signatures reads them here. |
submission | On an accepted submit, a key minted when the attempt started: a version 4 UUID. It is the same for every retry of that attempt, and new for the next one. |
wait | Keeps the form locked until the promise settles. |
signed | Only when the form is signed with signing-placement="wrapper": the document to deliver, the envelope as its payload with the signatures beside it. See Signing. |
trigger | "agent" when an assistant started the submit; absent otherwise. See Assistants. |
agent | When an assistant's tools were ever live on the form: which answers they wrote last. Advisory, kept on the page, and never part of the envelope. |
Deliver detail.. For an unsigned form, and for a form signed with the default embedded placement, that is the envelope; under the wrapper placement it is the wrapper, and the envelope alone would drop the signatures.
The envelope
The envelope is the object the form calls the canonical submission. It has three keys, and the middle one is itself named submission, so the answers are at detail.. In this page the whole object is the envelope and its inner submission key is the submission block.
{
"versionContext": {
"form": { "id": "customer-intake", "version": "1.0.0" },
"client": {
"runtimeVersion": "1.0.0",
"rendererVersion": "1.0.0",
"schemaVersion": "1",
"components": { "text": "1.0.0", "select": "1.0.0" },
"plugins": {}
}
},
"submission": {
"locale": "en",
"values": {
"fullName": "Ada Lovelace",
"billing.street": "1 Main St",
"items": [{ "sku": "A-1" }, {}]
},
"journey": { "id": "apply" }
},
"signatures": [
{ "signature": "MEUCIQ...", "algorithm": "ES256", "signedAt": 1767225600000, "participantId": "applicant" }
]
}| Key | What it holds |
|---|---|
version | The id and version of the definition the answers were given against. A server uses the pair to pick the definition to check them with. |
version | What the browser ran: runtime, renderer and the definition's schema, then components (each component type the form uses, with its version) and plugins (each installed plugin, with its version). |
version | Absent from what a page sends. It appears only where a server stage is part of the submission mode. |
submission. | The language the form was in when it was submitted. |
submission. | The answers, one entry per value path. A nested container's answer is under a dotted path (billing.). A data grid, or any other collection, is one entry holding a list of row objects, a row the person left empty kept as {}, so the server counts the rows the person saw. A key never appears with an undefined value. |
submission. | Only for a form filled through a journey: { "id": ... }. It is the only journey data in the envelope. The pages the person visited are not sent, and a server works the path out again from the answers. |
signatures | Only for an embedded signed submit. Each entry holds signature, algorithm, signed (milliseconds since 1970) and participant, with format, statement and webauthn when the provider sets them. See Signing. |
What a hidden field's answer does in values is described with the field, not here. Presentation-only answers of a journey (the page's own fields) never reach values; presentation returns them on the page.
The canonical form and the digest
Before the envelope is signed, delivered or stored, every object in it has its keys sorted by UTF-16 code unit, at every depth. Lists keep their order. Two envelopes with the same answers therefore serialise to the same text, whatever order the keys were written in.
The sandbox returns that text as canonical, with digest: the lowercase hex SHA-256 of the text's UTF-8 bytes. A host passes the delivered document to the sandbox as document, stores both values, and never serialises the document itself, so the browser and every host name one record by one digest. See Your own server.
A signature covers a different text: the envelope, its submission block or its values alone (the signing-scope), written in the form RFC 8785 defines (JSON Canonicalization Scheme). signatures never enters the signed text, so a verifier gets the same bytes from an embedded or a wrapped document. canonicalize and signed are exported from datum-form. for a page that verifies in the browser; see JavaScript exports.
Holding the form while the server answers
A delivery that takes a moment must not leave the form open to a second press or to edits. Hand the delivery to detail.. The form stays locked, every field, button and the language switcher inert, and a status line reads "Submitting…" with a spinner beside it, until the promise settles. The element reflects the lock as its submitting attribute, so a stylesheet or an observer can see it too.
Two attributes shape the line:
textscarries the page's own wording, per language:{ submitting: { default: "Sending your answers…", locales: { "fr-CA": "Envoi de vos réponses…" } } }.submitting-placementsays where the line goes:top(the default, where the error summary sits),bottombeside the button, or both.
Call wait while the listener is still running, before any await. A listener written async (event) => { await something(); event. calls it too late and it throws. It can also be called again while an earlier promise is still pending, but not with the promise submit() itself returned.
A promise that rejects lifts the lock and is reported as datum-error. What the person sees for the failure is the page's catch. A promise that resolves with a Response whose ok is false, which is what fetch gives for a 500, counts as a failed delivery too: the form unlocks and shows no confirmation.
Calling form. while a submit is in flight joins it and resolves with the same detail. A call that asks for something different (a download after a plain submit), or one made from inside a datum-submit listener, rejects with a busy error.
Timeouts and retries
The form has no timeout of its own. The page sets one on the request, and a signal does it in one line: Abort makes the fetch throw when the server has not answered in five seconds. The catch then calls set with an error of the form's own, and the form unlocks so the person can press Submit again.
That second press starts a new attempt, with a new submission. When the page retries the same delivery itself, it sends the key it already has, unchanged. A server that keeps one record per key then keeps one record however many times the request arrived, which matters when the first request did reach it and only the reply was lost.
The reply, back into the form
| The server | The page calls | The form shows |
|---|---|---|
| Accepted | set | A receipt |
| Rejected a field | set | The message on that field and in the error summary |
| Rejected a row of a data grid | set | The message on that row's field |
| Did not answer in time, or could not be reached | set | An error of the form's own, in the summary |
The full shape of an error and of a notice is on The form element. In brief: placement on a notice lists the ends of the form it is shown at, ["top"], ["bottom"] beside the button, or both. A notice is printed with the form and takes focus. A notice's title, message and detail labels can be a plain string or one worded per language. An error's message and a notice's detail values are plain strings. The next submit clears a notice, and set and set clear them by hand.
A server that reports a warning sends severity: "warning" (or "info") and the error is shown without being treated as blocking. In a journey, the person is moved to the first page holding an error the server reported.
After acceptance
Three things a page commonly does once the server has accepted:
- Show the receipt and leave the answers editable. The notice is all it takes.
- Show the receipt and lock the answers. Set
form.aftermode = "readonly" set. The answers stay as sent and the Submit button is disabled. SettingNotice form.and clearing the notice starts over.mode = "interactive" - Move on. The page navigates, for instance
location., and the form is not seen again.assign("/thanks?ref=" + reply. reference)
A form that needs only a plain confirmation can use the confirmation attribute instead: an accepted delivery shows the form's own notice. It reads the reference from reference (or confirmation, a string or a number) on the value the wait promise resolves with, or on that value's receipt. A fetch resolves with a Response, which carries no reference, so hand wait a promise that resolves with the parsed reply:
form.addEventListener("datum-submit", (event) => {
if (!event.detail.accepted) return;
const delivery = fetch("/api/submissions", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ document: event.detail.signed ?? event.detail.submission, submissionKey: event.detail.submissionKey })
}).then((response) => response.json()); // { "reference": "GC-48213" }
event.detail.waitUntil(delivery);
});The confirmation also keeps the reply's data for print. When the reply is a plain object (or has a receipt object), the confirmation's notice carries it as data, so a printed header or footer can say Reference {{receipt.reference}} (see Print).
The confirmation appears only when the submit was accepted and the delivery did not fail (no promise rejected, no reply with ok: false). It does not appear when the page has set a notice of its own, when an error is standing, or for a download. The title, message and the label of the reference line are the texts keys confirmation, confirmation and confirmation, listed on The form's own words. Datum's server hosts answer an accepted submission with { id, reference, status, digest, handled } and a rejected one with a 422 and { errors: [{ field, code, message }] }, which the page maps into set as component. A page that wants its own receipt calls set instead, and the built-in confirmation never replaces it.
A live example
Submit the form with a name. With the 2 second delay, the form locks and shows the page's own submitting line, then the receipt follows. Choose Never answers and submit again: the page gives up after five seconds, the form unlocks and shows the page's error. Move the submitting line to the bottom, or lock the answers after acceptance, and the code under the example changes with you.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Customer intake</title>
<link rel="stylesheet" href="/datum/datum-form.css">
<script type="module" src="/datum/datum-form.js"></script>
</head>
<body>
<datum-form
id="intake"
src="/forms/customer-intake.json"
language-switcher
></datum-form>
<script type="module">
const form = document.getElementById("intake");
form.dataSources = {
countries: [
{ value: "CA", label: "Canada" },
{ value: "US", label: "United States" },
{ value: "MX", label: "Mexico" }
]
};
// What the form says while the delivery is in flight, per language. Left out, it says "Submitting…".
form.texts = {
submitting: {
default: "Sending your answers…",
locales: { "fr-CA": "Envoi de vos réponses…" }
}
};
// The form locks the moment Submit is pressed and stays locked until the promise handed to
// waitUntil settles. It has no timeout of its own: the signal on the fetch is the timeout.
form.addEventListener("datum-submit", ({ detail }) => {
if (!detail.accepted) return;
detail.waitUntil(deliver(detail.submission, detail.submissionKey));
});
async function deliver(submission, submissionKey) {
try {
const response = await fetch("/api/submissions", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ document: submission, submissionKey }),
signal: AbortSignal.timeout(5000)
});
if (response.ok) {
const { reference } = await response.json();
form.setNotice({
kind: "success",
placement: ["top"],
title: "Application received",
details: [
{ label: "Confirmation number", value: reference }
]
});
return;
}
const { errors } = await response.json();
form.setErrors(errors.map((e) => ({ componentId: e.field, code: e.code, message: e.message })));
} catch (error) {
// The server did not answer in time, or could not be reached.
console.log("gave up:", error.name);
form.setErrors([{ code: "delivery.failed", message: "The form could not be sent. Try again." }]);
}
}
</script>
</body>
</html>Nothing yet.
Next
- The basics of the same round trip: The form on your page.
- Checking the answers on your server: Validation and the sandbox.
- Every attribute and method: The form element.