Creating a tenant-spec manifest
Bricks Technical Documentation
How a selection of bricks composes into a TenantSpec, renders into an apply manifest, and instantiates a real tenant — the concrete shapes at each step and how to author a manifest by hand.
Availability. Applying a manifest is a granted capability: it is open to platform administrators and to people holding an apply grant for that organisation, which an administrator issues per person and per organisation and can revoke. Being an organisation's administrator is not enough on its own. The composer that drives compose → render → apply is offered to the same people. As the platform grows we expect composing a tenant from a spec to become part of a premium plan; treat what follows as the technical contract, not a commitment that the surface stays free.
Bricks turns a choice of bricks into a running tenant through three shapes, in order: a selection, a TenantSpec, and an apply manifest. This page walks that pipeline, shows the exact shape of each stage, and explains how to write a manifest yourself — the path for everything the renderer does not emit yet, and for anyone whose catalog lives outside Bricks.
If you have not read the concepts graph & ontologies, read it first — this page assumes the vocabulary (artefact, artefact_type, extends, catalog) it defines.
The pipeline
Each arrow is a distinct step:
- compose is a deterministic, model-free function on the platform. It reads the published catalog store, limited to the catalogs the person may read, and returns a TenantSpec.
- render is a pure function: it dereferences each
brics://ref against the catalog store and emits the manifest. No configuration, no database, no network. - apply is the endpoint
POST /v2/tenants/:id/apply: it takes a manifest (as a bundle) and materialises the tenant.
The composer in the platform runs all three for you: preview, dry run, named projects, a draft organisation rebuilt on each compose, and opening the result in Studio — see concepts & ontologies. The same steps are reachable through the API: POST /v2/composition/preview composes and renders without writing anything, and POST /v2/composition/apply?dry_run=true rehearses the build.
Stage 1 — the selection
A selection is the list of bricks a person ticked, in order. Each entry is a brics:// ref, optionally labelled with what this occurrence is for — the same brick can be ticked twice (a table for training sessions and one for facility bookings), and then each occurrence needs a label so the two tables can be told apart.
{
"instances": [
{ "ref": "brics://example/tables/seasons@v1" },
{ "ref": "brics://example/tables/courses@v1" },
{ "ref": "brics://example/relationships/season-has-courses@v1" }
],
"predicates": { "scheduling": "seasonal" }
}
refs: [...] (a plain list of strings) is accepted as shorthand for one instance per ref. predicates are optional menu answers: they never decide what goes into the spec — they are matched against each brick's own predicates list to say why it is there, which render turns into concept-graph glosses.
Stage 2 — the TenantSpec
compose() returns a TenantSpec: the ticked artefacts plus everything they declare they requires, the gaps and conflicts it found, and a justification. The artefacts are abstract — each is a brics://… ref, not content; render fetches the content later.
{
"artifacts": [
{ "ref": "brics://example/tables/seasons@v1", "kind": "table", "name": "seasons", "matched_predicates": ["scheduling"] },
{ "ref": "brics://example/tables/courses@v1", "kind": "table", "name": "courses", "matched_predicates": ["chosen by the operator"] },
{ "ref": "brics://example/relationships/season-has-courses@v1", "kind": "relationship" }
],
"dependencies": [
{ "from_ref": "brics://example/tables/courses@v1", "to_ref": "brics://example/tables/seasons@v1", "relation": "one_to_many", "via_fk": "season_id" }
],
"conflicts": [],
"gaps": [
{ "missing": "brics://example/tables/age-brackets@v1", "required_by": "brics://example/tables/courses@v1", "relation": "requires" }
],
"justification": [
{ "predicate": "scheduling", "selected": ["brics://example/tables/seasons@v1"] },
{ "predicate": "chosen by the operator", "selected": ["brics://example/tables/courses@v1"] }
],
"stats": { "selected": 3, "composed": 3, "pulled_by_closure": 0, "existing": 0, "gaps": 1, "conflicts": 0 }
}
The fields you will read:
| Field | What it holds |
|---|---|
artifacts |
The composed abstract artefacts. ref is the catalog coordinate; kind is the intrinsic artefact_type; name is the table name for a table; existing: true marks an artefact already on the tenant (referenced, not re-authored); instances carries the labels a person gave. |
dependencies |
Edges between artefacts in the spec. An edge derived from a selected relationship has from_ref = the child (it holds the FK), to_ref = the parent, via_fk = the column; only those materialise as relationships. A requires edge carries no via_fk and is provenance only. |
gaps |
Something required that is not in the spec — a requires ref that does not resolve (by exact ref, version included), or one side of a relationship that was not ticked. Reported, never silently dropped or substituted. |
conflicts |
Selections that resolve but cannot compose: a base ontology ticked directly, two entries that render to the same table name, a relationship the spec cannot express (many-to-many), a table ticked twice without labels. |
justification |
Which menu answer, or "chosen by the operator", accounts for each ticked ref. |
A ref the person cannot read and a ref nothing publishes look the same — both are gaps — so a spec never reveals the existence of a catalog its author cannot see.
Stage 3 — render the manifest
Render dereferences each ref and emits a manifest: a list of artefact.upsert operations keyed by artefact_type, plus the reasoned concept graph. Dispatch is by the artefact's intrinsic artefact_type, never by walking extends — an artefact whose type is table becomes a table op.
What render emits today.
tableops; therelationshipops the spec's dependencies imply; oneappop for each app the selection asks for, built from the standard app base; andcomponentops placed into that app. A component whose source the store does not hold is deferred with that reason. Every other kind — workflow, role, permission, data flow, and the rest — is returned asdeferred: visible with its ref, never dropped. Apply itself handles every kind, so you reach those by writing the manifest yourself, as below.
The manifest shape
A manifest is a small, declarative document. This is the shape render emits and apply accepts:
api_version: bricks.platform/v1
kind: TenantApplyManifest
metadata:
description: A seasonal-club structural subset.
source: hand-authored
operations:
- id: upsert-seasons
kind: artefact.upsert
artefact_type: table
idempotency_key: seasonal-club/seasons@v1
ref: brics://example/tables/seasons@v1
gloss: Seasons bound every course and registration in time.
spec:
table_name: seasons
label: { en: Season, fr: Saison }
columns:
- { name: id, type: UUID, primary_key: true, nullable: false, default: gen_random_uuid() }
- { name: name, type: VARCHAR(255), label: { en: Name, fr: Nom } }
- { name: status, type: VARCHAR(20), check: { kind: one_of, values: [draft, open, closed] } }
indexes: []
- id: upsert-courses
kind: artefact.upsert
artefact_type: table
idempotency_key: seasonal-club/courses@v1
spec:
table_name: courses
label: { en: Course, fr: Cours }
columns:
- { name: id, type: UUID, primary_key: true, nullable: false, default: gen_random_uuid() }
- { name: title, type: VARCHAR(255), label: { en: Title, fr: Titre } }
indexes: []
- id: rel-season-has-courses
kind: artefact.upsert
artefact_type: relationship
idempotency_key: seasonal-club/rel/season_has_courses@v1
spec:
relationship_name: season_has_courses
label: { en: Courses of the season, fr: Cours de la saison }
from_table: seasons
to_table: courses
cardinality: one_to_many
foreign_key_column: season_id
Operation kinds. A manifest holds up to 100 operations, of three kinds:
artefact.upsert, with anartefact_typeoftable,relationship,app,media,workflow,role,permission,integration,component,data_flow,retention,retention_charter,exportorharness. Each carries aspecshaped for its type, and optionallyref,extends(free-form identifiers — any URI scheme) and a one-sentenceglosssaying why the artefact exists in this tenant.data.load— loads rows of one table from a registered migration dataset, re-runnable: a second run updates the rows the first created rather than duplicating them.data.bind— fills user columns of already-loaded rows once the people concerned have accepted their invitations.
Per-kind operation names such as schema.table.upsert or schema.relationship.upsert are not accepted; the refusal names the artefact.upsert + artefact_type to use instead.
Rules that matter when you write one by hand:
idempotency_keyis the identity of the operation. Applying the same manifest twice upserts — it does not duplicate. Keep the key stable across versions of the same artefact (the@v1suffix is a convention, not a requirement).- Ordering: tables before the relationships that join them. A relationship materialises a FK between two tables that must already exist. Render guarantees this order; preserve it if you edit a manifest.
- The relationship inverts the dependency. In the spec,
from_refis the child (holds the FK). In the manifest,from_tableis the parent (oneside) andto_tablethe child (manyside, which gainsforeign_key_column) for aone_to_many. Amany_to_manynames ajunction_tableand its two columns instead. Read the FK direction, not the field name. - A relationship can point at a person. For a column that holds a BricksID person's id (
attendances.user_id), declareto_person: trueandforeign_key_columninstead ofto_tableandcardinality: the column is onfrom_table, and the data manager shows the person's name in place of the id. No constraint is added, because the id belongs to BricksID, not to the tenant's schema. - A column can declare the values it allows.
check: { kind: one_of, values: [...] }(1 to 64 strings, numbers or booleans) becomes a database CHECK, so every writer — the data API, workflows, your own backend — is refused a value outside the list. Any otherkindis refused by name rather than ignored. - A table already on the tenant (
existing: truein the spec) gets no table op — it is referenced by relationship ops without being re-authored.
Stage 4 — apply
Apply takes a bundle: a zip whose root holds manifest.yaml (or .yml / .json) plus any files the operations reference under content/. Post it as the bundle field of a multipart request:
POST /v2/tenants/:id/apply
If-Match: <state_version>
If-Matchis required. It carries the tenant'sstate_version; if the tenant changed since you read it, apply answers 412 and changes nothing.POST /v2/tenants/:id/state/readreturns the current value, andPOST /v2/tenants/init— which creates an empty organisation to apply into — returns it too, so creating then applying takes two calls.- A lint runs first. Before any operation commits, apply walks the manifest against the tenant's current state and refuses one with blocking findings.
?dry_run=truereturns that plan and writes nothing. Operations commit one by one, so the lint is what stops a broken manifest from leaving half its work behind. - Authorization is a platform administrator, or a person holding an apply grant for that organisation (see Availability above).
The endpoint materialises each operation against the tenant and writes the concept graph carried in, or derived from, the manifest.
Worth knowing
- Compose is deterministic — what a person ticked, plus what it requires by exact ref; no model decides what goes into a tenant.
- Abstract until render — a TenantSpec is
brics://refs, not bytes; the content comes from the catalog store at render time. Render is a linker, not a transpiler. - Render emits tables, relationships, apps and components — other kinds are
deferredand reached by authoring the manifest; apply handles them all. idempotency_keymakes apply safe to repeat — re-applying upserts, it never duplicates.- Applying is granted, not implied — platform administrators and apply-grant holders only; expected to sit behind a paid plan as the platform grows.
Related: the concepts graph & ontologies defines artefact, artefact_type and catalog, and describes the composer; the data API covers the tables a manifest materialises; workflows and data flows cover kinds you author in the manifest directly.