# IDs and cross-references — canonical grammar

This appendix defines the ID grammar used across all Transitrix notations and enumerates the TYPE registry. Every element ID and every cross-reference in any notation file follows this grammar.

Recorded 2026-05-20 as the canonical decision for the methodology.

---

## 1. Grammar

```
<TYPE>-[<middle segment(s)>-]<INTEGER>
```

- **TYPE** — uppercase entity-type prefix from the registry in §3. The prefix names *what kind of thing* the ID refers to. The TYPE segment is composed of uppercase letters `A`–`Z`, digits `0`–`9`, and the underscore `_`; it MUST start with a letter. The underscore allows multi-word TYPE names — `PROCESS_BLUEPRINT` (the first registered TYPE to use one, decided 2026-05-21) and `INFORMATION_ENTITY` (registered alongside it).
- **Middle segments** — optional, notation-specific. Add for disambiguation (a domain code, a period, a programme name). The grammar fixes only the start and the end of an ID; a notation MAY define one or more middle segments where needed. A middle segment may be alphanumeric or purely numeric, and a numeric middle segment **MAY carry leading zeros** where it is a zero-padded date or period component — e.g. the month and day of an ISO date, `INTERVIEW-cfo-onboarding-2026-04-15-1` (`04`, `15`). The no-leading-zeros rule below constrains the **terminal** integer only; middle segments are labels, not the sort key.
- **INTEGER** — terminal positive integer, ≥ 1, **no leading zeros** — this constraint applies to the **terminal** integer only (it is the numeric sort key; numeric middle segments are exempt, see above). Sorting and comparison MUST parse it numerically, never lexically. There is no fixed width and no upper bound.

**Examples:**

| ID | TYPE | Middle | Integer | Notes |
|---|---|---|---|---|
| `DRIVER-1` | DRIVER | — | 1 | minimal form |
| `GOAL-RETENTION-12` | GOAL | RETENTION | 12 | one middle segment |
| `ACTION-Q3-2026-7` | ACTION | Q3, 2026 | 7 | two middle segments |
| `INTERVIEW-cfo-onboarding-2026-04-15-1` | INTERVIEW | cfo, onboarding, 2026, 04, 15 | 1 | zero-padded ISO-date middle segments (`04`, `15`) are valid — the ban is terminal-only |
| `DRIVER-CHURN-001` | — | — | — | **invalid** — leading zero on the *terminal* integer. Use `DRIVER-CHURN-1`. |
| `driver-1` | — | — | — | **invalid** — TYPE must be uppercase. |
| `DRIVER-` | — | — | — | **invalid** — missing terminal integer. |
| `PROCESS_BLUEPRINT-FULFIL-1` | PROCESS_BLUEPRINT | FULFIL | 1 | underscore in TYPE — permitted |
| `BUSINESS_OBJECT-ORDER-3` | BUSINESS_OBJECT | ORDER | 3 | underscore in TYPE — permitted |

---

## 2. Exception — `CAPABILITY`

Capability IDs end with a V/H diagram address instead of a plain integer:

```
CAPABILITY-V<L1[.L2[.L3]]>
CAPABILITY-H<L1[.L2[.L3]]>
```

- `V` = vertical capability (column in the diagram).
- `H` = horizontal capability (row cutting across columns).
- Each address component (`L1`, `L2`, `L3`) is a positive integer ≥ 1, no leading zeros, no upper bound.
- `0` is reserved for the root node and is never used in a capability ID.
- Depth is **capped at three levels** (`L1.L2.L3`). A fourth level (`L1.L2.L3.L4`) is invalid.

**Examples:**

- `CAPABILITY-V1`
- `CAPABILITY-V1.2`
- `CAPABILITY-V1.2.3`
- `CAPABILITY-H1.2`

The diagram address derives from the V/H positional addressing system documented in [`05-capability-map.md`](views/05-capability-map.md) §4–5. Capability IDs are the only place the trailing integer is replaced by a multi-component path; every other TYPE follows §1 unchanged.

---

## 3. TYPE registry

The complete set of canonical TYPE prefixes. Use exactly the listed form — abbreviations like `ACT`, `CHG`, `FAC`, `CAP`, `SCN` are deprecated and being migrated out (see §6).

### 3.1 Element types

Elements that get referenced across documents.

| TYPE | What it is | Used by |
|---|---|---|
| `DRIVER` | strategic driver — external or internal | DGCA, FGA |
| `GOAL` | strategic or tactical goal | Goals tree, DGCA, FGA, Action schedule |
| `CHANGE` | business transformation (the BDN change layer) | DGCA, Action schedule (`delivers_changes:`) |
| `ACTION` | implementation-layer work package — Initiative / Programme / Project / Task (ArchiMate Work Package). **Deprecated alias:** `ACTIVITY` (accepted with `ACTION-005` warning until 1.0 cut). | DGCA, FGA, Action schedule, Actions tree, Action Card; see [elements/24-action.md](elements/24-action.md) |
| `CAPABILITY` | capability — V/H sub-grammar, see §2 | Capability map, Products, Applications, Process map |
| `PROCESS` | business process | Process landscape map, BPMN |
| `STEP` | process-flow step — a single node (task / event / gateway) in a `PROCESS` element's `flow`. Canonical-by-containment within its PROCESS (which carries the admission record); addressable by its `STEP-…` id and promoted to a standalone catalogue record only when a second document first references it — a step-level `CHANGE`, a `RULE.applies_to`, an `ACTION` realising it, or an `ASSERTION` (`subject` / `realised_via`). | `PROCESS.flow` (inline, §7.5); promoted to `canon/elements/02_business/steps/`. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.21. |
| `PRODUCT` | product or service | Products catalogue |
| `APPLICATION` | application | Applications catalogue |
| `INTEGRATION` | integration between applications | Applications catalogue |
| `ROLE` | business role — a position / responsibility, distinct from the `ACTOR` that fills it | referenced as `owner_role` across notations; `role.unit` references an `ACTOR` of `type: business_unit` |
| `ACTOR` | active-structure identity — `person`, `business_unit`, or `system` (ArchiMate Business Actor). Replaces the former `UNIT` / `EMPLOYEE` TYPEs (removed 2026-05-29). Engagement (employment, candidacy, …) and org hierarchy are first-class `REL` records, not inline fields. | Actors catalogue (`canon/elements/02_business/actors/`); referenced as activity `owner`. Schema: [19-actors.md](elements/19-actors.md). |
| `LOCATION` | physical or virtual place (ArchiMate Location) — `country`, `region`, `city`, `site`, `office`, or `virtual`. A shared, addressable place element referenced by `ACTOR` nodes via `located_at` relations. | Locations catalogue (`canon/elements/02_business/locations/`); attached to actors via `located_at` REL. Schema: [elements/21-locations.md](elements/21-locations.md). |
| `BUSINESS_SERVICE` | externally visible behaviour the organisation offers to its consumers — internal, external, or shared (ArchiMate Business Service §8.3.4). Linked to its offering unit via the `offers` REL kind and to the capability it realizes via the `realizes` REL kind. Distinct from `PROCESS` (internal execution), `CAPABILITY` (the ability), and `PRODUCT` (a packaged offering). | Business-services catalogue (`canon/elements/02_business/business-services/`); `offers` and `realizes` REL kinds link to `ACTOR` / `ROLE` and `CAPABILITY`. Schema: [elements/25-business-services.md](elements/25-business-services.md). |
| `SCENARIO` | implementation-layer **path** primitive — the ordered set of steps (`ACTION` / `CHANGE`) that moves the enterprise to one `TARGET_STATE` in service of one or more `GOAL`s (ArchiMate Course of Action realised by Work Packages + Gaps). The destination is a separate primitive (`TARGET_STATE`); the scenario references it via `arrives_at` and owns its `steps`. | Scenarios catalogue (`canon/elements/05_implementation/scenarios/`); rendered by [11-scenarios.md](views/11-scenarios.md) as a report-config view. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.19. |
| `EQUIPMENT` | ArchiMate Physical element — physical instrument, device, or facility a process stage depends on. Catalogued at `canon/elements/04_technology/equipment/` (ADR 2026-06-08; first catalogued TYPE for this layer). | Process Blueprint; Technology layer catalogue. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.14. |
| `NODE` | ArchiMate Technology Node — the physical or virtual compute, network, or storage substrate that hosts technology services. Catalogue: `canon/elements/04_technology/nodes/`. Hosts `TECHNOLOGY_SERVICE` via the `hosts` REL kind. | Technology layer catalogue; infrastructure integration modelling. Schema: [elements/25-nodes.md](elements/25-nodes.md). |
| `TECHNOLOGY_SERVICE` | ArchiMate Technology Service — a platform-level service (messaging, storage, API gateway, database, compute) exposed by a `NODE` to the application layer. Consumed by `APPLICATION` via the `uses` REL kind. Catalogue: `canon/elements/04_technology/services/`. | Technology layer catalogue; application-layer dependency modelling. Schema: [elements/26-technology-services.md](elements/26-technology-services.md). |
| `BUSINESS_OBJECT` | ArchiMate Business Object — passive information element at the business grain ("customer order", "customs declaration", "invoice"). Replaces `INFORMATION_ENTITY` (renamed for ArchiMate alignment). Catalogued at `canon/elements/02_business/business-objects/` (ADR 2026-06-08). `INFORMATION_ENTITY` is a deprecated alias for one release (see §6). | Process Blueprint; Business layer catalogue. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.15. |
| `RULE` | business rule (business layer per ArchiMate 3.2) | Rules catalogue (`canon/elements/02_business/rules/`); referenceable from any notation via `applies_to:` |
| `REGISTRY` | business-layer **operating-configuration** primitive — a curated, org-authored list the organisation maintains to drive an operating activity. Worked example: the regulatory **source registry** (which sources to watch, where, how, how often). Rows are inline, canonical-by-containment, promotable. Distinct from `RULE` (decision logic, not a maintained list), from codex (codex is *given to* the org; a registry is *authored by* it), and from the Field zone (a registry is curated/authoritative, not contradiction-tolerant evidence). | Registries catalogue (`canon/elements/02_business/registries/`). Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.20. |
| `CONSTRAINT` | design / operating constraint (motivation layer per ArchiMate 3.2) — a restriction or prohibition the organisation must not cross | Constraints catalogue (`canon/elements/01_motivation/constraints/`); referenced from DGCA drivers via `references_constraint:` |
| `REQUIREMENT` | regulatory or organisational requirement (motivation layer per ArchiMate 3.2) — a positive obligation the organisation must fulfil. Distinct from `CONSTRAINT` by **form of the obligation**: REQUIREMENT = positive action ("must submit", "must register", "must obtain approval"); CONSTRAINT = restriction ("must not", "cannot exceed"). | Requirements catalogue (`canon/elements/01_motivation/requirements/`); cites its source via `derived_from:` (codex `LAW` / `REGULATION` / `POLICY` / `INTERNAL_STANDARD`) and, optionally, the upstream `NEED` it serves via `serves:`. Schema: [15-requirement.md](elements/15-requirement.md). |
| `STAKEHOLDER` | motivation-layer interest primitive (ArchiMate Stakeholder) — `internal` / `external`. Carries the stake profile (concern, interest, influence) and **references an `ACTOR` for identity** (`actor:` required); never carries identity itself. | Stakeholders catalogue (`canon/elements/01_motivation/stakeholders/`); stakes in specific objects are `stakeholding` relations. Schema: [20-stakeholders.md](elements/20-stakeholders.md). |
| `ASSESSMENT` | motivation-layer finding (ArchiMate Assessment) — a **dated finding/judgement about the state of a `DRIVER`**, e.g. "support response time 8h, degrading". Carries the finding and its observation date; **no polarity / SWOT field** (polarity lives on the `INFLUENCE` relation). One driver accrues many assessments over time, which is what justifies it as its own element. Also usable as the core primitive for expressing generic risk via the motivation-layer mapping — see [CONTRACT.md](CONTRACT.md) §8.1 — as an alternative to the dedicated `RISK` type below. | Assessments catalogue (`canon/elements/01_motivation/assessments/`); `assesses:` references one `DRIVER`. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.17. |
| `RISK` | motivation-layer **projected event** — likelihood, impact, and residual exposure of something that has not happened yet, distinct from `ASSESSMENT`'s dated finding about the present. No ArchiMate counterpart (ArchiMate 3.x has no risk element). References the `DRIVER` / element it `threatens` and the `REQUIREMENT` / `CONSTRAINT` that `treats` it via `treated_by`. Additive alongside, not a replacement for, the [CONTRACT.md](CONTRACT.md) §8.1 motivation-primitive risk mapping. | Risks catalogue (`canon/elements/01_motivation/risks/`). Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.26. |
| `METRIC` | motivation-layer **managed indicator** — the measure an organisation tracks to know whether a `GOAL` is moving, or whether a `CAPABILITY` / `PROCESS` is performing as intended. Carries `unit`, `target`, and `direction_of_good`; no ArchiMate counterpart. Distinct from `COVERAGE_METRIC` (below) — a document-level **report-config** view with no canonical content of its own, computing a regulatory dark-cell count, not a first-class managed indicator. | Metrics catalogue (`canon/elements/01_motivation/metrics/`); `measures:` references one or more `GOAL` / `CAPABILITY` / `PROCESS`. Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.27. |
| `NEED` | motivation-layer **stakeholder/user need** — what must be true for whoever depends on it, independent of how it will be met. Upstream of `REQUIREMENT`, which traces back to it via `serves:`. No ArchiMate counterpart (ArchiMate 3.x has no need element). | Needs catalogue (`canon/elements/01_motivation/needs/`). Schema: [`ELEMENT_PRIMITIVES.md`](ELEMENT_PRIMITIVES.md) §7.28. |
| `TARGET_STATE` | implementation-layer **end-state** primitive (ArchiMate Plateau) — a structural snapshot of the `CAPABILITY` / `PROCESS` / `APPLICATION` selection that exists when one or more goals are met. The object an architect varies when presenting solution options; satisfies one or more `GOAL`s and is reached by one or more `SCENARIO` paths. | Target-states catalogue (`canon/elements/05_implementation/target-states/`); composition is inline (`capabilities[]`, `processes[]`, `applications[]`). Schema: [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.18. |
| `REL` | first-class time-aware relation between two canonical primitives — `parent`, `action_goal`, `goal_parent`, etc. Carries its own `valid_from` / `valid_to` so changes to a relation (a capability re-parenting, a goal re-aimed) are first-class temporal events. Deprecated alias: `activity_goal` → `action_goal`. | Relations catalogue (`canon/relations/`); one file per relation. Schema: [17-relations.md](elements/17-relations.md). |
| `MILESTONE` | project-narrative milestone — a decision gate, certification date, or programme-level marker that belongs in an Action Card's narrative. Distinct from a "schedule milestone" (a zero-duration action inside an Action schedule document, see [07-action.md](views/07-action.md) §5.9), which exists for critical-path computation. | Defined inside an Action Card document (`*.action-card.transitrix.yaml`); scope is the parent card document. Schema: [18-action-card.md](views/18-action-card.md). |

### 3.2 Document-level types

Each notation file carries its own ID using the same grammar; the TYPE names the notation.

| TYPE | Notation file |
|---|---|
| `DGCA` | `*.dgca.transitrix.yaml` |
| `GOALS_TREE` | `*.goals.transitrix.yaml` |
| `CAPABILITY_MAP` | `*.capability-map.transitrix.yaml` |
| `PROCESS_MAP` | `*.process-map.transitrix.yaml` |
| `ACTION_NET` | `*.action.transitrix.yaml` (deprecated alias: `*.activities.transitrix.yaml`) |
| `PRODUCTS_CAT` | `*.products.transitrix.yaml` |
| `APPLICATIONS_CAT` | `*.applications.transitrix.yaml` |
| `SCENARIOS` | `*.scenarios.transitrix.yaml` |
| `BLOCKS` | `*.blocks.transitrix.yaml` |
| `PROCESS_BLUEPRINT` | `*.process-blueprint.transitrix.yaml` |
| `ACTION_CARD` | `*.action-card.transitrix.yaml` (deprecated alias: `*.activity-card.transitrix.yaml`) |
| `COMPLIANCE_IMPACT` | `*.compliance-impact.transitrix.yaml` |
| `COVERAGE_METRIC` | `*.coverage-metric.transitrix.yaml` |

BPMN diagrams use their `process.id` as the document identifier; that field is a free-form string defined by the spec, not by this appendix.

### 3.3 File-local labels (standalone BPMN projection only)

In a **standalone `.bpmn.transitrix.yaml` projection** — a generated diagram, not an authored source — the node IDs (`POOL-…`, `GW-…`, `TASK-…`, `SF-…`, `SE-…`, `EE-…`) are local labels, not cross-document references: they identify nodes within that one rendered file and are not part of the TYPE registry above.

This does **not** apply to a process flow authored inside a `PROCESS` element ([ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.5). There the flow is canon: each `flow.steps[].id` follows the canonical ID grammar (§1) and is **addressable** — unique within its `PROCESS` and referenceable by a step-level `CHANGE`, a `RULE`, an `ACTION`, or an `ASSERTION` — and is promoted to the registered standalone `STEP` TYPE (§3.1; element-file shape and promotion mechanic in [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §7.20) only if a second document references it (canonical-by-containment + promotion, [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §1). The `STEP` TYPE is the canonical step identity; the file-local `TASK-…` / `SE-…` / `EE-…` labels above are projection labels, never a step's catalogue identity.

### 3.4 Field artefact types

Raw, unprocessed material in the **Field** zone (see [CONTRACT.md](CONTRACT.md) §5). Field artefacts are not authoritative; their value is provenance. A Canon record cites the Field material behind it via `derived_from:` ([CONTRACT.md](CONTRACT.md) §6).

| TYPE | What it is |
|---|---|
| `INTERVIEW` | a recorded interview or its notes |
| `SURVEY` | a survey instrument and/or its responses |
| `OBSERVATION` | a direct observation of work, a system, or an event |
| `DRAFT` | a working draft not yet admitted to canon |
| `AMENDMENT` | a structured record that a watched codex source has been amended — what moved, when it was detected, the source section, hints about likely-impacted canon elements, and (post-adjudication) the canon `CHANGE` / Gap elements it motivates. Distinct from canon `CHANGE` (§3.1, ArchiMate Gap — the *org's planned delta*); AMENDMENT records the *external detection event*. Schema: [22-amendment.md](elements/22-amendment.md). |
| `SEGMENT` | an extracted chunk of a codex source — one article / clause / paragraph / section — with a locator into the source and the chunk text (or its `sha256` fingerprint). The addressable text-level provenance that an `AMENDMENT` (`segment_refs[]`), a `REQUIREMENT` / `ASSERTION`, or the compliance-impact view cites instead of a free-text section string. Schema: [23-segment.md](elements/23-segment.md). |

### 3.5 Codex artefact types

External constraints and internal authority documents in the **Codex** zone — *given to* the organisation, not authored by it. See [CONTRACT.md](CONTRACT.md) §5 and [14-codex.md](elements/14-codex.md).

| TYPE | Sub-zone | What it is |
|---|---|---|
| `LAW` | codex / external | a statute or act binding the organisation |
| `REGULATION` | codex / external | a regulation issued under a law |
| `POLICY` | codex / internal | an internal policy the organisation issues |
| `INTERNAL_STANDARD` | codex / internal | an internal standard or convention |

### 3.6 Assertion type

Compliance claims linking a `REQUIREMENT` to the elements that realise it. Assertions are canonical (canon zone) but live **outside** the `elements/` tree, under `canon/assertions/`. Schema: [16-assertion.md](elements/16-assertion.md).

| TYPE | What it is |
|---|---|
| `ASSERTION` | a claim that a subject (`PRODUCT` / `PROCESS` / `CAPABILITY`) satisfies a `REQUIREMENT`, with status and evidence |

### 3.7 Verification type

The engineering verification counterpart to `ASSERTION` (§3.6) — a claim that a protocol was run against a `REQUIREMENT`, with method, result, and pass/fail outcome. Verification only, not full verification-and-validation (V&V): `verifies` resolves to `REQUIREMENT`. The stakeholder/user-need validation anchor is the separate `VALIDATION` type (§3.8). Also canonical but living **outside** the `elements/` tree, under `canon/verifications/`. Schema: [27-verification.md](elements/27-verification.md).

| TYPE | What it is |
|---|---|
| `VERIFICATION` | a claim that a protocol (test / analysis / inspection / demonstration) was run against a `REQUIREMENT`, with a pass/fail outcome |

### 3.8 Validation type

The validation-domain counterpart to `VERIFICATION` (§3.7) — a claim that a protocol was run against a `NEED`, with method, result, and pass/fail outcome. Also canonical but living **outside** the `elements/` tree, under `canon/validations/`. Schema: [28-validation.md](elements/28-validation.md).

| TYPE | What it is |
|---|---|
| `VALIDATION` | a claim that a protocol (user acceptance / field trial / stakeholder review / usability study) was run against a `NEED`, with a pass/fail outcome |

---

## 4. Uniqueness scope

Each TYPE has a scope within which its IDs must be unique. Cross-document references rely on the wider scope holding.

| TYPE | Uniqueness scope |
|---|---|
| `DRIVER`, `GOAL`, `CHANGE`, `ACTION` | within the DGCA / FGA / Goals / Action schedule document that defines them. When referenced from across documents, IDs must also be unique within the organisation's element catalogue (`canon/elements/01_motivation/`, `canon/elements/02_business/`). |
| `CAPABILITY` | within the capability set (`set_name`, per [`05-capability-map.md`](views/05-capability-map.md) §5). |
| `PROCESS` | within the organisation's element catalogue (`canon/elements/02_business/`). |
| `STEP` | within its `PROCESS` element while inline (canonical-by-containment); once promoted, within the organisation's element catalogue (`canon/elements/02_business/steps/`), one file per promoted STEP. The id is unchanged by promotion (no rename). |
| `PRODUCT`, `APPLICATION` | within the organisation's element catalogue (`canon/elements/02_business/` for `PRODUCT`, `canon/elements/03_application/` for `APPLICATION`), one file per element. Both are `standalone` ([ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §4), so their IDs are org-wide-unique from creation (not document-scoped) — the §1 promotion rule does not apply (they are first-class catalogue elements, never inline). |
| `INTEGRATION` | within the catalogue document while `view-defined` (nested in an application's `integrations[]`, [`10-applications.md`](views/10-applications.md)); once promoted (§1 promotion rule), within the organisation's element catalogue (`canon/elements/03_application/integrations/`), one file per promoted INTEGRATION. The id is unchanged by promotion (no rename). |
| `ROLE`, `ACTOR`, `LOCATION`, `BUSINESS_SERVICE` | within the organisation's element catalogue (`canon/elements/02_business/`). |
| `SCENARIO` | within the organisation's element catalogue (`canon/elements/05_implementation/scenarios/`), one file per SCENARIO. |
| `EQUIPMENT` | within the organisation's element catalogue (`canon/elements/04_technology/equipment/`), one file per EQUIPMENT (ADR 2026-06-08). |
| `NODE` | within the organisation's element catalogue (`canon/elements/04_technology/nodes/`), one file per NODE. |
| `TECHNOLOGY_SERVICE` | within the organisation's element catalogue (`canon/elements/04_technology/services/`), one file per TECHNOLOGY_SERVICE. |
| `BUSINESS_OBJECT` | within the organisation's element catalogue (`canon/elements/02_business/business-objects/`), one file per BUSINESS_OBJECT. `INFORMATION_ENTITY` is a deprecated alias for one release — its IDs resolve to the same catalogue; migrate IDs to the `BUSINESS_OBJECT-` prefix. |
| `RULE` | within the organisation's element catalogue (`canon/elements/02_business/rules/`), one file per RULE. |
| `REGISTRY` | within the organisation's element catalogue (`canon/elements/02_business/registries/`), one file per REGISTRY. A registry's **rows** are unique within their REGISTRY (canonical-by-containment); a row is promoted to its own registered standalone TYPE only when a second document references it (§1 promotion rule, [ELEMENT_PRIMITIVES.md](ELEMENT_PRIMITIVES.md) §1) — the same mechanic as a `PROCESS` flow step (§3.3). |
| `CONSTRAINT` | within the organisation's element catalogue (`canon/elements/01_motivation/constraints/`), one file per CONSTRAINT. |
| `REQUIREMENT` | within the organisation's element catalogue (`canon/elements/01_motivation/requirements/`), one file per REQUIREMENT. |
| `STAKEHOLDER` | within the organisation's element catalogue (`canon/elements/01_motivation/stakeholders/`), one file per STAKEHOLDER. |
| `ASSESSMENT` | within the organisation's element catalogue (`canon/elements/01_motivation/assessments/`), one file per ASSESSMENT. |
| `METRIC` | within the organisation's element catalogue (`canon/elements/01_motivation/metrics/`), one file per METRIC. |
| `RISK` | within the organisation's element catalogue (`canon/elements/01_motivation/risks/`), one file per RISK. |
| `NEED` | within the organisation's element catalogue (`canon/elements/01_motivation/needs/`), one file per NEED. |
| `TARGET_STATE` | within the organisation's element catalogue (`canon/elements/05_implementation/target-states/`), one file per TARGET_STATE. |
| `REL` | within the organisation's `canon/relations/` folder, one file per REL. |
| `MILESTONE` | within the action-card document that defines it. MILESTONE IDs are not required to be unique across the organisation; they are document-scoped element identifiers (the parent card binds them). |
| `ASSERTION` | within the organisation's `canon/assertions/` folder, one file per ASSERTION. |
| `VERIFICATION` | within the organisation's `canon/verifications/` folder, one file per VERIFICATION. |
| `VALIDATION` | within the organisation's `canon/validations/` folder, one file per VALIDATION. |
| `INTERVIEW`, `SURVEY`, `OBSERVATION`, `DRAFT`, `AMENDMENT`, `SEGMENT` | within the organisation's `field/` zone. Contradictions between Field artefacts are allowed; only the IDs must be unique. |
| `LAW`, `REGULATION` | within the organisation's `codex/external/` zone. |
| `POLICY`, `INTERNAL_STANDARD` | within the organisation's `codex/internal/` zone. |

Document-level IDs (`DGCA-…`, `FGA-…`, etc.) are unique within the organisation.

---

## 5. Cross-references

A cross-reference is a field whose value is an ID (or array of IDs) of another element. The pattern is consistent across notations:

- **Plural field name → array of typed IDs.** Example: `actions[].goals: [GOAL-1, GOAL-2]`.
- **Singular field name → single typed ID.** Example: `actions[].parent: PHASE-DESIGN`.
- **Child references parent.** A Goal references its driving Drivers via `factors: [DRIVER-…]`; a Change references its Goals via `goals: [GOAL-…]`; an Action references its Changes via `changes: [CHANGE-…]`. Any deviations are documented in the relevant notation spec.

A validator MUST check that every cross-reference resolves to a defined element of the correct TYPE. A reference to an undefined ID is an error; a reference whose target has the wrong TYPE prefix is also an error.

---

## 6. Migration checklist

The TYPE registry above was confirmed 2026-05-20. Several notations and example files still carry older, abbreviated, or untyped forms. Each row below is a follow-up migration: rewriting existing files is **out of scope for this appendix** and rolls out per notation as separate tasks.

| Old form | Canonical form | Where it appears | Notes |
|---|---|---|---|
| `ACT-…` | `ACTION-…` | examples under `examples/dgca/`, `examples/action/`; `07-action.md` §4 (`delivers_changes: [CHG-001]`). | follow-up |
| `ACTIVITY-…` | `ACTION-…` | any remaining files using the deprecated `ACTIVITY-` prefix — validators emit `ACTION-005`; migrate before 1.0 cut | follow-up |
| `activity_type` field | `type` field | any schedule or element file still using `activity_type` — validators emit `ACT-020` / `ACTION-005` | follow-up |
| `activities:` root array | `actions:` root array | any `*.action.transitrix.yaml` still using `activities:` top-level array — validators emit `ACT-020` | follow-up |
| `activity-card` notation key | `action-card` | any `*.action-card.transitrix.yaml` using `notation: activity-card` — validators emit `PC-005` | follow-up |
| `activity_card:` root field | `action_card:` | any action-card file using `activity_card:` — validators emit `PC-005` | follow-up |
| `CHG-…` | `CHANGE-…` | spec example in `07-action.md` §4; DGCA when its schema lands | follow-up |
| `FAC-…` | `DRIVER-…` | scenarios examples (`FAC-MARKET-001`, etc.); some FGA references | follow-up — note: canonical TYPE name is now `DRIVER`; existing `FACTOR-…` IDs are grandfathered (valid, no forced migration) |
| `CAP-…` | `CAPABILITY-V…` / `CAPABILITY-H…` | residual: `11-scenarios.md` spec example + `examples/scenarios/optimistic-2027.scenarios.transitrix.yaml` | capability-map / products / applications / process-map portion **executed 2026-05-28**; scenarios remains as a follow-up |
| `SCN-…` / `SCEN-…` | `SCENARIO-…` | `11-scenarios.md`; scenarios examples; `07-activities.md` (`scenario: SCEN-2026-OPT`) | follow-up — variant `SCEN` vs `SCN` also needs unifying |
| Integer-only IDs (`1`, `2`, …) | typed string IDs (`GOAL-1`, `DRIVER-1`, …) | originally the DGCA example | covered in the in-flight DGCA schema PR — see [transitrix/methodology#7](https://github.com/transitrix/methodology/pull/7) |
| `V1`, `V1.2`, `H1.2` (no `CAPABILITY-` prefix) | `CAPABILITY-V1`, `CAPABILITY-V1.2`, `CAPABILITY-H1.2` | residual: `examples/scenarios/omnichannel-2028.scenarios.transitrix.yaml`; prose mentions in `method/01-methodology.md`; `integration/studio.md` | capability-map / products / applications / process-map portion **executed 2026-05-28** (capability-map examples + cross-refs in products / applications / process-map specs, examples, and `acme_corp` views); scenarios + supporting docs remain |
| Zero-padded sequences (`001`, `002`, …) | no-leading-zero integers (`1`, `2`, …) | most example files | follow-up — purely a string-form change; sort order is unaffected because comparison is numeric |
| `INFORMATION_ENTITY-…` ids and `information_entities[]` blueprint field | `BUSINESS_OBJECT-…` ids and `business_objects[]` field | any blueprint that carries `information_entities[]` aspect entries with ids | one-release alias window; validator emits `BOBJ-D001` warning; hard error in the following release. Migration recipe in `migrations/0.5-to-0.6/` (additive follow-up). |

**Migration policy:** one follow-up issue per notation (spec + its examples). Do not bundle migrations into a single mega-PR — they touch different files and benefit from independent review.

---

## 7. References

- Notation catalogue and the index of all notations: [`README.md`](README.md).
- Capability addressing (the V/H system that the `CAPABILITY` exception relies on): [`05-capability-map.md`](views/05-capability-map.md) §4–5.
- Methodology: `method/01-methodology.md`.