# T-BOX MIGRATION TO v2.1 — DECLARATIONS # ============================================================================= # Data consumed by migrate_tbox_v2_1.py. No renaming here: v2.1 declares what # v2.0 left silent. # # Three subjects, each closing a class of TN-025, TN-026 and TN-027 findings: # 1. polymorphism made explicit rather than inferred from prose # 2. domains stated wherever a single class of use exists # 3. provenance moved off the terms and onto the concrete classes # ============================================================================= meta: from_version: "2.0" to_version: "2.1" namespace: "https://ontology.pernod-ricard.com/metamodel/" # ----------------------------------------------------------------------------- # THE ANNOTATION ITSELF (TN-025) # ----------------------------------------------------------------------------- declare_annotations: - term: polymorphic label: polymorphic comment: > Declares that a property deliberately carries no rdfs:domain because it serves several classes with no useful common ancestor. Its scope is controlled class by class in SHACL instead. Without this axiom a deliberate omission and a forgotten one look identical, and no check can tell them apart. # ----------------------------------------------------------------------------- # POLYMORPHIC PROPERTIES — 18 # # The test: a property takes as domain the smallest common ancestor of its # classes of use, PROVIDED that ancestor sits below a layer root. A layer root, # a provenance axis and MetaModelObject are all too high to say anything; a # property whose smallest common ancestor is one of those is polymorphic. # ----------------------------------------------------------------------------- polymorphic: - {term: identifier, reason: "borne by every object in the graph"} - {term: canonicalName, reason: "borne by every object in the graph"} - {term: status, reason: "borne by every object in the graph"} - {term: version, reason: "borne by every object in the graph"} - {term: creationDate, reason: "borne by every object in the graph"} - {term: lastReviewDate, reason: "borne by every object in the graph"} - {term: arbitrationStatus, reason: "any declared object may be under arbitration"} - {term: ownedByDomain, reason: "smallest common ancestor is a provenance axis, not a layer class"} - {term: harvestDate, reason: "smallest common ancestor is a provenance axis, not a layer class"} - {term: sourceIdentifier, reason: "smallest common ancestor is a provenance axis, not a layer class"} - {term: belongsTo, reason: "sub-domain to domain and business object to sub-domain: two couples with no useful ancestor"} - {term: storedIn, reason: "two granularities, data object to structure and data element to field"} - {term: represents, reason: "data object to business object and data element to business concept"} - {term: unit, reason: "data element and metric sit in different layers"} - {term: sourcedFrom, reason: "data object and data structure sit in different layers"} - {term: fullyQualifiedName, reason: "DATABASE.SCHEMA.RELATION[.COLUMN] names a structure and a column alike"} - {term: ownedBy, reason: "any object may have an owner; Actor is the range, the domain is free"} - {term: exampleValue, reason: "observed on a field, documented on a data element"} - {term: physicalName, reason: "a data object names its table as a data element names its column; BR-013 names one carrier where there are two"} # ----------------------------------------------------------------------------- # DOMAINS TO DECLARE — 18 # ----------------------------------------------------------------------------- domains: - {term: formula, domain: Metric, basis: "shape; forbidden on BusinessConcept, which is what distinguishes a metric"} - {term: timeAggregation, domain: Metric, basis: "belongs to the calculation, alongside formula"} - {term: businessDefinition, domain: BusinessConcept, basis: "shape; forbidden on BusinessObject, whose meaning lives in its concept"} - {term: businessRule, domain: BusinessConcept, basis: "meaning belongs to the concept"} - {term: synonym, domain: BusinessConcept, basis: "meaning belongs to the concept"} - {term: technicalDefinition, domain: BusinessConcept, basis: "meaning belongs to the concept"} - {term: monitoredBy, domain: BusinessObject, basis: "shape; forbidden on DataElement and DataObject, where stewardship is inherited"} - {term: logicalFormat, domain: DataElement, basis: "a logical characteristic of the element"} - {term: isNullable, domain: Field, basis: "a property of the column"} - {term: ordinalPosition, domain: Field, basis: "a property of the column"} - {term: physicalDataType, domain: Field, basis: "a property of the column"} - {term: isInSchema, domain: DataStructure, basis: "shape"} - {term: viewDefinition, domain: View, basis: "a table has no SQL definition"} - {term: queryCount, domain: DataStructure, basis: "ACCESS_HISTORY traces tables, views and external tables alike"} - {term: lastQueryDate, domain: DataStructure, basis: "ACCESS_HISTORY traces tables, views and external tables alike"} - {term: definitionAddress, domain: Transformation, basis: "the Git URI of the code behind a transformation; a view uses viewDefinition"} - {term: expression, domain: BusinessIntelligenceField, basis: "the calculated-field formula, compared against the metric formula to detect drift"} # ----------------------------------------------------------------------------- # NEW TERM (procedure C1) # ----------------------------------------------------------------------------- declare_properties: - term: serviceCommitment kind: DatatypeProperty domain: DataContract range: "http://www.w3.org/2001/XMLSchema#string" comment: > What the contract guarantees about the product it covers: refresh schedule, freshness, quality thresholds, support channel, notice period on a breaking change. Held as prose for now, which no shape can verify; the structured form, aligned on ODCS, is the next step. Recorded here because the commitment had been written into businessRule for want of anywhere else, where it sat next to genuine business rules and could not be told apart. # ----------------------------------------------------------------------------- # RANGES MISSING ON POLYMORPHIC PROPERTIES # A polymorphic property may still have a single range: what it points AT can be # settled even when what it starts FROM cannot. # ----------------------------------------------------------------------------- ranges: [] # ----------------------------------------------------------------------------- # PROVENANCE (TN-026) # # A vocabulary term is declared, always and by definition. What has a provenance # is the INSTANCES, and the concrete class is where the model states which one. # Nothing is inherited: each class declares its own mode, and the mode agrees # with the provenance axis the class descends from. # ----------------------------------------------------------------------------- provenance: strip_from_non_concrete: true # abstract classes, properties, vocabulary terms derive_from_axis: true # CapturedObject -> HARVESTED, DefinedObject -> ASSERTED # ----------------------------------------------------------------------------- # ATTACHMENT (TN-027) # ----------------------------------------------------------------------------- attach: - term: GovernanceLayerObject parent: DefinedObject basis: > A layer root sits on a provenance axis like any other. Actors and governance objects are declared by governance, never harvested, so the governance layer descends from DefinedObject and its five roles inherit the axis. # SystemType remains outside the layers: it is a controlled-vocabulary class, # the named and closed exception of TN-027. Recorded as an open arbitration # rather than silently resolved here. # ----------------------------------------------------------------------------- # INSTANCE CORRECTIONS # Each one was surfaced by declaring a domain: an instance carrying a property # outside its domain is retyped by RDFS inference, and the shapes of the wrong # class then fire on it. # ----------------------------------------------------------------------------- instance_fixes: - action: remove property: businessDefinition subjects: [DI_06_01_001, DI_06_01_002] reason: > Meaning belongs to the Business Concept. An interface is a channel through which data is delivered; it defines nothing. Same rule the shapes already enforce on Business Object. - action: remove property: sourcedFrom subjects: [DI_06_01_001, DI_06_01_002] reason: > An interface has no system of truth: the data it exposes is sourced by the Data Objects behind it, and those name the system. - action: move property: businessRule to: serviceCommitment subjects: [DC_06_01_001] reason: > The text is a service commitment, not a business rule: refresh window, notice period, support channel. It was written into businessRule for want of a property to hold it.