Files

T

Bastien Gourdon 1c8ab77003 tbox: v1.6 - provenance portee par les classes concretes, isAbstract declare et non plus infere, ForeignKeyConstraint devient ForeignKey, les dix classes sans rdfs:comment completees

2026-08-05 09:13:12 +02:00

21 KiB

Raw Permalink Blame History

Pernod Ricard Data MetaModel — T-Box Processbook

Version 0.1 — Draft for review — generated 2026-08-03

Generated from processes.yaml. The BPMN files in bpmn/ are the authoritative form; the views below are derived from the same source. Do not edit this document (EV-007, EV-008).

Procedures for changing the vocabulary of the model. Each procedure names the rules it enforces, the steps a person must perform, and the points at which the work stops rather than continues.

Procedures

Id	Family	Procedure	Scope
X1	Release	Propagate a change and publish a version	Any validated modification of the vocabulary.
C1	Create	Create a term	class
C2	Create	Create a controlled value	typed individual
C3	Create	Create a shape	Any SHACL constraint added to the validation set.
D1	Delete	Deprecate a term	class
D2	Delete	Withdraw a term permanently	class
R1	Verify	Verify the vocabulary against the rulebook	The whole vocabulary, or the subset touched by a change.
R2	Verify	Validate instances against the shapes	Any instance graph in the validation perimeter.
R3	Verify	Audit what the shapes cannot see	The whole vocabulary and its source file.

Reading a diagram

A rounded node is a start or end state.
A diamond is a decision; every outgoing path is labelled.
A shaded box is a human task: it cannot be automated, and the work stops there until someone acts.
A double-bordered box calls another procedure by its identifier.

X1 — Propagate a change and publish a version


Family	Release
Scope	Any validated modification of the vocabulary.
Trigger	A change to the vocabulary has been agreed and is ready to apply.
Inputs	the agreed change, the target version, the list of affected artifacts
Outputs	a merged branch, a tagged version, an execution log
Rules enforced	EV-004, EV-005, EV-006, EV-007, EV-008, EV-009, EV-010, EV-014, EV-015, TN-023
Calls	R1, R2

Note. The most frequently invoked procedure of the processbook: every other procedure ends by calling it. Two of its steps are gateways rather than checks, because an idempotence failure and a validation failure must stop the work rather than be noted in passing.

flowchart TD
    start(["Change agreed"])
    branch["Create the migration branch"]
    apply["Apply the change through an RDF parser"]
    labels["Regenerate labels by derivation"]
    abox["Propagate to the instances"]
    shapes["Update the shapes and align conformsTo"]
    artifacts["Regenerate every derived artifact"]
    replay["Replay the chain a second time"]
    idem{"Second run reports zero change?"}
    verify_voc[["R1: Verify the vocabulary"]]
    verify_abox[["R2: Validate the instances"]]
    log["Write the execution log for this attempt"]
    clean{"Any violation?"}
    decide["Correct or abandon"]
    drop["Destroy the branch and restart from the published version"]
    review["Review the merge"]
    merge["Merge as a block"]
    bump["Increment the ontology version"]
    end(["Version published"])
    aborted(["Change abandoned"])
    start --> branch
    branch --> apply
    apply --> labels
    labels --> abox
    abox --> shapes
    shapes --> artifacts
    artifacts --> replay
    replay --> idem
    idem -->|zero change| verify_voc
    idem -->|the chain is not replayable| decide
    verify_voc --> verify_abox
    verify_abox --> log
    log --> clean
    clean -->|none| review
    clean -->|at least one| decide
    decide -->|correct| apply
    decide -->|abandon| drop
    drop --> aborted
    review --> merge
    merge --> bump
    bump --> end
    class idem decision;
    class clean decision;
    class decide human;
    class review human;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Create the migration branch	script	EV-009
Apply the change through an RDF parser	script	EV-005, EV-006
Regenerate labels by derivation	script	TN-023
Propagate to the instances	script	EV-009
Update the shapes and align conformsTo	script	EV-010
Regenerate every derived artifact	script	EV-008
Replay the chain a second time	script	EV-006, EV-007
Second run reports zero change?	decision	-
Verify the vocabulary (R1)	calls	-
Validate the instances (R2)	calls	-
Write the execution log for this attempt	script	EV-015
Any violation?	decision	-
Correct or abandon	human	EV-004, EV-007
Destroy the branch and restart from the published version	script	EV-007
Review the merge	human	EV-004, EV-009
Merge as a block	script	EV-009
Increment the ontology version	script	EV-014

C1 — Create a term


Family	Create
Scope	class
Trigger	A missing concept, edge or field has been identified.
Inputs	the intended meaning, the nature, the target layer, the provenance, the parent or the domain and range
Outputs	a declared term, a published version
Rules enforced	EV-004, TN-001, TN-002, TN-003, TN-004, TN-005, TN-006, TN-007, TN-009, TN-010, TN-011, TN-012, TN-013, TN-014, TN-015, TN-018, TN-019, TN-020, TN-021, TN-022, TN-023, TN-024, TN-025, TN-026, TN-027, TN-028
Calls	R1, X1

Parameter. The nature of the term selects the naming rules applied at the naming step: a class takes TN-001, TN-002, TN-004, TN-005, TN-006, TN-007 and TN-027; a relation takes TN-001, TN-002, TN-009, TN-010, TN-011 and TN-028; an attribute takes TN-001, TN-002, TN-004, TN-012, TN-013, TN-014 and TN-015; an annotation takes TN-001, TN-002 and TN-003.

Note. The first step has no tool today. Checking that no existing term already covers the need is the semantic uniqueness control that SHACL cannot perform, and it stays a human task until R3 exists.

flowchart TD
    start(["Need identified"])
    unique["Check that no existing term covers the need"]
    exists{"A term already covers it?"}
    reuse(["Reuse the existing term"])
    name["Name the term according to its nature"]
    label["Derive the label"]
    short["Decide the short label and the acronym"]
    comment["Write the comment"]
    declare["Declare typing"]
    validate["Validate before applying"]
    check[["R1: Verify against the rulebook"]]
    release[["X1: Propagate and publish"]]
    end(["Term available"])
    start --> unique
    unique --> exists
    exists -->|yes| reuse
    exists -->|no| name
    name --> label
    label --> short
    short --> comment
    comment --> declare
    declare --> validate
    validate --> check
    check --> release
    release --> end
    class unique human;
    class exists decision;
    class short human;
    class comment human;
    class validate human;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Check that no existing term covers the need	human	-
A term already covers it?	decision	-
Name the term according to its nature	script	TN-001, TN-002, TN-003, TN-004, TN-005, TN-006, TN-009, TN-010, TN-011, TN-012, TN-013, TN-014, TN-015, TN-028
Derive the label	script	TN-018, TN-019, TN-020, TN-021, TN-023
Decide the short label and the acronym	human	TN-022
Write the comment	human	TN-024
Declare typing	script	TN-007, TN-025, TN-026, TN-027
Validate before applying	human	EV-004
Verify against the rulebook (R1)	calls	-
Propagate and publish (X1)	calls	-

C2 — Create a controlled value


Family	Create
Scope	typed individual
Trigger	A new value is needed in a controlled set.
Inputs	the value, the set it belongs to, whether a domain may add others
Outputs	a declared value, a published version
Rules enforced	EV-004, TN-001, TN-016, TN-017, TN-018, TN-022
Calls	C3, R1, X1

Parameter. The form is not a style choice but the outcome of the first decision. The two branches have different consequences: the literal branch edits the shapes and therefore the vocabulary, so it falls under the version freeze; the individual branch touches nothing else.

flowchart TD
    start(["New value needed"])
    decide["Must it be defined, owned or extended by a domain?"]
    form{"Which form?"}
    indiv["Create the typed individual and derive its label"]
    literal["Write the literal in upper snake case"]
    shape[["C3: Extend the closed list in the shapes"]]
    validate["Validate before applying"]
    check[["R1: Verify against the rulebook"]]
    release[["X1: Propagate and publish"]]
    end(["Value available"])
    start --> decide
    decide --> form
    form -->|extensible by a domain| indiv
    form -->|closed governance state| literal
    indiv --> validate
    literal --> shape
    shape --> validate
    validate --> check
    check --> release
    release --> end
    class decide human;
    class form decision;
    class validate human;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Must it be defined, owned or extended by a domain?	human	TN-016
Which form?	decision	-
Create the typed individual and derive its label	script	TN-001, TN-018, TN-022
Write the literal in upper snake case	script	TN-017
Extend the closed list in the shapes (C3)	calls	-
Validate before applying	human	EV-004
Verify against the rulebook (R1)	calls	-
Propagate and publish (X1)	calls	-

C3 — Create a shape


Family	Create
Scope	Any SHACL constraint added to the validation set.
Trigger	A rule needs an executor, or a new class enters the validation perimeter.
Inputs	the rule to enforce, the target class or property
Outputs	a shape, a rulebook entry naming it as executor
Rules enforced	EV-010, EV-011, EV-012, EV-013
Calls	R2, X1

Note. The step that is forgotten is the last one before release: recording the shape as the executor of its rule. Without it a rule stays declared blocking with nothing enforcing it, which EV-011 forbids.

flowchart TD
    start(["Constraint needed"])
    write["Write the constraint"]
    pattern["Check that every pattern is expressed positively"]
    portable{"Expressible within the specification?"}
    demote["Move the rule to the script tier"]
    conforms["Align the declared ontology version"]
    test[["R2: Test against real instances"]]
    record["Record the shape as the executor of its rule"]
    release[["X1: Propagate and publish"]]
    end(["Shape in force"])
    start --> write
    write --> pattern
    pattern --> portable
    portable -->|yes| conforms
    portable -->|no| demote
    demote --> record
    conforms --> test
    test --> record
    record --> release
    release --> end
    class write human;
    class portable decision;
    class demote human;
    class record human;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Write the constraint	human	-
Check that every pattern is expressed positively	script	EV-013
Expressible within the specification?	decision	-
Move the rule to the script tier	human	EV-012
Align the declared ontology version	script	EV-010
Test against real instances (R2)	calls	-
Record the shape as the executor of its rule	human	EV-011, EV-012
Propagate and publish (X1)	calls	-

D1 — Deprecate a term


Family	Delete
Scope	class
Trigger	A term is superseded or no longer needed.
Inputs	the term, its replacement if any
Outputs	a deprecated stub, a published version
Rules enforced	EV-001, EV-015, TN-020
Calls	X1

Note. The count at step two is informative, not a condition: a term may be deprecated whether or not it is instantiated. It becomes a condition only in D2.

flowchart TD
    start(["Term superseded"])
    replacement["Identify the replacement"]
    count["Count the instances for information"]
    mark["Mark deprecated and declare the replacement"]
    strip["Strip the stub of every edge"]
    label["Remove any mention of state from the label"]
    release[["X1: Propagate and publish"]]
    end(["Term deprecated"])
    start --> replacement
    replacement --> count
    count --> mark
    mark --> strip
    strip --> label
    label --> release
    release --> end
    class replacement human;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Identify the replacement	human	-
Count the instances for information	script	EV-015
Mark deprecated and declare the replacement	script	EV-001
Strip the stub of every edge	script	EV-001
Remove any mention of state from the label	script	TN-020
Propagate and publish (X1)	calls	-

D2 — Withdraw a term permanently


Family	Delete
Scope	class
Trigger	A deprecated term is to be removed from the vocabulary.
Inputs	the deprecated term
Outputs	a vocabulary without the term, a proof of non-instantiation, a published version
Rules enforced	EV-002, EV-003, EV-015
Calls	R1, R2, X1

Note. The reference cleaning step is what prevents phantom nodes: a subject removed while its identifier is still cited elsewhere is reconstructed by inference, present in traversals and absent from every control. It is a step of the procedure, not a check at the end of a script.

flowchart TD
    start(["Withdrawal requested"])
    count["Run the counting query"]
    instantiated{"Any instance found?"}
    keep(["Kept deprecated"])
    proof["Attach the proof to the commit"]
    remove["Remove the subject block"]
    refs["Remove every reference naming the subject"]
    check_voc[["R1: Verify the vocabulary"]]
    check_abox[["R2: Validate the instances"]]
    release[["X1: Propagate and publish"]]
    end(["Term withdrawn"])
    start --> count
    count --> instantiated
    instantiated -->|yes| keep
    instantiated -->|no| proof
    proof --> remove
    remove --> refs
    refs --> check_voc
    check_voc --> check_abox
    check_abox --> release
    release --> end
    class instantiated decision;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Run the counting query	script	EV-002, EV-015
Any instance found?	decision	-
Attach the proof to the commit	script	EV-002, EV-015
Remove the subject block	script	-
Remove every reference naming the subject	script	EV-003
Verify the vocabulary (R1)	calls	-
Validate the instances (R2)	calls	-
Propagate and publish (X1)	calls	-

R1 — Verify the vocabulary against the rulebook


Family	Verify
Scope	The whole vocabulary, or the subset touched by a change.
Trigger	A term has been created, changed or withdrawn, or a release is prepared.
Inputs	the vocabulary, the rulebook source
Outputs	a conformance report
Rules enforced	EV-014, TN-001, TN-002, TN-003, TN-004, TN-005, TN-006, TN-007, TN-008, TN-009, TN-010, TN-011, TN-012, TN-013, TN-014, TN-015, TN-016, TN-017, TN-018, TN-019, TN-020, TN-021, TN-022, TN-023, TN-024, TN-025, TN-026, TN-027, TN-028
Calls	-

Note. Two tiers run in sequence, not in parallel: the script settles everything mechanisable, and a person answers only for the rules no script can judge. Reversing the order wastes review time on findings the script would have caught.

flowchart TD
    start(["Verification requested"])
    script["Run the naming and declaration checks"]
    mechanised{"Any mechanised violation?"}
    report_fail(["Report returned with violations"])
    human["Review the rules no script can judge"]
    judged{"Reviewer raises an issue?"}
    report_ok(["Vocabulary conforms"])
    start --> script
    script --> mechanised
    mechanised -->|at least one| report_fail
    mechanised -->|none| human
    human --> judged
    judged -->|yes| report_fail
    judged -->|no| report_ok
    class mechanised decision;
    class human human;
    class judged decision;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Run the naming and declaration checks	script	TN-001, TN-002, TN-003, TN-004, TN-005, TN-006, TN-007, TN-009, TN-010, TN-011, TN-012, TN-013, TN-014, TN-015, TN-017, TN-018, TN-019, TN-020, TN-021, TN-023, TN-025, TN-026, TN-027, TN-028, EV-014
Any mechanised violation?	decision	-
Review the rules no script can judge	human	TN-008, TN-016, TN-022, TN-024
Reviewer raises an issue?	decision	-

R2 — Validate instances against the shapes


Family	Verify
Scope	Any instance graph in the validation perimeter.
Trigger	Instances have changed, shapes have changed, or a release is prepared.
Inputs	the instance graph, the shapes, the ontology
Outputs	a validation report
Rules enforced	EV-010
Calls	-

Note. The version check comes first and aborts rather than warns. Validating against shapes that target another version of the ontology does not fail loudly: it returns a long list of violations that reads exactly like a regression of the model.

flowchart TD
    start(["Validation requested"])
    conforms["Compare the declared target version with the ontology version"]
    match{"Versions match?"}
    abort(["Aborted on version mismatch"])
    run["Run the shape validation"]
    violations{"Any violation?"}
    fail(["Report returned with violations"])
    ok(["Instances conform"])
    start --> conforms
    conforms --> match
    match -->|no| abort
    match -->|yes| run
    run --> violations
    violations -->|at least one| fail
    violations -->|none| ok
    class match decision;
    class violations decision;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Compare the declared target version with the ontology version	script	EV-010
Versions match?	decision	-
Run the shape validation	script	-
Any violation?	decision	-

R3 — Audit what the shapes cannot see


Family	Verify
Scope	The whole vocabulary and its source file.
Trigger	Periodic audit, or before a version is published.
Inputs	the vocabulary, its source file
Outputs	a shortlist of suspected duplicates, a list of duplicated blocks
Rules enforced	EV-012
Calls	-

Note. Shape validation reads a graph, not a file and not meaning. Two identifiers standing for the same notion produce two individually valid graphs; a duplicated block of text produces identical triples and no complaint. This procedure is the tier those rules fall to, and its output is a shortlist for a person rather than a verdict.

flowchart TD
    start(["Audit requested"])
    index["Build the normalised label index"]
    hash["Hash every normalised subject block"]
    shortlist{"Any candidate found?"}
    clean(["Nothing to arbitrate"])
    review["Arbitrate each candidate"]
    act{"Duplication confirmed?"}
    merge(["Referred to the merge procedure"])
    dismissed(["Candidates dismissed"])
    start --> index
    index --> hash
    hash --> shortlist
    shortlist -->|none| clean
    shortlist -->|at least one| review
    review --> act
    act -->|yes| merge
    act -->|no| dismissed
    class shortlist decision;
    class review human;
    class act decision;
    classDef human fill:#FFF4CE,stroke:#B08900;
    classDef decision fill:#E8F0F7,stroke:#3E6E96;

Step	Type	Rules
Build the normalised label index	script	EV-012
Hash every normalised subject block	script	EV-012
Any candidate found?	decision	-
Arbitrate each candidate	human	-
Duplication confirmed?	decision	-

Rule coverage

Which procedures enforce each rule. Derived, not maintained: a rule cited in a diagram appears here automatically.

Rule	Procedures
EV-001	D1
EV-002	D2
EV-003	D2
EV-004	C1, C2, X1
EV-005	X1
EV-006	X1
EV-007	X1
EV-008	X1
EV-009	X1
EV-010	C3, R2, X1
EV-011	C3
EV-012	C3, R3
EV-013	C3
EV-014	R1, X1
EV-015	D1, D2, X1
TN-001	C1, C2, R1
TN-002	C1, R1
TN-003	C1, R1
TN-004	C1, R1
TN-005	C1, R1
TN-006	C1, R1
TN-007	C1, R1
TN-008	R1
TN-009	C1, R1
TN-010	C1, R1
TN-011	C1, R1
TN-012	C1, R1
TN-013	C1, R1
TN-014	C1, R1
TN-015	C1, R1
TN-016	C2, R1
TN-017	C2, R1
TN-018	C1, C2, R1
TN-019	C1, R1
TN-020	C1, D1, R1
TN-021	C1, R1
TN-022	C1, C2, R1
TN-023	C1, R1, X1
TN-024	C1, R1
TN-025	C1, R1
TN-026	C1, R1
TN-027	C1, R1
TN-028	C1, R1

21 KiB Raw Permalink Blame History