docs: expand ontology docs and diagrams

Author: jgeluk

docs/concept/.pages.yaml

@@ -5,6 +5,7 @@ nav:
   - persona.md
   - story.md
   - concept.md
+  - term.md
   - outcome.md
   - data-product.md
   - ontology.md

docs/concept/concept.md

@@ -213,3 +213,65 @@ business concepts_
     - **[Ontologies](ontology.md)** — Concepts link to ontology
       classes, properties, and shapes
 
+=== "Ontology"
+
+    ## Ontology (minimal facts we can state today)
+
+    --8<-- "fragment/uctm-diagram-concept.md"
+
+    We're not (yet) prescribing a full OWL ontology here.
+    But we can state a small set of **facts** that people can reliably use to build their own
+    ontology / schema / graph model around a Concept.
+
+    ### Required facts about a Concept
+
+    - **Opaque universally unique identifier**
+        - A Concept must have an **opaque**, **universally unique** identifier.
+        - Prefer a random identifier such as **UUIDv4**.
+        - Represent it as a URI, for example:
+          `urn:uuid:550e8400-e29b-41d4-a716-446655440000`
+
+    - **Slug**
+        - A Concept should have a kebab-cased slug.
+        - Slug uniqueness cannot be guaranteed, but it can be used as a convenient alternative
+          identifier next to the real identifier (with lookup/search).
+        - Do **not** use the slug as a foreign key in the Knowledge Graph itself; use the real
+          identifier for references.
+
+    - **Label Term (instead of a traditional label)**
+        - A Concept does not have a traditional label such as `skos:prefLabel` or `rdfs:label`.
+        - Instead, it has a **labelTerm** link to one of its **BusinessTerm** objects (a resource
+          in the Knowledge Graph).
+        - Learn more in [Term](term.md).
+
+    - **Definition**
+        - A Concept must have a business-focused definition explaining what it means in context.
+
+    - **One or more Terms (required)**
+        - A Concept must have **one or more Terms** (`Term`), which can be either a
+          **BusinessTerm** or a **TechnicalTerm**.
+        - A Concept without a Term has no reason to exist.
+        - All Terms of a Concept **mean the same thing** in the context of that Concept.
+        - Terms may include alternative spellings, abbreviations, synonyms, and technical
+          manifestations.
+        - Terms are **owned** by the Concept (part-of): when the Concept is deleted, its Term
+          objects are deleted as well.
+        - Learn more in [Term](term.md).
+
+    - **Contained in a Concept Vocabulary**
+        - A Concept is a member of a Concept Vocabulary (a “container” of Concepts).
+        - A Use Case can relate to Concept Vocabularies via relationship-objects:
+            - it can **reference** an external vocabulary and/or
+            - **own** a private vocabulary.
+
+    - **Mapping to ontologies (optional)**
+        - A Concept can be mapped/aligned to terms in one or more ontologies (classes,
+          properties, shapes).
+        - Model this via mapping/alignment relationships so you can capture confidence, rationale,
+          and provenance.
+
+    - **Used by Stories and Workflows**
+        - Stories use Concepts as **input**, **output**, and **dependent** concepts.
+        - Workflows use Concepts through the Stories they orchestrate and the vocabulary of the
+          Use Case.
+

docs/concept/outcome.md

@@ -206,3 +206,51 @@ from a Use Case, providing the "why" behind every business requirement_
     This integration ensures that outcomes are not abstract goals but
     concrete, measurable results that drive the EKG's value
     proposition.
+
+=== "Ontology"
+
+    ## Ontology (minimal facts we can state today)
+
+    --8<-- "fragment/uctm-diagram-outcome.md"
+
+    We're not (yet) prescribing a full OWL ontology here.
+    But we can state a small set of **facts** that people can reliably use to build their own
+    ontology / schema / graph model around an Outcome.
+
+    ### Required facts about an Outcome
+
+    - **Opaque universally unique identifier**
+        - An Outcome should have an **opaque**, **universally unique** identifier.
+        - Prefer a random identifier such as **UUIDv4**, represented as a URI:
+          `urn:uuid:550e8400-e29b-41d4-a716-446655440000`
+
+    - **Business-friendly name**
+        - An Outcome must have a human-readable name expressed in business language.
+
+    - **Definition**
+        - An Outcome must have a definition explaining the expected benefit/result.
+
+    - **Stereotype**
+        - An Outcome can have an **Outcome Stereotype** (e.g. KPI, Goal, Objective, Success
+          Criteria, Definition of Done).
+        - Stereotypes categorize outcomes without changing the underlying “Outcome” concept.
+
+    - **Time horizon (optional)**
+        - Outcomes often imply a time horizon (short/mid/long term). Capture it explicitly if
+          it matters.
+
+    - **Measurability (optional but recommended)**
+        - Outcomes should have measurable success criteria where possible (metrics, thresholds,
+          targets, baselines).
+
+    - **Owned by a Use Case (optional)**
+        - Outcomes are often defined/owned by a Use Case, but can be referenced by other Use
+          Cases (e.g., children).
+
+    - **Use Case ↔ Outcome relationship-object (recommended)**
+        - Model the connection between a Use Case and an Outcome via a **relationship-object**
+          (not just a direct link).
+        - This supports:
+            - **Inheritance**: a child Use Case referencing an Outcome defined on a parent Use Case
+            - **Contribution mapping**: describing *how* the child contributes to that desired Outcome
+            - **Local outcomes**: linking to Outcomes owned by the current Use Case as well

docs/concept/persona.md

@@ -211,7 +211,6 @@ or entities — involved in a Use Case, defined using business language_
     `<persona-B>`, then the user is also associated with
     `<persona-B>`.
 
-
 === "Model"
 
     ## Overview
@@ -239,3 +238,46 @@ or entities — involved in a Use Case, defined using business language_
     integrated components of the Enterprise Knowledge Graph,
     enabling automated reasoning, policy enforcement, and
     composability.
+
+=== "Ontology"
+
+    ## Ontology (minimal facts we can state today)
+
+    --8<-- "fragment/uctm-diagram-persona.md"
+
+    We're not (yet) prescribing a full OWL ontology here.
+    But we can state a small set of **facts** that people can reliably use to build their own
+    ontology / schema / graph model around a Persona.
+
+    ### Required facts about a Persona
+
+    - **Opaque universally unique identifier**
+        - A Persona should have an **opaque**, **universally unique** identifier.
+        - Prefer a random identifier such as **UUIDv4**, represented as a URI:
+          `urn:uuid:550e8400-e29b-41d4-a716-446655440000`
+
+    - **Business-friendly name**
+        - A Persona must have a human-readable name (e.g., “Auditor”, “Chief Risk Officer”).
+
+    - **Slug**
+        - A Persona should have a kebab-cased slug (convenient identifier; do not use as a foreign
+          key in the Knowledge Graph).
+        - Example: `auditor`, `chief-risk-officer`, `legal-entity-maintainer`
+
+    - **Definition**
+        - A Persona should have a definition describing who it represents in the domain.
+
+    - **Persona inheritance (optional)**
+        - Personas can be related via `isSubPersonaOf` for hierarchical organization.
+
+    - **Persona taxonomy membership (required)**
+        - Personas are `skos:Concept`.
+        - Every Persona is a member of exactly one **PersonaTaxonomy** (a `skos:ConceptScheme`)
+          via `skos:inScheme`.
+        - Each Use Case can have **zero or one PersonaTaxonomy** that provides the scheme for
+          Personas used in that Use Case.
+
+    - **Participation in Stories (relationship-object)**
+        - Stories reference Personas in the “Who” part.
+        - Model the connection via a relationship-object if you need to capture context such as
+          role, responsibility, entitlement, or provenance.

docs/concept/story.md

@@ -201,3 +201,54 @@ defines what a Persona needs to accomplish within a Use Case_
     This integration ensures that Stories are not isolated
     requirements but part of a cohesive, semantic model of the
     enterprise.
+
+=== "Ontology"
+
+    ## Ontology (minimal facts we can state today)
+
+    --8<-- "fragment/uctm-diagram-story.md"
+
+    We're not (yet) prescribing a full OWL ontology here.
+    But we can state a small set of **facts** that people can reliably use to build their own
+    ontology / schema / graph model around a Story.
+
+    ### Required facts about a Story
+
+    - **Opaque universally unique identifier**
+        - A Story must have an **opaque**, **universally unique** identifier.
+        - Prefer a random identifier such as **UUIDv4**.
+        - Represent it as a URI, for example:
+          `urn:uuid:550e8400-e29b-41d4-a716-446655440000`
+
+    - **Business-friendly name**
+        - A Story should have a concise, human-readable name.
+
+    - **Slug**
+        - A Story should have a kebab-cased slug that is unique at least within the organization.
+        - Example: `assess-risk-position`, `verify-stakeholders`
+
+    - **Business-focused definition**
+        - A Story must have a plain-language definition of what the user needs.
+
+    - **Structured statement (who / what / why)**
+        - A Story should capture:
+            - **Who**: a reference to a Persona (or persona-like Concept)
+            - **What**: the capability/action needed
+            - **Why**: a reference to an Outcome (the intended business value)
+
+    - **Owned by a Use Case**
+        - A Story is **part-of** a Use Case: the Use Case **owns** the Story.
+        - If the owning Use Case is deleted, its Stories are deleted as well.
+
+    - **Concept usage (relationship-object)**
+        - Model the relationship between a Story and a Concept as a **relationship-object**
+          (not a direct link), because it carries meaning about *how* the Concept is used.
+        - The relationship-object defines a usage type, for example:
+            - **Input Concept** — required/mandatory input parameter (or optional)
+            - **Output Concept** — definition of the output (often a shape/compound object)
+            - **Dependent Concept** — referenced in filters/constraints (e.g., SQL/SPARQL `WHERE`)
+
+    - **Workflow participation**
+        - A Story can participate as a **Step** in one or more WorkflowDefinitions.
+        - Model this via a relationship-object (e.g. a “WorkflowStep”) so you can capture step
+          order, conditions, and other execution semantics.

docs/concept/term.md

@@ -0,0 +1,159 @@
+---
+description: "A manifestation of a Concept: a business-facing or technical term (e.g., synonyms, abbreviations, variable names) that all mean the same thing in the Concept’s context. Learn how Terms work in the Use Case Tree Method."
+keywords:
+  - term
+  - business term
+  - technical term
+  - concept term
+  - EKG method
+  - enterprise knowledge graph
+schema_type: "Article"
+---
+
+# Term
+
+<!--summary-start-->
+_A manifestation of a Concept: the words (business-facing and technical) used to refer to the same underlying meaning_
+<!--summary-end-->
+
+=== "Business & Management Audience"
+
+    ## What Is a Term?
+
+    A **Term** is a word or phrase people use to refer to a [Concept](concept.md) in a given
+    context.
+    Concepts are about **meaning**; Terms are about **how that meaning shows up** in language.
+
+    A Concept can have multiple Terms (synonyms, abbreviations, variations), but they all refer
+    to the **same meaning** in the context of that Concept.
+
+    ## Business Terms vs Technical Terms
+
+    Terms come in two broad categories:
+
+    - **Business Terms** — user-facing terminology used in conversations, documentation, UI, and
+      policies (e.g., “Customer”, “Counterparty”, “Risk Position”)
+    - **Technical Terms** — manifestations in code and data (e.g., variable names, column names,
+      API parameters, query bindings)
+
+    Treat both as Terms, because both are used by people, and both need to be linked back to the
+    Concept so everyone stays aligned.
+
+=== "Data & Tech Audience"
+
+    ## Terms as Concept Manifestations
+
+    A Term is a **manifestation** of a Concept.
+    It can be:
+
+    - a preferred business phrase
+    - an abbreviation
+    - a synonym
+    - a technical symbol in code (e.g., `_customer`, `cust_id`, `?cust`, `/customers`)
+
+    Terms allow the Knowledge Graph to connect human language and technical artifacts back to a
+    consistent semantic core (the Concept).
+
+    ## Discovering Technical Terms in code and data
+
+    Technical Terms can often be **discovered automatically** by scanning the organization’s
+    repositories and data artifacts:
+    Python/Java code, SQL, configuration, CSV column headers, API specs, and more.
+
+    Each detected manifestation becomes a **Technical Term** that links to:
+
+    - the **Concept** it manifests, and optionally
+    - the **Business Term** it corresponds to in that context.
+
+    Example:
+    If you detect the CSV header `P`, you can link that Technical Term to the Concept and also to
+    the Business Term “Patient”.
+
+    Technical Terms also include **semantic/validation artifacts** introduced later in the Use
+    Case lifecycle (especially during the Build phase), such as:
+
+    - OWL classes/properties/axioms in an ontology, and
+    - SHACL shapes and constraints.
+
+    In those cases, you link the Concept (and optionally a Business Term) to the ontology/shapes
+    term via a **special mapping relationship** (e.g. “representsClass”, “representsProperty”,
+    “constrainedByShape”), pointing at the ontology IRI.
+
+    Example:
+    If the Concept “patient” corresponds to the OWL class `hospital:Patient` in a Hospital
+    ontology, create a Technical Term representing that ontology term and link it with something
+    like **representsClass → `hospital:Patient`**.
+
+    ## Preferred Term
+
+    Concepts don’t need a traditional `rdfs:label` / `skos:prefLabel` label.
+    Instead, a Concept can point to a **preferred Term** (a Term object) that represents the
+    preferred expression in that context.
+
+=== "Ontology"
+
+    ## Ontology (minimal facts we can state today)
+
+    --8<-- "fragment/uctm-diagram-term.md"
+
+    We're not (yet) prescribing a full OWL ontology here.
+    But we can state a small set of **facts** that people can reliably use to build their own
+    ontology / schema / graph model around a Term.
+
+    ### Required facts about a Term
+
+    - **Opaque universally unique identifier**
+        - A Term should have an **opaque**, **universally unique** identifier.
+        - Prefer a random identifier such as **UUIDv4**, represented as a URI:
+          `urn:uuid:550e8400-e29b-41d4-a716-446655440000`
+
+    - **One or more forms (lexical variants)**
+        - A Term must have **one or more textual forms** (the actual strings).
+        - Business Terms often need multiple forms for different UI / communication contexts, for
+          example:
+            - **Singular**: “Patient”
+            - **Plural**: “Patients”
+            - **Abbreviation**: “Pat.”
+            - **Short label**: “P”
+        - These are variations of the **same Term** (think “sub-manifestations” of the Term).
+          They should not be mixed with the forms of a different Term.
+
+        Example:
+        If “Patient” and “Client” are both used to mean the same thing in a given Use Case
+        context, model them as **two separate Business Term objects**, each with their own
+        lexical forms.
+        Both Terms link to the same Concept, and the Concept defines the shared meaning.
+
+    - **Term kind**
+        - A Term should indicate whether it is a **Business Term** or a **Technical Term**.
+
+    - **Owned by a Concept**
+        - Terms are **owned** by a Concept (part-of): when the Concept is deleted, its Term
+          objects are deleted as well.
+        - A Concept must have **one or more Terms**.
+        - All Terms for a Concept **mean the same thing** in that Concept’s context.
+
+    ### Optional but useful facts
+
+    - **Language**: natural language tag for business terms (e.g., `en`, `nl`)
+    - **System / artifact**: where a technical term appears (e.g., codebase, dataset, API)
+    - **Term subtype**: for technical terms (e.g., `VariableName`, `ColumnName`, `ApiFieldName`,
+      `QueryBinding`)
+    - **Provenance**: who introduced the term, when, and why
+
+    ### Optional facts for Technical Terms (recommended)
+
+    When a Term is discovered in code/data, capture **where it came from**:
+
+    - **Repository URL** (e.g., GitHub repo)
+    - **File path**
+    - **Line range** (or equivalent location for non-text artifacts)
+    - **Commit / tag / revision**
+    - **Language / format** (e.g., Python, Java, SQL, CSV)
+    - **Locator URL** (deep link to the exact source line / blob for traceability)
+
+    When a Term represents an ontology or validation artifact, capture:
+
+    - **Ontology / shape identifier** (IRI), e.g. `hospital:Patient`
+    - **Mapping kind** (e.g., representsClass / representsProperty / constrainedByShape)
+