Skip to content

Commit 5e5908d

Browse files
committed
docs(concept): enhance concept page with comprehensive improvements
- Add summary block for consistency with other concept pages - Add tabbed content structure (Business & Management Audience, Data & Tech Audience) - Fix syntax error (removed erroneous comma) - Expand Business & Management Audience tab: - Add What Is a Concept? section - Add Why Concepts Matter section - Add tip admonition about starting with business language - Add Concept Vocabulary section - Add Evolution and Refinement section - Significantly enhance Data & Tech Audience tab: - Add What Is a Concept in the EKG Method? section - Add The Concept Lifecycle with subsections - Add Concept Types section (Class, Property, Shape) - Add Concepts as Linking Pins section explaining how concepts link business and technical terms across all manifestations (forms, code, SPARQL, databases, APIs, OWL axioms, SHACL shapes) - Expand Relationship to Ontologies section - Add Reuse and Inheritance section - Add Relationship to Other Concepts section - Add links to related concepts (Use Case, Use Case Tree, Persona, Story, Ontology) - Ensure all lines under 70 characters
1 parent e8ccc67 commit 5e5908d

File tree

1 file changed

+200
-24
lines changed

1 file changed

+200
-24
lines changed

docs/concept/concept.md

Lines changed: 200 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,203 @@
11
# Concept
22

3-
For every given Use Case we want to start with capturing the concepts and
4-
terms that the user or "the business" uses or wants to use.
5-
6-
Most of these concepts and their terms will be pre-defined in all kinds of
7-
vocabularies but for brand-new use cases in a new domain concepts and their
8-
terms will have to be created.
9-
10-
At the initial stages of a use case, the focus should be on capturing the
11-
language of the users in their domain, which may not necessarily involve
12-
discussing ontologies.
13-
The main goal is to gather requirements and understand the problem context,
14-
as well as the terms and concepts used by the users.
15-
Later in the use case's life cycle, once the problem is well understood,
16-
the relevant ontologies can be mapped to the terms and concepts captured earlier.
17-
This allows for better integration of the use case with the overall EKG ecosystem.
18-
19-
As the use case evolves and the understanding of the domain becomes clearer,
20-
it may be necessary to adjust the captured concepts and terms to better
21-
reflect the reality of the domain.
22-
, it may be necessary to map the captured concepts and terms to more appropriate
23-
terms in a specific ontology or vocabulary to ensure consistency and interoperability
24-
across the enterprise.
25-
In either case, the important thing is to ensure that the captured concepts and
26-
terms accurately reflect the reality of the domain and the needs of the stakeholders.
3+
<!--summary-start-->
4+
_A domain term or idea that links business language to semantic models,
5+
enabling the Enterprise Knowledge Graph to understand and reason about
6+
business concepts_
7+
<!--summary-end-->
8+
9+
=== "Business & Management Audience"
10+
11+
## What Is a Concept?
12+
13+
For every given [Use Case](use-case.md), we want to start with
14+
capturing the concepts and terms that the user or "the business"
15+
uses or wants to use.
16+
17+
A **Concept** is a way to represent a business idea or term in a
18+
way that both humans and machines can understand.
19+
It serves as a bridge between the language your organization uses
20+
and the formal semantic models (ontologies) that enable the
21+
Enterprise Knowledge Graph to reason about your business.
22+
23+
## Why Concepts Matter
24+
25+
Concepts ensure that:
26+
27+
- **Business language is preserved** — We capture terms as the
28+
business uses them, not as some external standard defines them
29+
- **Semantic meaning is enabled** — Concepts link to ontologies
30+
that give them machine-readable meaning
31+
- **Consistency is maintained** — The same concept can be reused
32+
across multiple use cases
33+
- **Interoperability is achieved** — Concepts can map to
34+
multiple ontologies, enabling integration across systems
35+
36+
!!! tip "Start with business language"
37+
38+
Don't worry about ontologies in the early stages.
39+
Focus on capturing what the business calls things and what
40+
those things mean in their context.
41+
42+
## Concept Vocabulary
43+
44+
Most concepts and their terms will be pre-defined in all kinds of
45+
vocabularies, but for brand-new use cases in a new domain,
46+
concepts and their terms will have to be created.
47+
48+
Each Use Case can have its own vocabulary of concepts, but it can
49+
also inherit or borrow concepts from higher-level or related use
50+
cases in the [Use Case Tree](use-case-tree.md).
51+
This enables reuse and consistency across the enterprise.
52+
53+
## Evolution and Refinement
54+
55+
As the use case evolves and the understanding of the domain
56+
becomes clearer, it may be necessary to:
57+
58+
- **Adjust concepts** — Better reflect the reality of the domain
59+
- **Map to ontologies** — Link concepts to more appropriate
60+
terms in specific ontologies or vocabularies to ensure
61+
consistency and interoperability across the enterprise
62+
63+
In either case, the important thing is to ensure that the
64+
captured concepts and terms accurately reflect the reality of the
65+
domain and the needs of the stakeholders.
66+
67+
=== "Data & Tech Audience"
68+
69+
## What Is a Concept in the EKG Method?
70+
71+
A **Concept** is the linking pin between local business language
72+
and formal semantic models (ontologies).
73+
It enables the EKG to understand business terminology while
74+
maintaining connections to standardized vocabularies and enabling
75+
automated reasoning.
76+
77+
## The Concept Lifecycle
78+
79+
### Initial Capture
80+
81+
At the initial stages of a use case, the focus should be on
82+
capturing the language of the users in their domain, which may not
83+
necessarily involve discussing ontologies.
84+
The main goal is to gather requirements and understand the
85+
problem context, as well as the terms and concepts used by the
86+
users.
87+
88+
!!! tip "Business-first approach"
89+
90+
Start with what the business calls things, not what some
91+
ontology says they should be called.
92+
The business owns its use cases and should recognize them
93+
throughout their lifecycle.
94+
95+
### Mapping to Ontologies
96+
97+
Later in the use case's lifecycle, once the problem is well
98+
understood, the relevant ontologies can be mapped to the terms and
99+
concepts captured earlier.
100+
This allows for better integration of the use case with the
101+
overall EKG ecosystem.
102+
103+
### Refinement and Evolution
104+
105+
As the use case evolves and the understanding of the domain
106+
becomes clearer, it may be necessary to:
107+
108+
- **Adjust captured concepts** — Better reflect the reality of
109+
the domain
110+
- **Map to appropriate ontologies** — Link to more appropriate
111+
terms in specific ontologies or vocabularies to ensure
112+
consistency and interoperability across the enterprise
113+
114+
## Concept Types
115+
116+
Concepts can represent different types of semantic elements:
117+
118+
- **Class Concepts** — Represent types or categories (e.g.,
119+
"Person", "Account", "Transaction")
120+
- **Property Concepts** — Represent relationships or attributes
121+
(e.g., "hasOwner", "isLocatedIn", "hasValue")
122+
- **Shape Concepts** — Represent validation constraints or data
123+
shapes
124+
125+
## Concepts as Linking Pins
126+
127+
Concepts are the linking pin in many ways.
128+
They link "business terms" and "technical terms" as they are
129+
used in the context of the given use case, by the business and
130+
by various programs, apps, and systems, in all their variations
131+
and manifestations.
132+
133+
**Example:**
134+
The official term for Customer could be "Customer," but it
135+
appears in different forms:
136+
- On forms in apps as "Cust."
137+
- In Python code as `_customer`
138+
- In SPARQL statements as `?cust`
139+
- In database schemas as `cust_id` or `customer_id`
140+
- In API endpoints as `/customers` or `/api/cust`
141+
- In OWL ontologies as specific axioms (e.g., `owl:Class` or
142+
`rdfs:subClassOf` relationships)
143+
- In SHACL shapes as validation constraints (e.g., `sh:property`
144+
or `sh:minCount`)
145+
146+
All these symbols, terms, axioms, and shapes are manifestations
147+
of the same concept and linked to it.
148+
Even the mapping to certain axioms in an OWL ontology or
149+
certain shapes in a SHACL shape would be seen as "technical
150+
terms" — just yet some other manifestations of a given concept.
151+
152+
This enables the EKG to understand that these different
153+
representations all refer to the same business concept, enabling
154+
semantic integration across diverse systems and technologies.
155+
156+
## Relationship to Ontologies
157+
158+
Concepts serve as a bridge between:
159+
160+
- **Local business terminology** — The language used within a
161+
specific use case or domain
162+
- **Technical manifestations** — How concepts appear in code,
163+
databases, APIs, forms, and other systems
164+
- **Standard ontologies** — Formal semantic models that enable
165+
interoperability and reasoning
166+
167+
This multi-faceted nature allows the EKG to:
168+
- Address "the business" with their language
169+
- Integrate with technical systems using their terminology
170+
- Keep backend EKG models generic and linked to appropriate
171+
ontologies
172+
- Model semantic conundrums (e.g., different terms for the same
173+
concept, same term for different concepts)
174+
175+
## Reuse and Inheritance
176+
177+
Concepts follow the same reuse patterns as other elements in the
178+
EKG Method:
179+
180+
- **Local definition** — Each use case can define concepts
181+
specific to its domain
182+
- **Inheritance** — Lower-level use cases inherit concepts from
183+
parent use cases in the Use Case Tree
184+
- **Borrowing** — Use cases can reference concepts from related
185+
use cases
186+
- **Consistency** — Common concepts are defined once and reused
187+
188+
This ensures that concepts are not duplicated unnecessarily and
189+
that the EKG maintains semantic consistency across the enterprise.
190+
191+
## Relationship to Other Concepts
192+
193+
Concepts are fundamental building blocks that relate to:
194+
195+
- **[Use Cases](use-case.md)** — Each use case has a vocabulary
196+
of concepts
197+
- **[Personas](persona.md)** — Personas are Concepts, enabling
198+
semantic definition and reasoning
199+
- **[Stories](story.md)** — Stories reference domain concepts
200+
that need to be understood and modeled
201+
- **[Ontologies](ontology.md)** — Concepts link to ontology
202+
classes, properties, and shapes
27203

0 commit comments

Comments
 (0)