Object field

import { collection } from "#questpie/factories";

export const users = collection("users").fields(({ f }) => ({
	email: f.email().required(),
	address: f.object({
		street: f.text().required(),
		city: f.text().required(),
		zip: f.text(10),
	}),
}));

address reads back as { street: string; city: string; zip: string | null } | null, one jsonb value, no second table and no join.

Nested keys

Each value in the record is a field built from the same f, so it takes the same chain. Another f.object() nests, to any depth. What a modifier on a nested key actually changes:

Filtering

The typed where clause carries the object operator set. Every entry is structural, and all of them run against the whole jsonb value.

const { docs } = await app.collections.users.find({
	where: { address: { pathEquals: { path: ["city"], val: "Berlin" } } },
});

await app.collections.users.find({
	where: { address: { contains: { city: "Berlin", zip: "10115" } } },
});

Three sharp edges in that table. pathEquals extracts with #>>, so val is compared as text and a number has to be written the way Postgres prints it. hasKey and its two siblings see top-level keys only, never a key one level down. isEmpty and isNotEmpty ignore their operand, so passing false runs the same SQL as passing true.

After .array()

.array() keeps the single jsonb column and stores a list of the object. .minItems(n) and .maxItems(n) become real here, as z.array().min() and .max(), and are inert on a bare object. The admin swaps the panel for a repeatable item list.

links: f
	.object({ label: f.text().required(), url: f.url().required() })
	.array()
	.maxItems(5),
//  read type: { label: string; url: string }[] | null

The operator set changes with it. The eleven object operators are gone and the array set takes over: containsAll, containsAny, eq, length, isEmpty, isNotEmpty, isNull, isNotNull. The types offer a ninth, contains, with no operator behind it. It falls through to an ILIKE against the jsonb column, which Postgres rejects. See Arrays.

Localization

.localized() on the object itself moves the whole jsonb value into the i18n table, one stored object per locale.

.localized() on a single nested key splits instead. QUESTPIE walks the nested fields, leaves a marker at that path in the structure column, and stores the value per locale. It recurses through nested objects and through .array(), where every item is split at the same path.

profile: f.object({
	name: f.text().required(),        // one value for every locale
	bio: f.textarea().localized(),    // one value per locale
}),

Access on nested keys

A nested .access() rule registers under its dot path, address.zip. Reads evaluate the rule and delete the key from the response. Writes evaluate it per key present in the payload, and a denied key throws instead of being ignored. Both recurse into deeper objects and into array items. Both are skipped for a system-mode call, which is how seeds and internal code still see the key. See Access control.

Admin

Both methods below come from @questpie/admin, which registers them as field extensions. They sit on the chain of every field, and only when that module is enabled. See Collections and Globals.

.admin(config) sets the panel's shape:

.form(({ f }) => ({ fields })) orders the keys instead, and accepts the same section and tabs containers the collection form takes. Here f is a name proxy, so f.street is the string "street".

With a form set, layout and columns are never read. Each section carries its own pair, defaulting to "stack" and 2. wrapper and defaultCollapsed still apply.

address: f
	.object({ street: f.text(), city: f.text(), zip: f.text(10) })
	.admin({ defaultCollapsed: false })
	.form(({ f }) => ({
		fields: [
			{ type: "section", label: "Postal", layout: "grid", fields: [f.zip, f.city] },
		],
	})),

Related

• Fields, the type table and the shared chain.
• f.json(), the same column with no declared keys.
• Arrays, what .array() does to reads and filters.
• Blocks, when items are different shapes, not one shape.
• Relations, when nested data wants its own rows.
• Validation, the derived schema and the .zod() hatch.