diff --git a/README.md b/README.md index ca048d2..0627f0a 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/standards-review/README.md b/docs/standards-review/README.md index 252ec41..b6ca3dc 100644 --- a/docs/standards-review/README.md +++ b/docs/standards-review/README.md @@ -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 diff --git a/docs/standards-review/archimate-differences.md b/docs/standards-review/archimate-differences.md index 95adf65..d9840e5 100644 --- a/docs/standards-review/archimate-differences.md +++ b/docs/standards-review/archimate-differences.md @@ -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. @@ -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; diff --git a/method/00-glossary.md b/method/00-glossary.md index 44f5025..cc7ae9d 100644 --- a/method/00-glossary.md +++ b/method/00-glossary.md @@ -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 --- @@ -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. | @@ -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 | |---|---|---| @@ -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. --- diff --git a/method/03-modelling.md b/method/03-modelling.md index 0c4c7a1..e1fc11e 100644 --- a/method/03-modelling.md +++ b/method/03-modelling.md @@ -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 diff --git a/method/semantic-standards-profile.md b/method/semantic-standards-profile.md new file mode 100644 index 0000000..f1b0dc5 --- /dev/null +++ b/method/semantic-standards-profile.md @@ -0,0 +1,207 @@ +# Transitrix Semantic Standards Profile + +**Profile version: 1.0.** This is the normative documentation contract for an +explicit claim of conformity to this profile. It does not assert that existing +Transitrix tools implement RDF exchange, OWL reasoning, SHACL validation or a +SPARQL endpoint. Canonical authoring remains Git/YAML under the +[notation contract](../notations/CONTRACT.md); existing file schemas, identifiers, +admission rules and diagnostic meanings are unchanged. + +Architects can read a [concise interoperability explanation](https://transitrix.com/semantic-standards/?utm_source=methodology-semantic-profile). +The [standards review](../docs/standards-review/README.md) supplies the evidence, +editions, findings and access limitations behind this profile. The +[ArchiMate differences register](../docs/standards-review/archimate-differences.md) +is the single detailed home for comparisons, including partial and lossy mappings. +Neither this profile nor that register establishes standards certification. + +## Scope, language and conformance + +**MUST** identifies an obligation for the explicitly claimed scope. **SHOULD** +identifies a recommendation: a departure needs a stated reason, assessed effect +and evidence. **MAY** identifies a permitted option. These words express this +Transitrix contract, not a reproduction of inaccessible standards requirements. + +There are three independently declared scopes: + +- **A — authoring and interpretation:** definitions, original local identities, + source authority and truthful capability/mapping claims. This adds no required + YAML fields or new automated admission gate. +- **X — a described semantic interchange:** an optional mapping contract and its + selected formats, identity, context, loss, evidence and compatibility. Choosing + X does not commission an exporter or replace source storage. +- **T — a tool's claim of profile support:** the exact implemented subset, versions, + test evidence, limitations and unsupported behavior. A documentation proposal + is not an implementation claim. + +A conformity declaration MUST identify profile version, subject/source revision, +selected scopes and formats, satisfied rule IDs, evidence and explicit deviations. +It MUST NOT use a partial scope as a claim that all Transitrix software conforms, +or treat conformity to this local profile as conformity to an external standard. +There is no default claim for an existing model or tool merely because it uses +Transitrix terminology. A diagram, valid YAML, successful render or approved +assertion alone is insufficient evidence. + +For a SHOULD deviation or permitted exception, record the rule, scope, reason, +alternative, responsible maintainer, affected versions and evidence. An exception +cannot authorize a false implementation/conformance claim, label unknown evidence +as verified, or hide semantic loss. An incompatible core/schema change, a concrete +ontology adoption or a new service requires its own recorded architecture decision +and compatibility work; this profile supplies none of those decisions. + +## Concepts, identity and authority + +A **taxonomy** is an organized concept scheme for classification or retrieval, +with explicitly interpreted broader/narrower/related links. An **ontology** defines +classes, properties and their formal interpretation or axioms. A **knowledge graph** +is a selected graph or dataset of identified resources and assertions, with declared +context and evidence; being graph-shaped alone does not establish an ontology or +entailment regime. A taxonomy can index resources in a knowledge graph; an optional +ontology can describe their classes. None of these roles implies another. + +`skos:Concept`, `owl:Class` and an individual have distinct semantic roles. A +retrieval concept about applications is not the class of applications, and neither +is a particular application. Sharing a label does not justify identity or class +equivalence. Deliberate metamodeling must name its interpretation and test its +consequences; it cannot silently reinterpret a canonical TYPE or TERM. Existing +[TERM and glossary semantics](../notations/ELEMENT_PRIMITIVES.md) remain +authoritative; an enterprise object's definition is not duplicated as a TERM. + +ArchiMate 3.2 is a starting foundation, not an overriding fidelity constraint. +Preserve useful distinctions in identity/stake, history, obligations and evidence. +Compare actual meanings, direction and applicability rather than substitute +similarly named types or relations. The element/relation specifications remain +authoritative for Transitrix behavior; the differences register explains comparisons. + +## Applicable rules and evaluation + +All rule evidence is bound to the declared subject, source/methodology/profile +revision and selected scope. Standards locators and known access limits are in +the [semantic](../docs/standards-review/semantic-evidence.md#authoritative-source-register) +and [architecture](../docs/standards-review/architecture-evidence.md#sources-and-access) +source registers. A source field's presence establishes a declaration, not its truth. + +| Rule / scope | Standard and finding | Transitrix obligation | How satisfaction is evaluated | +|---|---|---|---| +| **SSP-01 — roles and interpretation; A/X/T** | SKOS 2009 §§3–5, OWL 2 Structural 2012 §§5/9; SE-01/07 | MUST distinguish concept, class and individual; MUST NOT infer identity from labels or `subClassOf` from organizational parentage. A deliberate metamodeling option MUST state its separate interpretations. | Three-role example and a rejected same-label merge; preserve existing duplicate-TERM behavior. No unreviewed TYPE reinterpretation. | +| **SSP-02 — persistent identifiers; X/T** | RDF 1.1 Concepts 2014 §3.2; SE-02 | MUST preserve local ID, catalogue identity and containment scope separately from the resource IRI. MUST document namespace controller, minting rule, collision policy, persistence and successor/redirect policy. A branch/path/repository basename alone MUST NOT define identity. | Two catalogues with the same local ID produce distinct resources; relocation retains identity; contained-object promotion has an explicit mapping. No specific production namespace or registry service is selected here. | +| **SSP-03 — reuse and mappings; A/X/T** | SKOS 2009 §10, RDF 1.1; SE-01/02/07, REC-03 | SHOULD reuse an applicable published vocabulary with pinned edition/context; MUST state a mapping's direction, strength, source/version, provenance and loss. MUST NOT turn label similarity into `owl:sameAs`, exactMatch or class equivalence. | Distinguish exact, broader/narrower, related and unmapped cases. A partial or lossy projection is labeled as such; no lossless claim without evidence. | +| **SSP-04 — graph and formats; X/T** | RDF 1.1 Concepts 2014 §§3–4, Turtle 2014, JSON-LD 1.1 2020; SE-03 | MUST declare graph/dataset selection and selected exchange formats. RDF claims MUST use RDF 1.1 semantics. A Turtle target MUST state how a dataset is packaged; a JSON-LD target MUST pin its context and coercion/list/null rules. MUST preserve relation identity and supported fields or explicitly report loss. | Reconstruct parallel/recurring RELs, endpoint/window selection, admission, history, missing/null/default values, ordered occurrences and unknown extensions. Byte-identical YAML round trip is not promised without retained source bytes. | +| **SSP-05 — assertion provenance; A/X/T** | PROV-O 2013 §§3–4; SE-06, C4 | MUST distinguish declared, observed/imported, inferred and AI-proposed evidence where such a claim is made. MUST identify source/locator, source and record versions, responsible agent and time, or explicitly retain unknowns. SHOULD map to PROV-O where exchanging that evidence. | Demonstrate all four bases, missing/denied evidence and differing assertion sources. Inference retains input/rule versions; an import proves source presence, not enterprise truth. Admission/approval and document generation remain separate. No retrospective fabricated evidence. | +| **SSP-06 — validation and queries; X/T** | SHACL 1.0 2017 §§2–5, SPARQL 1.1 Query 2013 §§8–9/13/16–17, OWL 2 Profiles 2012 §§4.2–4.3; SE-04/05 | MUST separate structural constraints, inference and admission. A SHACL claim MUST identify shapes/data graphs and engine/version; a SPARQL claim MUST identify dataset/time/entailment and completeness. Denied/incomplete scope MUST remain unknown at the adapter boundary. SHOULD preserve original diagnostic identities and versions. | Positive and negative H/Q cases, time boundaries, endpoint lifecycles and graph isolation. An OWL/RL claim needs its own syntax/entailment tests. No engine, endpoint or inference is required merely to author YAML. | +| **SSP-07 — vocabulary lifecycle; A/X/T** | RDF/SKOS identity, DCAT 3 2024 version metadata; SE-02/03/07/08 | MUST distinguish resource identity, description snapshot, vocabulary/profile version and source-methodology version. MUST retain deprecated IDs with successor and compatibility notes; MUST NOT reuse an ID for a different meaning. SHOULD publish mappings for renamed or retired terms. | Existing references remain interpretable after rename/deprecation; new versions identify changed meanings/contexts and losses. No automatic deletion, redirect service or tool behavior is assumed. | +| **SSP-08 — compatibility; A/X/T** | Local compatibility contract §10; SE-02–07, REC-03/04 | MUST assess changed identity, meaning, required fields, relation direction, context expansion and diagnostics against consumers. MUST document migration/version implications before an incompatible implementation. Optional outputs MAY be additive; no automatic major/minor classification overrides the existing contract. | Compare before/after interpretations and affected parsers, resolvers, views/reports, catalogue bindings and historical queries. Keep unsupported/unknown distinct from success. | +| **SSP-09 — terminology; A** | ISO 704:2022 / 1087:2019 scope, SKOS 2009; SE-07, C5 | SHOULD describe concept/context, definition, preferred designation, other designations, relations and examples/non-examples. MUST label ISO clause correspondence unevaluated where full evidence is unavailable. | Review non-circular definitions, language-specific labels and non-equivalent mappings without duplicating canonical enterprise definitions. No new mandatory terminology fields or unsupported ISO compliance claim. | +| **SSP-10 — architecture and mapping register; A/X/T** | ISO 42010:2022 conceptual mapping, ArchiMate 3.2; ARC-001–009/015, AM-001–014 | MUST identify comparison edition and subject; MUST preserve partial/non-equivalent mappings. A change introducing, changing or removing an ArchiMate difference MUST update its stable register entry in the same change. SHOULD use an optional AD evidence companion where stakeholder/concern coverage matters. | Entry contains edition/concept, exact Transitrix path/revision, difference, benefit/tradeoff, status, direction/loss, consumers/compatibility and decision reference or explicit unknown. Retain deprecated IDs; do not promote proposals to accepted semantics without a recorded decision. | +| **SSP-11 — claim boundaries and optional metadata; A/X/T** | PROV-O/DCMI Terms 2020/DCAT 3 2024; REC-01/05/06 | MUST state implemented versus specified/proposed/unevaluated capability. MAY use Dublin Core for actual described resources and DCAT for real datasets/distributions. MUST NOT invent a service, selected upper ontology, external registration, conformance or certification. | Inspect claim, named resource/consumer, exact implementation/test evidence and remaining unknowns. No specific BFO/DOLCE/ODM/11179 profile or external system follows from this document. | + +## Disposition of the reviewed candidates + +The review's preliminary stack is not a universal replacement for current authoring. +This version specifies the following bounded documentation contract; an unimplemented +selected target still needs separate source, decision, compatibility and release evidence. + +| Candidate | Disposition and rationale | Scope / findings | +|---|---|---| +| RDF 1.1, stable IRIs, named graphs | Change universal adoption to explicit X/T claims. Retain scoped persistent identity and declared context; named graphs are recommended where context/provenance requires them. | SSP-02/04; SE-02/03. No mandatory RDF storage. | +| Turtle and JSON-LD 1.1 | Change universal format mandates to requirements for each selected target. A claimed format must preserve its stated contract; neither format alone supplies a Transitrix mapping. | SSP-04; SE-03. No exporter is delivered. | +| SKOS / ISO 25964-1:2011 and -2:2013 | Retain SKOS as a selected concept-scheme mapping; defer ISO normative correspondence without full evidence. A glossary is not automatically a thesaurus. | SSP-01/03/09; SE-01/07. Optional retrieval profile. | +| OWL 2 / RL | Defer mandatory ontology/inference adoption. A selected optional ontology must declare interpretation and regime; no inference by default is introduced into existing tools. | SSP-01/06; SE-04/A3. Concrete ontology choice requires a separate decision. | +| SHACL 1.0 | Change universal validator requirement to explicit X/T graph-constraint claims, separated from current validators and admission. | SSP-06; SE-04. H1/H2 remain illustrative shapes. | +| SPARQL 1.1 | Change blanket support to explicit query claims with dataset/completeness evidence. Query examples do not implement Update, Protocol or an endpoint. | SSP-06; SE-05. Q1–Q3 are examples. | +| ISO 704:2022 / ISO 1087:2019 | Use original concept-oriented guidance; defer clause-level normative correspondence. Full text was unavailable in the review. | SSP-09; SE-07. No certification or new core schema. | +| ISO/IEC/IEEE 42010:2022 / 42020:2019 | Retain edition-specific conceptual alignment; defer conformance and new process mandates pending complete evidence. | SSP-10/11; ARC-001–010. Architecture Model has the review's 2022 qualification. | +| PROV-O | Retain optional provenance interchange, with required truthful source/basis distinctions for evidence claims. | SSP-05; SE-06. Existing document provenance remains separate. | +| Dublin Core Terms / DCAT 3 | Retain conditionally for actual resources/datasets and consumers, not every catalogued element. | SSP-11; SE-08. No invented service or registry. | +| ISO/IEC 21838-1:2021 / BFO / DOLCE | Defer upper-ontology adoption; neither a specific ontology nor its axioms are selected. A concrete choice needs a dedicated architecture decision and representative cases. | SSP-11; ARC-011–013. No required core classification. | +| ArchiMate 3.2 / OMG ODM 1.1 | Retain optional mappings with explicit edition, direction and losses; reject blanket equivalence. Adopt one detailed differences-register home and same-change maintenance for comparisons. | SSP-03/10; ARC-014/015, AM-001–014. No exchange implementation or license path selected. | +| ISO/IEC 11179 selected 2023 parts | Defer general adoption; a bounded registry profile must select its parts, target and evidence independently. | SSP-11; ARC-016. Catalogue binding does not establish external registration. | + +Remaining architecture choices—production namespace ownership/minting, concrete +exchange mapping and time/default policy, inference regime, terminology schema, +provenance capture implementation, structured AD companion and ontology/registry +selection—are not decided here. The rules require them to be declared/evidenced +before the corresponding implementation or conformance claim. Deferral is explicit, +not an implementation backlog automatically commissioned by this profile. + +## Worked interpretation: concept, class and instance + +This fictional example demonstrates SSP-01–05/07; all namespaces are illustrative, +not published Transitrix vocabulary. Assume a publisher controls the immutable +catalogue identity `example-catalogue-1` and its `https://example.org/catalogue/one/` +namespace. Its policy keeps resource IRIs stable across repository moves and gives +description snapshots separate versioned IRIs. A second catalogue uses another +namespace even if its YAML also contains `APPLICATION-PAYMENTS-1`. + +```turtle +@prefix res: . +@prefix concept: . +@prefix onto: . +@prefix record: . +@prefix external: . +@prefix skos: . +@prefix owl: . +@prefix prov: . +@prefix dct: . +@prefix xsd: . + +concept:topics a skos:ConceptScheme . +concept:payment-processing a skos:Concept ; + skos:inScheme concept:topics ; skos:prefLabel "Payment processing"@en ; + skos:relatedMatch external:payment-processing . +onto:Application a owl:Class . +res:APPLICATION-PAYMENTS-1 a onto:Application ; + dct:identifier "APPLICATION-PAYMENTS-1" ; + dct:subject concept:payment-processing . + +record:subject-assertion-1 a prov:Entity ; + record:subject res:APPLICATION-PAYMENTS-1 ; + record:predicate dct:subject ; record:object concept:payment-processing ; + record:basis "declared" ; record:version "1" ; + prov:wasDerivedFrom record:source-snapshot-1 ; + prov:wasAttributedTo record:author-1 ; + prov:generatedAtTime "2026-10-21T00:00:00Z"^^xsd:dateTime . +record:source-snapshot-1 a prov:Entity ; record:sourceVersion "source-revision-1" . +record:author-1 a prov:Agent . +record:mapping-1 a prov:Entity ; + record:subject concept:payment-processing ; + record:predicate skos:relatedMatch ; record:object external:payment-processing ; + record:direction "local-to-external" ; record:loss "related, not equivalent" ; + record:basis "declared" ; record:version "1" ; + prov:generatedAtTime "2026-10-21T00:00:00Z"^^xsd:dateTime ; + prov:wasDerivedFrom external:scheme ; + prov:wasAttributedTo record:author-1 . +external:scheme record:sourceVersion "1" . +``` + +The concept supports retrieval, the class describes an optional ontology +interpretation, and the application is an instance. `relatedMatch` deliberately +does not promise equivalence. The source-backed assertion is declared, not proved; +its admission and any document-generation evidence are separate. Mapping direction +and source version are recorded rather than inferred from the edge alone. + +For a revision that deprecates the concept, retain its IRI, old snapshot and a +replacement/compatibility note. A new preferred label does not change instance +identity. Changing the class meaning or upgrading relatedMatch to exactMatch is +a semantic change requiring evidence and compatibility review, not cosmetic editing. + +Reject these interpretations: one shared label means all three resources are +`owl:sameAs`; moving a repository requires minting all object IRIs again; a missing +provenance timestamp may be invented; a shape pass admits a fact; or the example +proves a production exporter exists. For concrete graph-constraint/query examples +and counterexamples, reuse [the review's H/Q cases](../docs/standards-review/semantic-evidence.md#non-normative-shacl-examples). + +## Maintenance and compatibility + +The [differences register](../docs/standards-review/archimate-differences.md) remains +the one detailed comparison source; glossary and guidance link to it. SSP-10 applies +to future accepted changes introducing, changing or removing a difference in the +same delivery. Existing baseline observations do not become accepted semantic +changes merely because this profile names the register. + +Profile versions are separate from methodology, vocabulary, context, shape/query +and tool versions. A changed mandatory interpretation or incompatible profile claim +requires a major profile version; additive optional guidance can use a minor version; +editorial corrections can use a patch. Core methodology compatibility and migration +remain governed by [CONTRACT §10](../notations/CONTRACT.md#10-versioning-and-compatibility). +Tool support and release propagation require their own evidence; prose does not +silently migrate stored models or upgrade installed consumers. diff --git a/notations/README.md b/notations/README.md index dc06cd1..f0947fc 100644 --- a/notations/README.md +++ b/notations/README.md @@ -6,6 +6,11 @@ For the shared envelope and GOAL, ACTION, REQUIREMENT and VERIFICATION fields, see [Reading fields by purpose](field-purpose.md): source data, provenance, admission history and derived diagnostics, with worked readings. +For semantic roles, persistent identity, mapping losses, provenance and truthful +tool-support claims, read the [Semantic Standards Profile](../method/semantic-standards-profile.md). +Its [ArchiMate differences register](../docs/standards-review/archimate-differences.md) +records comparison limits; it does not replace the element/relation contracts here. + ## Views The view notations live under [`views/`](views/), split by class into a folder per class — [`diagrams/`](views/diagrams/), [`reports/`](views/reports/), and [`documents/`](views/documents/) — so a spec's class is a filesystem fact, not a table position. Studio also renders **PlantUML** (`.puml`/`.plantuml`) natively — no separate Transitrix notation is needed for it. diff --git a/notations/elements/20-stakeholders.md b/notations/elements/20-stakeholders.md index 8e6c41f..70c353e 100644 --- a/notations/elements/20-stakeholders.md +++ b/notations/elements/20-stakeholders.md @@ -111,7 +111,7 @@ The shared header (`HDR-001..004`, [CONTRACT.md](../CONTRACT.md) §2) and primit ## 6. Evolution -- **Concern as a separate primitive.** ArchiMate models a stakeholder's *concern* as its own element. v0.1 inlines `concern` as free text; a `CONCERN` primitive is deferred until needed. +- **Concern as a separate primitive.** Transitrix currently uses free-text `concern`; no canonical `CONCERN` TYPE is established here. ISO/IEC/IEEE 42010:2022's Concern is a separate comparison from ArchiMate's Stakeholder; a shared label does not prove equivalent first-class elements. See [ARC-005](../../docs/standards-review/architecture-evidence.md#nine-architecture-concepts) and [AM-013](../../docs/standards-review/archimate-differences.md) for evidence and limits. A new structured concern model requires its own decision and compatibility review. - **External-organisation reference.** An external stakeholder often *is* an organisation; v0.1 models it as an `ACTOR(business_unit)` with `external_ref`. A dedicated external-org entity is out of scope. - **Action Card stakeholders block.** Once this notation lands, Action Card v0.2 (#97 follow-up) renders a stakeholders panel from the `stakeholding` relations whose target is the action. - DSM formalisation (the `stakeholder.type` enum + `action_stakeholder` join, legacy alias `activity_stakeholder`) is a `proj:transitrix-dsm` track; this spec defines only the methodology side. diff --git a/publish-manifest.json b/publish-manifest.json index 5c141e9..a3e5613 100644 --- a/publish-manifest.json +++ b/publish-manifest.json @@ -88,6 +88,7 @@ "method/07-decisions.md", "method/08-governance.md", "method/09-releases-and-propagation.md", + "method/semantic-standards-profile.md", "migrations/0.5-to-0.6/README.md", "migrations/0.5-to-0.6/codemod.mjs", "migrations/0.5-to-0.6/fixtures/after/canon/elements/02_business/roles/ROLE-OPS-1.yaml",