The engine on its own
<datum-form> is the engine with a face on it. Underneath is a runtime that holds the answers, works the rules out, validates and builds the submission envelope, and none of that needs an element. A test, a script, a shell of your own or a server that wants Datum's rules can use the runtime from JavaScript.
Prefer the element when a person fills the form in. It draws the form and a journey's pages, moves focus to the first error, keeps drafts and loads the optional files on demand. The runtime does none of that: it gives you the answers, the errors, the page a journey is on and the envelope, and drawing and delivering are yours.
The runtime has a file of its own, datum-engine., which defines no element and needs no DOM. It loads the same way in a page, a web worker and Node. datum-form. exports the same runtime beside the element. The names are in JavaScript exports, which this page does not repeat. Datum is pre-release, and the packages below are not published yet: Is Datum released? says what that means for the contracts.
A runtime in a few lines
Import create from datum-engine. and go. Nothing else has to be in place first, so the samples below run as they are in Node. datum-form. needs a DOM when it loads, because it defines the element.
The runtime takes the definition, answers are set by value path, and validate resolves with the errors.
import { createFormRuntime, versionContextFor, EMBED_SUBMISSION_MODE } from "./datum-engine.js";
const definition = {
id: "visit-request", version: "1.0.0", schemaVersion: "1",
root: { id: "root", type: "form", configuration: {}, children: { content: [
{ id: "fullName", type: "text", configuration: { label: "Full name", required: true } },
{ id: "reason", type: "textarea", configuration: { label: "Reason for the visit" } }
] } }
};
const runtime = createFormRuntime(definition);
const before = await runtime.validate();
console.log(before.map((error) => `${error.componentId}: ${error.code}`)); // fullName: required
runtime.setValue("fullName", "Ada Lovelace");
console.log((await runtime.validate()).length); // 0
const result = await runtime.submit(EMBED_SUBMISSION_MODE, versionContextFor(definition));
console.log(result.accepted, result.canonicalSubmission.submission, result.submissionKey);[ 'fullName: required' ]
0
true { locale: 'en', values: { fullName: 'Ada Lovelace' } } 7eff686c-d7cb-43aa-9c85-500e025e8a77submit takes a submission mode and a version context. The element's own pair is EMBED_, which validates and does not sign, and version. An accepted result carries canonical, the envelope, and submission, the attempt's key. Deliver them as { document, submission, as Submissions and replies shows. A refused one has accepted: false and the errors, and neither of those two.
Values from the host, the language and events
Rules that read host. names get them from host, set when the runtime is built or later with set, which works the form out again over the answers held. set throws for a language the form does not declare. events(). hears the runtime's own events. Form holds their names; the same names as plain strings work too.
import { createFormRuntime, FormEventType } from "./datum-engine.js";
const definition = {
id: "visit-request", version: "1.0.0", schemaVersion: "1",
localization: { defaultLocale: "en", supportedLocales: [{ code: "en", label: "English" }, { code: "fr", label: "Français" }] },
root: { id: "root", type: "form", configuration: {}, children: { content: [
{ id: "fullName", type: "text", configuration: { required: true } },
{ id: "badge", type: "text", configuration: { required: true }, rules: { visibleWhen: 'host.role = "staff"' } }
] } }
};
const runtime = createFormRuntime(definition, { hostContext: { role: "visitor" } });
runtime.events().subscribe(FormEventType.COMPONENT_CHANGED, (event) => console.log(event.type, event.data.value));
console.log(runtime.effectiveState("badge").visible); // false
runtime.setHostContext({ role: "staff" });
console.log(runtime.effectiveState("badge").visible); // true
runtime.setValue("fullName", "Ada");
runtime.setLocale("fr");
console.log(runtime.state().locale, runtime.submittableValues());
try { runtime.setLocale("de"); } catch (error) { console.log(error.message); }false
true
COMPONENT_CHANGED Ada
fr { fullName: 'Ada' }
Locale "de" is not supportedsubmittable is what a submission would carry: the answers of fields that are shown, without the ones a rule has hidden. See Rules and formulas for host. and Languages for what a locale changes.
Walking a journey
A form with journeys opens as its journey here too, and the runtime walks it page by page as the element does. journey says which page is shown and where it sits on the path. next is Continue, previous is Back and go jumps to a page already reached. Each resolves to { ok, page: a refusal is a value, never a rejection. The routes pick the next page from the answers, so a page the path does not take is passed over.
journey is your way to your server. Continue calls it for a page that asks for a server check, with the page's request and the envelope over the same answers. Submit on the last page checks every page on the path first.
import { createFormRuntime, versionContextFor, EMBED_SUBMISSION_MODE, FormEventType } from "./datum-engine.js";
const definition = {
id: "benefit-check", version: "1.0.0", schemaVersion: "1",
root: { id: "root", type: "form", configuration: {}, children: { content: [
{ id: "fullName", type: "text", configuration: { label: "Full name", required: true } },
{ id: "children", type: "number", configuration: { label: "Children at home", required: true, min: 0 } },
{ id: "childNames", type: "text", configuration: { label: "Their names" } },
{ id: "email", type: "text", configuration: { label: "Email", required: true } }
] } },
journey: { journeys: [{
id: "apply",
validation: { continue: "page" },
pages: [
{ id: "you", components: ["fullName", "children"], validation: { server: true },
routes: [{ when: "children > 0", to: "kids" }, { to: "contact" }] },
{ id: "kids", components: ["childNames"] },
{ id: "contact", components: ["email"] }
]
}] }
};
// Your way to your server: here it accepts every page.
const journeyServerValidator = async (request, { document }) => {
console.log("check", request.scope, request.pageId, document.submission.values);
return { errors: [] };
};
const runtime = createFormRuntime(definition, { journeyServerValidator });
runtime.events().subscribe(FormEventType.PAGE_CHANGED, ({ data }) => console.log("moved", data.direction, data.toPageId));
console.log(runtime.journeyView().pageId); // you
console.log(await runtime.nextPage()); // refused: the page has errors
runtime.setValue("fullName", "Ada Lovelace");
runtime.setValue("children", 0);
await runtime.nextPage(); // no children: past their page
await runtime.previousPage();
runtime.setValue("children", 2);
await runtime.nextPage(); // kids
await runtime.nextPage(); // contact
runtime.setValue("email", "ada@example.org");
const result = await runtime.submit(EMBED_SUBMISSION_MODE, versionContextFor(definition));
console.log(result.accepted, result.canonicalSubmission.submission);you
{ ok: false, reason: 'validation', pageId: 'you' }
check page you { children: 0, fullName: 'Ada Lovelace' }
moved forward contact
moved back you
check page you { children: 2, fullName: 'Ada Lovelace' }
moved forward kids
moved forward contact
true {
journey: { id: 'apply' },
locale: 'en',
values: { children: 2, email: 'ada@example.org', fullName: 'Ada Lovelace' }
}The page ids are the journey's own. PAGE_ reports each move, and journey gives the path the answers draw now. Nothing here draws a page or follows the address bar: read the view and draw it, as below. To post each check to a Datum host, pass create as journey: see Checking between pages on the server. The settings a page takes are under Journeys.
Drawing it yourself
The runtime is a model. A shell of your own reads it and draws what it likes: the tree from form, each component's state from effective and is, the answers from state()., the problems from errors(). This one prints the form as text.
import { createFormRuntime } from "./datum-engine.js";
const definition = {
id: "visit-request", version: "1.0.0", schemaVersion: "1",
root: { id: "root", type: "form", configuration: { title: "Visit request" }, children: { content: [
{ id: "fullName", type: "text", configuration: { label: "Full name", required: true } },
{ id: "reason", type: "textarea", configuration: { label: "Reason" } }
] } }
};
const runtime = createFormRuntime(definition);
await runtime.validate();
function lines(node, depth = 0) {
if (runtime.effectiveState(node.id)?.visible === false) return [];
const problems = runtime.errors().filter((error) => error.componentId === node.id).map((error) => error.code);
const answer = JSON.stringify(runtime.state().values[node.id] ?? "");
const row = `${" ".repeat(depth)}${node.configuration.label ?? node.id}${runtime.isRequired(node.id) ? " *" : ""} = ${answer} ${problems.join()}`;
return [row, ...Object.values(node.children ?? {}).flat().flatMap((child) => lines(child, depth + 1))];
}
console.log(lines(runtime.formRoot()).join("\n"));root = ""
Full name * = "" required
Reason = ""The engine has a renderer of its own that draws a runtime through a binding, but no file you host exports it. It needs a shadow root and the pieces the element wires, so drawing with Datum's components without the element is not something you can do from the page's side today. Use <datum-form>, and reach its runtime with form. or datum-ready's detail. when you want both.
Validating a submission on a server
The server checks again what the page checked. The @datum/ package is a service for that: register a definition, hand it the envelope and the key, and it answers with a verdict and keeps the record. It judges in the sandbox, the same program the page can run, so the verdicts match. The two functions the HTTP routes need are receive and validate; parse and the response helpers turn a body into a call and a result into a status and body.
import { InMemorySubmissionStore, createSubmissionService, parseValidateRequest, receiveResponse, validateResponse, errorResponse } from "@datum/submissions";
import { createQuickJsValidator } from "@datum/submissions/node";
const definition = {
id: "visit-request", version: "1.0.0", schemaVersion: "1",
root: { id: "root", type: "form", configuration: {}, children: { content: [
{ id: "fullName", type: "text", configuration: { label: "Full name", required: true } }
] } }
};
const validator = await createQuickJsValidator(); // the sandbox, on a worker thread
const service = createSubmissionService({ store: new InMemorySubmissionStore(), validator });
await service.register(definition);
// The two routes, as functions of a parsed JSON body.
async function deliver(body) {
try { return receiveResponse(await service.receive(body, { source: "api" })); }
catch (error) { return errorResponse(error) ?? { status: 500, body: {} }; }
}
async function check(body) {
try { return validateResponse(await service.validate(parseValidateRequest(body))); }
catch (error) { return errorResponse(error) ?? { status: 500, body: {} }; }
}
const envelope = (values) => ({
versionContext: { form: { id: "visit-request", version: "1.0.0" }, client: { runtimeVersion: "1.0.0", rendererVersion: "1.0.0", schemaVersion: "1" } },
submission: { locale: "en", values }
});
console.log(JSON.stringify(await check({ document: envelope({}), scope: "journey" })));
console.log(JSON.stringify(await deliver({ document: envelope({}), submissionKey: crypto.randomUUID() })));
const ok = await deliver({ document: envelope({ fullName: "Ada" }), submissionKey: crypto.randomUUID() });
console.log(ok.status, Object.keys(ok.body));
await validator.dispose();{"status":200,"body":{"accepted":false,"errors":[{"field":"fullName","code":"required"}]}}
{"status":422,"body":{"errors":[{"field":"fullName","code":"required"}]}}
200 [ 'id', 'status', 'digest', 'receipt' ]A check is a 200 whatever the verdict, and a refused delivery is a 422. The envelope the runtime above made is accepted here as it is.
The package is not published yet and its entry points are TypeScript source, so run the file through a TypeScript-aware runner from a checkout. There is a second validator, create, that runs the rules in the calling process with no sandbox. It is for development and tests, and the service logs a warning when it is given one.
The page can run the sandbox too, with wasm on the runtime's config or the wasm attribute on the element: Validation and the sandbox. A server in another language, or one that runs the programs itself, reads Running the programs on your own server. The built-in hosts are in Server hosts.
A PDF from a runtime
datum-pdf. holds the PDF kernel and its fonts. Its render draws a runtime's form as the element's render does: the same bytes for the same answers, language, layout and theme. It runs in Node as well as a page.
import { writeFile } from "node:fs/promises";
import { createFormRuntime } from "./datum-engine.js";
import { renderPdf } from "./datum-pdf.js";
const definition = {
id: "visit-request", version: "1.0.0", schemaVersion: "1",
root: { id: "root", type: "form", configuration: { title: "Visit request" }, children: { content: [
{ id: "fullName", type: "text", configuration: { label: "Full name", required: true } }
] } }
};
const runtime = createFormRuntime(definition);
runtime.setValue("fullName", "Ada Lovelace");
const pdf = await renderPdf(runtime);
await writeFile(pdf.fileName, pdf.bytes);
console.log(pdf.fileName, pdf.layoutId, pdf.pageCount, pdf.warnings);visit-request-default-20261116-014838.pdf default 1 []The options are the element's, listed under PDFs, and the result is the same. Four more stand in for the element's properties: support (what create makes, which the function makes for itself when it is left out), theme (a registered PDF theme's id or a theme, as the pdf-theme attribute), templates (as pdf) and binding (the PDF theme a binding suggests). The runtime's host context is not handed to the PDF: name host in the options when a layout reads host. values.
The fonts are read from fonts/ beside datum-pdf., so keep the folder with it. In a page, datum-form. exports a render of its own that loads datum-pdf. on its first call, from beside the bundle or from the address in its pdf option, and shares the load with the element.
On a server the PDF program draws the same document, and the submissions service renders and signs one with a record when the form is registered with PDF settings (see the package's README): The PDF program and Example: render a PDF on the server.
What is not stable
Only the names in JavaScript exports are meant to be imported, and even they are pre-release.
Formhas many more methods than this page shows. Those that are not on this page are not described anywhere on the site and may change.Runtime - The engine package,
@datum/, is private and ships TypeScript source. Names that the files do not re-export, such asengine mountand the telemetry helpers, cannot be imported from the files you host.Live @datum/andsubmissions @datum/are private too. Their entry points and the service's options may change before a release.pdf-kernel datum-engine.andjs datum-form.each carry their own copy of the runtime. A runtime made by one is not anjs instanceofthe other'sForm.Runtime rendertakes a runtime from either, and the two share the page's plugin and theme registries.Pdf