Skip to content

Embedded fields and lists

Keep owned, fixed-shape data with its parent entity instead of giving every nested value its own aggregate. This recipe covers both a single embedded object and an embedded list rendered by a declarative entityEdit screen.

  • Embedded objects — address and optional billingAddress are validated sub-schemas stored in the contact row.

  • Embedded lists — invoice lines repeat a fixed row shape without their own identity or event stream.

  • Structured cells — a line uses a reference, select, number, and money cell, with amount derived from quantity × unitPrice and a totals row.

  • Server-authoritative derived cells — the write schema recomputes derived values before validation, so a client cannot supply a stale amount; the edit view model exposes the definitions as embeddedListDerived.

  • Declarative editing — the invoice-edit screen uses createEmbeddedListField; its renderer receives embeddedListCells, so no custom screen component is required.

  • Derived head totals (src/screens/invoice-receive.screen.ts): an actionForm declares derive so net, VAT, and gross follow the lines (listSum); the list requires at least one line (minItems: 1), so there is no lineless input to cover. The head totals are not laid out; the lines footer shows Net, VAT, and Gross through labelled totals entries ({ label, from }). The handler wraps its schema with withFormDerivations(schema, screen) (src/handlers/invoice-receive.write.ts), so totals sent by the client are replaced on the server.

  • Redirect with search params: after submit, invoice-receive redirects to invoice-list with searchParams: { "invoice-list.q": "invoiceNumber" }, so the list opens with the number the handler returns in its search box. The receive handler stores nothing in this recipe; the search finds invoices saved through invoice-edit with that number.

Use an embedded field or list when the nested data is created, changed, and deleted with its parent. Promote a row to its own entity when it needs an independent status, history, or handler.

The feature entry point is src/feature.ts. The embedded object and invoice line-item schemas live under src/entities/; integration tests cover schema validation, derived values, totals, references, and the declarative edit screen.


The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

// Embedded Object Sample
// Shows: Embedded objects stored as JSONB, searchable sub-fields,
// field access on sub-fields, required vs optional embedded objects
//
// Pattern: Address belongs 1:1 to contact — never shared, always read together.
// Use embedded when: data is owned by the parent entity, not referenced elsewhere.
//
// Tables:
// contact — with embedded address (required) and billingAddress (optional)
// address.street and address.city are searchable
// billingAddress.vatId has restricted field access
// product — minimal entity, only exists so `invoice.lines` has something
// to reference
// invoice — embedded list with select/reference/derived/totals metadata
// on its `lines` sub-fields (Issue #1835), plus a declarative
// entityEdit screen that renders the list end-to-end via
// EmbeddedListField, no custom-screen code required
// invoice-receive — actionForm whose net/VAT/gross head fields are derived
// from the lines (`derive`); the handler recomputes them with
// `withFormDerivations`, so client-sent totals are never trusted
import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
import { contactEntity } from "./entities/contact";
import { invoiceEntity } from "./entities/invoice";
import { productEntity } from "./entities/product";
import { contactCreate } from "./handlers/contact-create.write";
import { contactDetail } from "./handlers/contact-detail.query";
import { invoiceReceive } from "./handlers/invoice-receive.write";
import { invoiceReceiveScreen } from "./screens/invoice-receive.screen";
export { contactEntity } from "./entities/contact";
export { invoiceEntity } from "./entities/invoice";
export { productEntity } from "./entities/product";
const adminWrite = { access: { roles: ["Admin"] } } as const;
const openRead = {
access: {
openToAll: {
reason:
"any signed-in user may read products and invoices in this recipe; writes are " +
"still gated by adminWrite",
},
},
} as const;
export const embeddedFeature = defineFeature("contacts", (r) => {
r.entity(contactEntity);
r.writeHandler(contactCreate);
r.queryHandler(contactDetail);
r.writeHandler(invoiceReceive);
r.crud(productEntity, { write: adminWrite, read: openRead });
r.crud(invoiceEntity, { write: adminWrite, read: openRead });
r.screen({
id: "invoice-edit",
type: "entityEdit",
entity: "invoice",
layout: {
sections: [{ columns: 1, fields: ["invoiceNumber", "customer", "lines"] }],
},
});
r.screen({
id: "invoice-list",
type: "entityList",
entity: "invoice",
columns: ["invoiceNumber", "customer"],
});
r.screen(invoiceReceiveScreen);
});

📄 On GitHub: samples/recipes/embedded/src/feature.ts