Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ New to the ideas behind it? Read **[`method/01-foundations.md`](method/01-founda

## Documentation

- **[Semantic and architecture standards review](docs/standards-review/README.md)** — evidence, mapping limits and proposed interoperability profiles; includes the detailed ArchiMate differences register. The review is non-normative.
- **[Semantic Standards Profile](method/semantic-standards-profile.md)** — scopes, identities, provenance, validation claims and compatibility for semantic interoperability; links the [ArchiMate differences register](docs/standards-review/archimate-differences.md) and [non-normative review](docs/standards-review/README.md).
- **[ArchiMate 3.2 cheat sheet](https://transitrix.com/library/archimate-cheat-sheet/?utm_source=methodology-readme)** — elements by layer and aspect, relationships, and a printable PDF.
- **[`GETTING_STARTED.md`](GETTING_STARTED.md)** — a first modelling session, step by step, illustrated against the `acme-corp` worked example.
- **[`WALKTHROUGH.md`](WALKTHROUGH.md)** — a guided tour of the `acme-corp` worked example, read as one story.
Expand Down
5 changes: 5 additions & 0 deletions docs/standards-review/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@ interchange profiles. It is **non-normative**. Recommendations below do not adop
standards, change authoring rules, provide an exporter or establish conformance
or certification. YAML/Git authoring remains unchanged.

For the bounded normative documentation contract and actual candidate dispositions,
see the [Semantic Standards Profile](../../method/semantic-standards-profile.md).
The findings and proposals below retain their reviewed baseline and are not
retroactively relabeled as implemented capabilities or adopted ontology choices.

Read the [semantic evidence](semantic-evidence.md) for terminology, identity,
representation, validation and provenance; the [architecture evidence](architecture-evidence.md)
for architecture concepts and optional ontology/registry comparisons; and the
Expand Down
21 changes: 21 additions & 0 deletions docs/standards-review/archimate-differences.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@ modeling, precise meaning, clear authoring and verifiable behavior.

## Comparison basis and status

This is the authoritative detailed differences register for the
[Semantic Standards Profile](../../method/semantic-standards-profile.md).
SSP-10 requires an accepted change affecting a difference to update its stable
entry in the same delivery: edition/concept, source/revision, exact difference,
benefit/tradeoff, status, direction/loss, compatibility/consumers and decision
reference or explicit unknown. Retired IDs remain with successor notes.
The original comparison below remains a non-normative observation at its stated
baseline; assigning this register its home does not accept every proposed change.

Profile integration resolves AM-012/013's wording concerns in
[modelling guidance](../../method/03-modelling.md), the
[glossary](../../method/00-glossary.md#archimate-32-alignment) and the
[stakeholder specification](../../notations/elements/20-stakeholders.md).
Their historical findings remain for traceability; no parser, TYPE or relation
semantics is changed by those qualifications.

All Transitrix citations refer to
[`8ca4eabf7666946ffb7a76eb579c31cb0ae3f327`](https://github.com/transitrix/methodology/tree/8ca4eabf7666946ffb7a76eb579c31cb0ae3f327),
observed on 2026-10-10 and rechecked against main on 2026-10-11 without a delta.
Expand Down Expand Up @@ -368,6 +384,11 @@ to ArchiMate but drops those facts is not an improvement on these cases.

## Proposed maintenance rule

This section preserves the original review recommendation at the comparison
baseline. The current maintenance obligation is now specified by SSP-10 in the
[Semantic Standards Profile](../../method/semantic-standards-profile.md);
the historical candidate wording below is not a second normative authority.

Recommend **`docs/standards-review/archimate-differences.md` as the authoritative
detailed register**, with the glossary and cheat sheet linking to it after that
maintenance decision is accepted. The glossary remains a vocabulary introduction;
Expand Down
18 changes: 14 additions & 4 deletions method/00-glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Purpose:** Plain-language definitions of Transitrix terms and abbreviations, for readers who don't yet know the vocabulary. For anything that changes as the methodology evolves — the full TYPE registry, relation kinds, field names — this glossary links to the authoritative spec rather than repeating it, so it can't drift out of sync the way a duplicated list does.
**Format:** English
**Last updated:** 2026-07-04
**Last updated:** 2026-10-21

---

Expand All @@ -12,7 +12,7 @@
|---|---|
| **Transitrix** | Text-native methodology for managing enterprise architecture as code: models, processes, and capabilities stored as YAML files in a Git repository. |
| **Architecture-as-Code (AaC)** | Approach to defining and managing architecture through version-controlled text files rather than a GUI-only modelling tool. |
| **ArchiMate** | The Open Group's open standard for enterprise architecture modelling (current version: 3.2). Transitrix's element and relation vocabulary is grounded in it — see [ArchiMate alignment](#archimate-32-alignment) below. |
| **ArchiMate** | The Open Group's standard for enterprise architecture modelling. This methodology compares against edition 3.2; its element and relation vocabulary is grounded in that foundation — see [ArchiMate alignment](#archimate-32-alignment) below. |
| **Element** | An architectural primitive — the atomic unit of modelling (a goal, a role, a process, an application component). One element = one file. |
| **Relation (`REL`)** | A first-class, time-aware, typed link between two canonical primitives (`valid_from` / `valid_to`), stored as its own file under `canon/relations/`. See [`elements/17-relations.md`](../notations/elements/17-relations.md) for the closed enum of relation kinds (e.g. `parent`, `action_goal`, `depends_on`, `offers`, `realizes`, `hosts`, `uses`). |
| **Atomicity** | Principle by which an element's description and its relations are stored in separate files — an element file never inlines a first-class relation. |
Expand Down Expand Up @@ -96,7 +96,13 @@ Full grammar, the exception, and the complete TYPE registry (element types, docu

## ArchiMate 3.2 alignment

Transitrix is grounded in ArchiMate 3.2 but uses deliberately simplified or domain-friendly names in a few places. This table records only the **intentional divergences** — for the full TYPE list see [`notations/IDS_AND_REFERENCES.md`](../notations/IDS_AND_REFERENCES.md) §3.
ArchiMate 3.2 is Transitrix's starting foundation. Model representation quality,
precision and useful validation take precedence over strict fidelity. Similar
names do not establish equivalent semantics. The authoritative detailed
[ArchiMate differences register](../docs/standards-review/archimate-differences.md)
records exact differences, rationale, status, direction, loss and compatibility;
the table below is only a terminology introduction, not a second mapping registry.
For the full TYPE list see [`notations/IDS_AND_REFERENCES.md`](../notations/IDS_AND_REFERENCES.md) §3.

| Transitrix TYPE | ArchiMate 3.2 term | Note |
|---|---|---|
Expand All @@ -108,7 +114,11 @@ Transitrix is grounded in ArchiMate 3.2 but uses deliberately simplified or doma
| `ACTOR` | Business Actor | A single active-structure identity type (`person` \| `business_unit` \| `system`) replacing the former separate `UNIT` / `EMPLOYEE` TYPEs. |
| `TERM` | Meaning | "Term" is more accessible than ArchiMate's "Meaning" for a business-vocabulary entry (name + definition, no modelled behaviour). |

Everything else in the registry (`GOAL`, `DRIVER`, `CONSTRAINT`, `REQUIREMENT`, `STAKEHOLDER`, `ASSESSMENT`, `EQUIPMENT`, `ROLE`, `PROCESS`, `CAPABILITY`, `APPLICATION`, `NODE`, `TECHNOLOGY_SERVICE`, `BUSINESS_SERVICE`, `LOCATION`, …) uses the ArchiMate term directly or a name aligned with it — no divergence to record.
Other names can align with ArchiMate while their structure, lifecycle, endpoints
or interpretation still differ. Consult the detailed register before asserting
equivalence; unmapped or lossy cases remain explicit. The
[Semantic Standards Profile](semantic-standards-profile.md) distinguishes concept,
class and instance and specifies identity, evidence and mapping-claim boundaries.

---

Expand Down
11 changes: 11 additions & 0 deletions method/03-modelling.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,17 @@ Two file shapes do most of the work: **elements** (objects) and **relations** (c

### 1.1 Element template

The simplified examples in §1.1–1.2 illustrate objects and edges; they are
**not canonical authoring templates**. Canonical primitives use `notation`, the
per-TYPE subtype vocabulary and the shared admission/lifecycle envelope; canonical
REL files use `from` / `to` and the local kind enum. Copy the
[primitive contract](../notations/ELEMENT_PRIMITIVES.md) or
[canonical REL schema](../notations/elements/17-relations.md)
when authoring. `ApplicationComponent`, `source` / `target` and `Access` below
are conceptual illustration labels, not newly admitted canonical values.
No parser conversion is implied. For comparisons and exchange claims use the
[Semantic Standards Profile](semantic-standards-profile.md) and its linked register.

```yaml
id: "APPLICATION-ORDERS-1" # TYPE-DOMAIN-INTEGER, uppercase, hyphens only, no leading zeros
name: "Order API" # Human-readable name
Expand Down
Loading
Loading