# 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](/technical/concepts-ontologies), read it first — this page assumes the vocabulary (artefact, `artefact_type`, `extends`, catalog) it defines.

## The pipeline

```mermaid
flowchart LR
  P["SELECTION<br/>the bricks a person ticked<br/>(+ optional menu answers)"]
  P ==>|compose| TS["TENANT SPEC<br/>ticked artefacts + their requires<br/>(brics:// refs)"]
  TS ==>|render| MAN["MANIFEST<br/>artefact.upsert ops<br/>+ reasoned concept graph"]
  MAN ==>|apply| RUN["TENANT<br/>tables, relationships, apps,<br/>components, concept graph"]

  classDef x fill:#eaf0ff,stroke:#6f8fd6,color:#1a2a4a;
  class P,TS,MAN,RUN x;
```

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](/technical/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.

```json
{
  "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.

```json
{
  "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.** `table` ops; the `relationship` ops the spec's dependencies imply; one `app` op for each app the selection asks for, built from the standard app base; and `component` ops 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 as **`deferred`**: 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:

```yaml
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 an `artefact_type` of `table`, `relationship`, `app`, `media`, `workflow`, `role`, `permission`, `integration`, `component`, `data_flow`, `retention`, `retention_charter`, `export` or `harness`. Each carries a `spec` shaped for its type, and optionally `ref`, `extends` (free-form identifiers — any URI scheme) and a one-sentence `gloss` saying 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_key` is 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 `@v1` suffix 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_ref` is the child (holds the FK). In the manifest, `from_table` is the **parent** (`one` side) and `to_table` the child (`many` side, which gains `foreign_key_column`) for a `one_to_many`. A `many_to_many` names a `junction_table` and 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`), declare `to_person: true` and `foreign_key_column` instead of `to_table` and `cardinality`: the column is on `from_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 other `kind` is refused by name rather than ignored.
- **A table already on the tenant (`existing: true` in 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-Match` is required.** It carries the tenant's `state_version`; if the tenant changed since you read it, apply answers 412 and changes nothing. `POST /v2/tenants/:id/state/read` returns the current value, and `POST /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=true` returns 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 `deferred` and reached by authoring the manifest; apply handles them all.
- **`idempotency_key` makes 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](/technical/concepts-ontologies) defines artefact, `artefact_type` and catalog, and describes the composer; [the data API](/technical/data-api-permissions) covers the tables a manifest materialises; [workflows](/technical/rpc-and-workflows) and [data flows](/technical/data-flows) cover kinds you author in the manifest directly.*
