Open Brand Definition
OBDS / 4.0.3 stable
English only
← Back
Examples Companion to OBDS 4.0.3

See OBDS
decide

Two runnable examples. One compiles because the truth it needs is approved. One refuses to compile because the truth it needs is unknown, and stops before any model is called.

Example 01Defined truth compiles. Reproducible hash.
Example 02Unknown truth fails closed. Zero model calls.
BothConformance cases. An example that drifts fails the suite.
00 / Setup

Four lines, then both examples run.

The repository root is the package root. This works in a clone and in the extracted release archive.

git clone https://github.com/openbranddefinition/obds.git && cd obds
python -m venv .venv && .venv/bin/pip install -r requirements.txt
export PYTHONPATH=reference/foundation/src

Or download OBDS-4.0.3-FINAL.zip, extract it, and run the same commands from the extracted directory.

build <manifest> <plan>

build takes the manifest and the build plan as positional arguments, in that order. --out is the only option. Both examples are also conformance cases in reference/foundation/tests/test_examples.py, so an example that drifts from the reference implementation fails the suite.

01 / Defined truth

Approved truth compiles.

One manifest. One element, structure.brand, a fact in state defined. One target that requires it. The build produces a Compiled Brand Context.

01ApprovedA named role approved the manifest. The approval carries a content hash.
02RequiredThe target declares requiresDefined: structure.brand.
03ReadyThe requirement passes, so the target builds.
04CompiledOne Compiled Brand Context, with a hash that reproduces across runs.
.venv/bin/python -m obds_ref.cli build \
  examples/foundation-minimal/manifest.yaml \
  examples/foundation-minimal/build-plan.yaml \
  --out /tmp/obds-out

Exits 0.

status             ready
targetId           brand-query-global-en
generationId       sha256:6e051b97cd804fee753a1e71ccc695a0a00d936d08b789f8bc193c18e81b1a06
artifactRef        generations/6e051b97cd804fee753a1e71ccc695a0a00d936d08b789f8bc193c18e81b1a06/
                   target-bea1c8bf6e2f0c8c990e7ec685b2f67a98bc8fe1111aaaae278176477cb8f123.context.json
artifactHash       sha256:ee526d850ff185f4cadd44dbbd72547de78499284d893e668c7366119a690f0a
requirements       structure.brand  defined  pass

Since 4.0 the file name is a deterministic mapping of the target's canonical identity, not the identity itself, and the artefact lives under its build generation. Do not construct the path from targetId; read artifactRef from the build report.

{
  "kind": "obds-compiled-brand-context",
  "schemaVersion": "3.0.0",
  "targetId": "brand-query-global-en",
  "slots": {
    "hardBoundaries": "",
    "factGrounding": "- `structure.brand` — {\"name\":\"Example Minimal Brand\"}",
    "stateMap": "",
    "styleTexture": ""
  }
}

Excerpt of the produced artefact. Three slots are empty because this manifest declares nothing to put in them. That is the whole Foundation minimum: one element and its value contract.

One element, structure.brand, state defined, with a value contract pinning the shape hash, the schema reference and the schema hash. Foundation, section 26.1.
One target, brand-query-global-en, requiring that element to be defined. Compiled Runtime, section 26.2.
The written walkthrough for both examples, shipped in the release package.
02 / Unknown truth

Required truth is unknown. Nothing is generated.

The same shape, with one difference. A second element, context.efficacy-claim, is in state unknown. The target requires it. The build fails, and that is the correct result.

Required truth
→
context.efficacy-claim unknown
Build
→
status: failed · exit 2
Compiled context
→
none written · artifactRef: null
Model calls
→
0
.venv/bin/python -m obds_ref.cli build \
  examples/fail-closed/manifest.yaml \
  examples/fail-closed/build-plan.yaml \
  --out /tmp/obds-fail

Exits 2. It writes a build report and no Compiled Brand Context.

status             failed
targetId           claim-copy-global-en
artifactRef        null
artifactHash       null
context files      none written
requirements       structure.brand         defined  pass
                   context.efficacy-claim  unknown  fail
error              OBDS-BUILD-REQUIRED-NOT-DEFINED
                   context.efficacy-claim: expected defined, got unknown
state: unknown

The unknown element is never guessed, never widened to a neighbouring scope and never quietly dropped to let the build succeed. It carries no value key at all, because a non-defined state must not carry one. No Compiled Brand Context exists, so there is nothing to assemble a model input from, so no model is called.

This is what fail closed means: the absence of required truth stops the process before generation, rather than producing fluent output from an assumption nobody approved.

Two elements. structure.brand is defined; context.efficacy-claim is unknown and carries no value.
One target requiring both elements to be defined.

The guarantee belongs to Compiled Runtime. Section 26.2 is what requires no artefact for a failed target and zero instrumented model calls after a failed build. Foundation supplies the truth the gate reads. A Foundation-only implementation does not run the gate.

03 / Next

Where this goes next.

These two examples cover the Foundation minimum and the build gate. Everything else in OBDS is optional and added only when a task requires it.

How to author OBDS Who curates brand truth, what evidence a manifest is built from, who approves it, and what OBDS cannot guarantee. Read the spec One normative document. Section 26.1 is Foundation, section 26.2 is Compiled Runtime. Quickstart Five concepts and the smallest conforming implementation.

This page is published in English only. The rest of openbranddefinition.org carries parallel English and German copy; this companion page does not yet, matching /authoring/.