diff --git a/generated/PR_TBox_Rulebook.md b/generated/PR_TBox_Rulebook.md index c6d97e4..e79eadd 100644 --- a/generated/PR_TBox_Rulebook.md +++ b/generated/PR_TBox_Rulebook.md @@ -1,6 +1,6 @@ # Pernod Ricard Data MetaModel — T-Box Rulebook -**Version 1.1** — Draft for review — generated 2026-08-03 +**Version 1.2** — Draft for review — generated 2026-08-03 > Generated from `rules.yaml`. Do not edit this document: edit the source and regenerate (EV-007, EV-008). @@ -444,7 +444,7 @@ The label is derived, not authored. Anything a reader needs that the derivation ## TN-022 — The short label carries the spoken form -**Statement.** A term carries pr:shortLabel whenever the form derived under TN-018 is not what the organisation writes or says. The short label is free: acronyms, abbreviations, hyphens, short forms. +**Statement.** A term carries pr:shortLabel ONLY where the form derived under TN-018 is not what the organisation writes or says. Where the two coincide, no short label is declared: a duplicate of the label carries no information and is one more thing to keep in step. The short label follows the casing of the label it replaces — title case for a class — and admits what the label cannot: acronyms, abbreviations, dropped words. | | | |---|---| @@ -454,12 +454,13 @@ The label is derived, not authored. Anything a reader needs that the derivation | Executor | `review checklist` | | Procedure | _pending_ | -**Why.** The short label is what makes the derivation rule bearable. Without it, a mechanical label impoverishes every screen; with it, display becomes explicit and centrally governed instead of being improvised by each consumer. It is MAJOR rather than BLOCKING because judging whether a derived form matches what people actually say is human work, and EV-011 forbids declaring a rule blocking with no executor. +**Why.** The short label is what makes the derivation rule bearable. Without it, a mechanical label impoverishes every screen; with it, display becomes explicit and centrally governed instead of being improvised by each consumer. Restricting it to the cases where it actually differs is what keeps it meaningful: a short label present on every term degenerates into a second copy of the label, drifting from it one entry at a time. It is MAJOR rather than BLOCKING because judging whether a derived form matches what people actually say is human work, and EV-011 forbids declaring a rule blocking with no executor. | From | To | Note | |---|---|---| | "Data Sub Domain Owner" | short label Sub Domain Owner | the word Data is dropped in the spoken form | | "Key Performance Indicator" | short label KPI, acronym KPI | the acronym channel is what makes TN-002 bearable | +| a short label reading Metric on a class labelled Metric | no short label | a duplicate of the label carries nothing | ## TN-023 — The label is generated, never typed @@ -923,19 +924,47 @@ Applies TN-011 and TN-022. The short label is what screens display and what rela | IRI | rdfs:label | shortLabel | acronym | Note | |---|---|---|---|---| -| `DataDomain` | Data Domain | Domain | DD | DD is already the short form used inside A-Box identifiers under NR-014 | -| `DataSubDomain` | Data Sub Domain | Sub Domain | SD | no hyphen | -| `DataDomainOwner` | Data Domain Owner | Domain Owner | DDO | | -| `DataSubDomainOwner` | Data Sub Domain Owner | Sub Domain Owner | SDO | | -| `DataProductOwner` | Data Product Owner | Product Owner | PO | NOT DPO — the initialism is taken by Data Protection Officer | -| `DataSteward` | Data Steward | Steward | - | | -| `DataGovernanceLead` | Data Governance Lead | Governance Lead | DGL | | -| `DataElement` | Data Element | Element | - | drives the name of hasElement and hasGrainElement | -| `BusinessConcept` | Business Concept | Concept | - | drives the name of usesConcept | +| `MetaModelObject` | Meta Model Object | - | - | | +| `DefinedObject` | Defined Object | - | - | | +| `CapturedObject` | Captured Object | - | - | | +| `OwnershipLayerObject` | Ownership Layer Object | Ownership Layer | - | the categorisation role moves into rdfs:comment | +| `BusinessLayerObject` | Business Layer Object | Business Layer | - | | +| `LogicalLayerObject` | Logical Layer Object | Logical Layer | - | | +| `PhysicalLayerObject` | Physical Layer Object | Physical Layer | - | | +| `DeliveryLayerObject` | Delivery Layer Object | Delivery Layer | - | | +| `ConsumptionLayerObject` | Consumption Layer Object | Consumption Layer | - | | +| `GovernanceLayerObject` | Governance Layer Object | Governance Layer | - | | +| `DataStructure` | Data Structure | - | - | the former short label was a gloss and belongs in rdfs:comment | +| `KeyConstraint` | Key Constraint | - | - | | +| `Actor` | Actor | - | - | | +| `DataDomain` | Data Domain | Domain | DD | DD is already the short form used inside instance identifiers | +| `DataSubDomain` | Data Sub Domain | Sub Domain | SD | no hyphen, for consistency | | `BusinessObject` | Business Object | - | BO | | +| `BusinessConcept` | Business Concept | Concept | - | drives the name of usesConcept | +| `Metric` | Metric | - | - | | | `KeyPerformanceIndicator` | Key Performance Indicator | KPI | KPI | the acronym channel is what makes TN-002 bearable | +| `DataObject` | Data Object | - | - | | +| `DataElement` | Data Element | Element | - | drives the name of hasElement and hasGrainElement | +| `Database` | Database | - | - | | +| `Schema` | Schema | - | - | | +| `Field` | Field | - | - | | +| `System` | System | - | - | | +| `SystemType` | System Type | - | - | | +| `Transformation` | Transformation | - | - | | +| `BaseTable` | Base Table | - | - | | +| `ExternalTable` | External Table | - | - | | +| `View` | View | - | - | | +| `PrimaryKey` | Primary Key | - | - | | +| `ForeignKey` | Foreign Key | - | - | | +| `DataProduct` | Data Product | - | - | | +| `DataContract` | Data Contract | - | - | | +| `DataInterface` | Data Interface | - | - | | | `BusinessIntelligenceWorkspace` | Business Intelligence Workspace | BI Workspace | - | | | `BusinessIntelligenceDataSource` | Business Intelligence Data Source | BI Data Source | - | | -| `BusinessIntelligenceField` | Business Intelligence Field | BI Field | - | | +| `BusinessIntelligenceField` | Business Intelligence Field | BI Field | - | reproduced whole in containsBIField under TN-011 | | `BusinessIntelligenceReport` | Business Intelligence Report | BI Report | - | | -| `OwnershipLayerObject` | Ownership Layer Object | - | - | the categorisation role moves into rdfs:comment | +| `DataDomainOwner` | Data Domain Owner | Domain Owner | DDO | | +| `DataSubDomainOwner` | Data Sub Domain Owner | Sub Domain Owner | SDO | | +| `DataProductOwner` | Data Product Owner | Product Owner | PO | not DPO - the initialism is taken by Data Protection Officer, a real GDPR role | +| `DataSteward` | Data Steward | Steward | - | | +| `DataGovernanceLead` | Data Governance Lead | Governance Lead | DGL | | diff --git a/generated/PR_TBox_Rulebook.xlsx b/generated/PR_TBox_Rulebook.xlsx index fd3ebe7..2b41abb 100644 Binary files a/generated/PR_TBox_Rulebook.xlsx and b/generated/PR_TBox_Rulebook.xlsx differ diff --git a/governance/migration/migrate_tbox_v2_0.py b/governance/migration/migrate_tbox_v2_0.py index 9501a1d..1deafff 100644 --- a/governance/migration/migrate_tbox_v2_0.py +++ b/governance/migration/migrate_tbox_v2_0.py @@ -238,16 +238,22 @@ def migrate(onto, others, spec, rules, report): report.add("isAbstract_declared", 1) # 10 — display annotations, from the rulebook annex (TN-022) + # The annex is authoritative AND exhaustive: a null value means any existing + # annotation is removed. A short label identical to the label carries no + # information and is one more thing to keep in step. for d in rules["display"]: term = pr[d["iri"]] for prop, value in ((pr.shortLabel, d.get("short_label")), (pr.acronym, d.get("acronym"))): - if not value: - continue - if (term, prop, Literal(value)) not in onto: + current = list(onto.objects(term, prop)) + if value: + if (term, prop, Literal(value)) not in onto: + onto.remove((term, prop, None)) + onto.add((term, prop, Literal(value))) + report.add("display_set", 1) + elif current: onto.remove((term, prop, None)) - onto.add((term, prop, Literal(value))) - report.add("display_set", 1) + report.add("display_removed", len(current)) # 11 — regenerate every label by derivation (TN-018, TN-023) kinds = (OWL.Class, OWL.ObjectProperty, OWL.DatatypeProperty, OWL.AnnotationProperty) diff --git a/governance/rules.yaml b/governance/rules.yaml index 3fcfd71..3fc670c 100644 --- a/governance/rules.yaml +++ b/governance/rules.yaml @@ -17,7 +17,7 @@ meta: title: Pernod Ricard Data MetaModel — T-Box Rulebook - version: "1.1" + version: "1.2" status: Draft for review date: "2026-08-03" scope: > @@ -520,9 +520,12 @@ rules: category: Label title: The short label carries the spoken form statement: > - A term carries pr:shortLabel whenever the form derived under TN-018 is not - what the organisation writes or says. The short label is free: acronyms, - abbreviations, hyphens, short forms. + A term carries pr:shortLabel ONLY where the form derived under TN-018 is not + what the organisation writes or says. Where the two coincide, no short label + is declared: a duplicate of the label carries no information and is one more + thing to keep in step. The short label follows the casing of the label it + replaces — title case for a class — and admits what the label cannot: + acronyms, abbreviations, dropped words. scope: [class, individual] severity: MAJOR control: {tier: human, executor: review checklist, procedure: null} @@ -531,12 +534,16 @@ rules: The short label is what makes the derivation rule bearable. Without it, a mechanical label impoverishes every screen; with it, display becomes explicit and centrally governed instead of being improvised by each - consumer. It is MAJOR rather than BLOCKING because judging whether a derived - form matches what people actually say is human work, and EV-011 forbids - declaring a rule blocking with no executor. + consumer. Restricting it to the cases where it actually differs is what + keeps it meaningful: a short label present on every term degenerates into a + second copy of the label, drifting from it one entry at a time. It is MAJOR + rather than BLOCKING because judging whether a derived form matches what + people actually say is human work, and EV-011 forbids declaring a rule + blocking with no executor. examples: - {from: "\"Data Sub Domain Owner\"", to: "short label Sub Domain Owner", note: the word Data is dropped in the spoken form} - {from: "\"Key Performance Indicator\"", to: "short label KPI, acronym KPI", note: the acronym channel is what makes TN-002 bearable} + - {from: "a short label reading Metric on a class labelled Metric", to: no short label, note: a duplicate of the label carries nothing} - id: TN-023 category: Label @@ -1026,20 +1033,51 @@ abstractness: - {term: SystemType, is_abstract: false, note: "must stay concrete — it types five individuals"} # ====== ANNEX: DISPLAY (TN-011, TN-022) ====== +# Authoritative and exhaustive: a class absent from this list carries no +# short label and no acronym. A null short_label means any existing one is +# removed, since a duplicate of the label carries no information (TN-022). display: -- {iri: DataDomain, label: "Data Domain", short_label: "Domain", acronym: "DD", note: "DD is already the short form used inside A-Box identifiers under NR-014"} -- {iri: DataSubDomain, label: "Data Sub Domain", short_label: "Sub Domain", acronym: "SD", note: "no hyphen"} -- {iri: DataDomainOwner, label: "Data Domain Owner", short_label: "Domain Owner", acronym: "DDO", note: null} -- {iri: DataSubDomainOwner, label: "Data Sub Domain Owner", short_label: "Sub Domain Owner", acronym: "SDO", note: null} -- {iri: DataProductOwner, label: "Data Product Owner", short_label: "Product Owner", acronym: "PO", note: "NOT DPO — the initialism is taken by Data Protection Officer"} -- {iri: DataSteward, label: "Data Steward", short_label: "Steward", acronym: null, note: null} -- {iri: DataGovernanceLead, label: "Data Governance Lead", short_label: "Governance Lead", acronym: "DGL", note: null} -- {iri: DataElement, label: "Data Element", short_label: "Element", acronym: null, note: "drives the name of hasElement and hasGrainElement"} -- {iri: BusinessConcept, label: "Business Concept", short_label: "Concept", acronym: null, note: "drives the name of usesConcept"} +- {iri: MetaModelObject, label: "Meta Model Object", short_label: null, acronym: null, note: null} +- {iri: DefinedObject, label: "Defined Object", short_label: null, acronym: null, note: null} +- {iri: CapturedObject, label: "Captured Object", short_label: null, acronym: null, note: null} +- {iri: OwnershipLayerObject, label: "Ownership Layer Object", short_label: "Ownership Layer", acronym: null, note: "the categorisation role moves into rdfs:comment"} +- {iri: BusinessLayerObject, label: "Business Layer Object", short_label: "Business Layer", acronym: null, note: null} +- {iri: LogicalLayerObject, label: "Logical Layer Object", short_label: "Logical Layer", acronym: null, note: null} +- {iri: PhysicalLayerObject, label: "Physical Layer Object", short_label: "Physical Layer", acronym: null, note: null} +- {iri: DeliveryLayerObject, label: "Delivery Layer Object", short_label: "Delivery Layer", acronym: null, note: null} +- {iri: ConsumptionLayerObject, label: "Consumption Layer Object", short_label: "Consumption Layer", acronym: null, note: null} +- {iri: GovernanceLayerObject, label: "Governance Layer Object", short_label: "Governance Layer", acronym: null, note: null} +- {iri: DataStructure, label: "Data Structure", short_label: null, acronym: null, note: "the former short label was a gloss and belongs in rdfs:comment"} +- {iri: KeyConstraint, label: "Key Constraint", short_label: null, acronym: null, note: null} +- {iri: Actor, label: "Actor", short_label: null, acronym: null, note: null} +- {iri: DataDomain, label: "Data Domain", short_label: "Domain", acronym: "DD", note: "DD is already the short form used inside instance identifiers"} +- {iri: DataSubDomain, label: "Data Sub Domain", short_label: "Sub Domain", acronym: "SD", note: "no hyphen, for consistency"} - {iri: BusinessObject, label: "Business Object", short_label: null, acronym: "BO", note: null} +- {iri: BusinessConcept, label: "Business Concept", short_label: "Concept", acronym: null, note: "drives the name of usesConcept"} +- {iri: Metric, label: "Metric", short_label: null, acronym: null, note: null} - {iri: KeyPerformanceIndicator, label: "Key Performance Indicator", short_label: "KPI", acronym: "KPI", note: "the acronym channel is what makes TN-002 bearable"} +- {iri: DataObject, label: "Data Object", short_label: null, acronym: null, note: null} +- {iri: DataElement, label: "Data Element", short_label: "Element", acronym: null, note: "drives the name of hasElement and hasGrainElement"} +- {iri: Database, label: "Database", short_label: null, acronym: null, note: null} +- {iri: Schema, label: "Schema", short_label: null, acronym: null, note: null} +- {iri: Field, label: "Field", short_label: null, acronym: null, note: null} +- {iri: System, label: "System", short_label: null, acronym: null, note: null} +- {iri: SystemType, label: "System Type", short_label: null, acronym: null, note: null} +- {iri: Transformation, label: "Transformation", short_label: null, acronym: null, note: null} +- {iri: BaseTable, label: "Base Table", short_label: null, acronym: null, note: null} +- {iri: ExternalTable, label: "External Table", short_label: null, acronym: null, note: null} +- {iri: View, label: "View", short_label: null, acronym: null, note: null} +- {iri: PrimaryKey, label: "Primary Key", short_label: null, acronym: null, note: null} +- {iri: ForeignKey, label: "Foreign Key", short_label: null, acronym: null, note: null} +- {iri: DataProduct, label: "Data Product", short_label: null, acronym: null, note: null} +- {iri: DataContract, label: "Data Contract", short_label: null, acronym: null, note: null} +- {iri: DataInterface, label: "Data Interface", short_label: null, acronym: null, note: null} - {iri: BusinessIntelligenceWorkspace, label: "Business Intelligence Workspace", short_label: "BI Workspace", acronym: null, note: null} - {iri: BusinessIntelligenceDataSource, label: "Business Intelligence Data Source", short_label: "BI Data Source", acronym: null, note: null} -- {iri: BusinessIntelligenceField, label: "Business Intelligence Field", short_label: "BI Field", acronym: null, note: null} +- {iri: BusinessIntelligenceField, label: "Business Intelligence Field", short_label: "BI Field", acronym: null, note: "reproduced whole in containsBIField under TN-011"} - {iri: BusinessIntelligenceReport, label: "Business Intelligence Report", short_label: "BI Report", acronym: null, note: null} -- {iri: OwnershipLayerObject, label: "Ownership Layer Object", short_label: null, acronym: null, note: "the categorisation role moves into rdfs:comment"} +- {iri: DataDomainOwner, label: "Data Domain Owner", short_label: "Domain Owner", acronym: "DDO", note: null} +- {iri: DataSubDomainOwner, label: "Data Sub Domain Owner", short_label: "Sub Domain Owner", acronym: "SDO", note: null} +- {iri: DataProductOwner, label: "Data Product Owner", short_label: "Product Owner", acronym: "PO", note: "not DPO - the initialism is taken by Data Protection Officer, a real GDPR role"} +- {iri: DataSteward, label: "Data Steward", short_label: "Steward", acronym: null, note: null} +- {iri: DataGovernanceLead, label: "Data Governance Lead", short_label: "Governance Lead", acronym: "DGL", note: null}