Skip to content
All technical docs Bricks technical documentation

Creating a tenant-spec manifest

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.

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

mermaid diagram

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. 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:

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 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.