ZAYAZ Physical Data Vocabulary (ZPDV)

1. Purpose

The ZAYAZ Physical Data Vocabulary (ZPDV) defines reusable semantic contracts for recurring physical data fields across ZAYAZ persistence layers.

ZPDV exists to ensure that a common field name carries the same core meaning wherever it is used. It standardizes canonical field names and naming patterns, precise semantic meaning, preferred PostgreSQL types and governed alternatives, nullability/default guidance, semantic and relationship constraints, aliases, PostgreSQL COMMENT templates, and future bindings to SSSR.

ZPDV is not a replacement for domain schemas, SSSR, database constraints, canonical architecture specifications, or governed identity/type registries. It is the governed bridge between recurring semantic concepts and their physical database representations.

2. Authority and source model

Architectural meaning remains canonical in Docusaurus. The machine-readable projection is config/data-governance/physical-data-vocabulary.json; its validation contract is schemas/physical-data-vocabulary.schema.json.

The machine registry MUST NOT redefine semantics independently of canonical specifications. Generated database catalogs remain evidence of physical implementation, not the source of architectural meaning.

For UOM-related fields, the Universal Organizational Model specification and its governed type/relationship registries define domain meaning. ZPDV standardizes the recurring physical field contracts used to persist that meaning.

3. Core rules

1. Names express semantic role; PostgreSQL types express physical representation. A field is not named *_date merely because it contains temporal data.
2. Same common name, same core meaning. created_at cannot mean persistence creation time in one schema and source observation time in another.
3. Instants default to timestamptz. ZAYAZ interprets and exchanges instants as UTC. date is used when the domain concept is intentionally calendar-date-only.
4. Domain semantics remain domain-owned. ZPDV standardizes recurring concepts; it does not force unrelated domain-specific fields into generic names.
5. Existing fields are classified before migration. ZPDV does not authorize blind renames or type changes.
6. Foreign-key representations must agree. When a ZPDV identity field is a physical FK, its PostgreSQL type must match the referenced key.
7. SSSR should bind, not duplicate. Once SSSR integration is governed, recurring signals should reference ZPDV identities instead of maintaining independent definitions.
8. Identity namespaces are explicit. eco_number, uom_number, and user_id are distinct governed identities and MUST NOT be replaced by generic entity_id, organization_id, tenant_id, or client_id where the canonical identity is known.
9. E-C-O family values share the eco_number field contract. ECO, EBU, EBP, PAR/WLP and other governed E-C-O family types remain distinguishable by their governed number type; the physical field remains eco_number when that family supplies the authoritative identity.
10. UOM classification is not UOM identity. uom_type and uom_category_code classify an object; uom_number identifies a UOM-owned object.
11. Relationship endpoints are neutral. UOM graph endpoint storage MUST NOT encode universal parent/child or source/target semantics; the governed relationship predicate supplies meaning.

4. Conformance classes

Existing database fields are classified as:

Class	Meaning
CONFORMANT	Name, meaning and physical representation agree with ZPDV.
VALID_SPECIALIZATION	A domain-specific specialization intentionally narrows a ZPDV concept without contradicting it.
LEGACY_ALIAS	Meaning is compatible but an older/non-preferred name is used.
NONCONFORMANT	Name, meaning or representation conflicts with the ZPDV contract.
REVIEW_REQUIRED	Available evidence is insufficient to classify safely.

A classification is an audit result, not permission to alter a database. Renames and type changes require dependency analysis and a governed migration.

5. Governed identity and UOM field family

The following recurring fields are canonical ZPDV concepts for the updated UOM architecture:

Field	Semantic contract
eco_number	Authoritative E-C-O identity-family value. Includes ECO organization identities and governed EBU/EBP scope identities where applicable.
uom_number	Authoritative identity of an independently identified UOM-owned object.
uom_type	Governed UOM semantic classification of an E-C-O-backed or UOM-owned graph object.
uom_category_code	Three-character UOM classification code on an E-C-O family registration; not a UOM Number prefix.
user_id	Globally governed identity of an individual ZAYAZ user.
relationship_id	Stable identifier of a persisted relationship assertion.
object_a	First neutral endpoint reference in a UOM relationship assertion.
object_b	Second neutral endpoint reference in a UOM relationship assertion.
uom_relationship	Governed UOM relationship predicate whose registry definition supplies directionality/inverse/symmetry semantics.
effective_from / effective_to	Business-time applicability interval for temporal relationship assertions and other governed facts.

object_a and object_b may physically reference an internal graph-node projection for referential integrity. They are not business identities themselves and MUST resolve transitively to an authoritative eco_number or uom_number.

Legacy generic entity_id/entity_type and organization_id fields require semantic classification before migration. Where they actually represent a UOM-owned identity they migrate toward uom_number; where they represent an E-C-O-family identity they migrate toward eco_number; where they are merely local surrogate keys they may remain local implementation identifiers.

tenant_id is not a canonical ZAYAZ-owned identity field. Multi-tenant isolation remains a deployment/security concern, but ZAYAZ-owned business identity and scope use their governed semantic identities. Provider-native fields such as microsoft_entra_tenant_id remain valid external/provider identifiers.

6. Initial vocabulary

The machine-readable registry contains the controlled concept set. It intentionally starts with recurring cross-schema concepts rather than attempting to standardize every domain-specific column.

Semantic families include temporal semantics, governed identity and UOM classification, actor attribution, provenance/correlation/causation/trace identity, lifecycle/versioning, integrity, evidence/verification, units, uncertainty, and relationship semantics.

The registry grows only through reviewed evidence from canonical architecture, physical database catalogs, governed migrations, and SSSR reconciliation.

7. Database description contract

For fields bound to a ZPDV concept, PostgreSQL descriptions SHOULD be derived from the concept's description_template, narrowed with domain context where needed. A generated description must not invent business meaning absent from canonical documentation.

Descriptions should answer, where applicable, what the field represents, which identity/lifecycle boundary it belongs to, applicable representation rules, the referenced object, and what null means.

COMMENT ON COLUMN is the governed physical projection. Generated database catalog JSON remains a read-only observation of that projection.

8. SSSR reconciliation

SSSR is the semantic signal registry; ZPDV is the reusable physical-data vocabulary. Their responsibilities are complementary. ZPDV defines recurring physical-field semantics and representation guidance; SSSR defines signal identity, semantic meaning, metadata, lineage, and governed bindings. A signal may bind to a ZPDV concept when the physical field implements that recurring semantic contract.

The preliminary workbook observations embedded in the machine registry are bootstrap evidence only. They must be reclassified against canonical SSSR architecture and the eventual governed SSSR database table.

9. Change governance

A ZPDV change that alters the meaning of an existing concept is compatibility-sensitive. Prefer a new concept, deprecation, or explicit migration rather than silently redefining an established identity.

A proposed physical rename or type change must be evaluated for FK/index dependencies, application/API contracts, SSSR bindings, ZAR/Pergamum Pulse lineage, Hecate implementation Needs, replay/evidence implications, and white-label isolation/security behavior.

ZPDV therefore acts as a classification and design authority, not an automatic DDL rewrite engine.

10. Validation

Validate the machine registry with:

node scripts/database/validate-physical-data-vocabulary.mjs

Validation applies the declared Draft 2020-12 JSON Schema first, then supplemental semantic checks for duplicate identities, semantic-category membership, and canonical-field/alias collisions.

---