The Semantic Drift Register: When a Facility Field Keeps Its Name but Changes Its Meaning

A facility field can survive a software release unchanged and still become a different field.

The API still says occupancy_rate. The dashboard still shows “Occupancy.” The export still has the same column. The data type is still a number. Every structural test passes.

But the denominator now excludes offline units. The observation moved from UTC midnight to the facility's local end of day. A different service owns the result. Historical values were recomputed with a new transformation. The same 0.91 no longer makes the same statement.

That is semantic drift: a change in what a field means, even when its label, path, or datatype appears stable.

This matters in self-storage because one field can travel far. An operating-system value can become a manager queue, portfolio report, customer-message draft, automation condition, model feature, retrieval document, or executive summary. If the meaning changes silently, each downstream consumer can remain technically healthy while acting on the wrong contract.

The answer is not a larger data dictionary. It is a versioned semantic drift register: a release control that records the old meaning, proposed meaning, changed dimensions, affected consumers, compatibility judgment, migration evidence, approval authority, and rollback contract for every consequential field change.

The companion package includes a fictional 15-row register, a 40-case readiness suite, a structural JSON Schema, a fictional contract instance, a practical release gate, and an accessible architecture diagram. The exact sources and limitations are in the source register.

This is an authored proposed method. It does not describe a deployed product, customer implementation, accepted industry definition, model capability, measured result, service level, certification, legal conclusion, safety procedure, or financial conclusion. All operational examples and records are fictional.

Open the full-size accessible diagram.

Governed companion package

Use the method. Test the failure paths.

These files contain fictional examples and structural tools. They do not establish a live facility fact, product capability, customer result, operating performance, certification, or independent validation.

Download the semantic-drift register ↓Download the semantic-drift readiness suite ↓Download the Draft 2020-12 semantic-contract schema ↓Download the fictional semantic contract ↓Download the semantic-drift release gate ↓Download the accessible semantic-drift register SVG ↓Download the semantic-drift register PNG ↓Download the source and limitations register ↓

A field name is an interface, not a definition

Operators often inherit meaning from a label. “Available units” sounds obvious. “Closed” sounds final. “Sent” sounds complete. “Confidence” sounds comparable. None of those labels supplies the operating contract.

For a consequential field, the meaning is distributed across at least ten dimensions:

1. Identity scope — which facility, unit, account, device, work item, or other stable identity the value describes.
2. Population — what may enter the numerator, denominator, or record set, including explicit inclusion and exclusion rules.
3. Value kind, unit, scale, and direction — count versus rate, feet versus meters, fraction versus percent, and whether a higher score means more or less urgency.
4. Time basis — which clock governs the value, the effective interval, cutoff, timezone, lateness rule, and restatement policy.
5. Source authority — which field and owner may state the fact, not merely which system can emit it.
6. Null semantics — whether absence means unknown, unobserved, not applicable, withheld, unavailable, error, or prohibited.
7. State machine — the allowed values, transitions, evidence requirements, and terminal-state definition.
8. Transformation — the calculation, version, inputs, rounding, thresholds, joins, and calibration that produced the value.
9. Permitted decision use — display, advice, routing, approval input, or action gate.
10. Evidence boundary — what the value does not establish.

Change any one of those dimensions and the old consumer assumptions may no longer hold.

The W3C RDF Data Cube Vocabulary separates dimensions, measures, and interpretive attributes such as unit, scale, and status. QUDT's dated schema documentation provides general quantity and unit concepts. Those specifications are useful vocabulary, not self-storage metric policy. A unit identifier cannot choose a denominator, a source owner, or the decision for which a value is fit.

Treat the field name as a stable interface label. Treat its semantic contract as the versioned definition behind that interface.

The facility examples that expose the problem

Occupancy without a denominator

Suppose a fictional portfolio originally calculates occupancy_rate as occupied configured units divided by all configured units at UTC midnight. A new definition uses active occupied rentable units divided by rentable units, excludes offline-maintenance and company-use spaces, and observes the facility's local end of operating day.

The label and numeric range can remain unchanged. The population and clock have changed. That is a breaking semantic change. A dashboard that draws one continuous line across both versions manufactures comparability the contract does not support.

The release needs more than a successful query. It needs a versioned denominator, effective date, dual calculation, consumer inventory, owner approval, historical-series decision, and executable rollback.

A note that becomes “closed”

Imagine a fictional maintenance service in which work_order_status = closed once meant that a technician note existed. A later operating definition requires the represented condition, completion evidence, authoritative readback, and a qualified closure disposition.

Both versions may serialize the word closed. They do not mean the same operational state.

This is not a cosmetic documentation issue. A portfolio exception queue, reopen rule, invoice workflow, and AI-generated summary may each depend on the terminal-state meaning. The register should identify every consumer and prevent the new state machine from being treated as a patch.

“Granted” is not passage

A fictional access event may call a request granted when a controller authorized it. Another consumer may interpret granted as evidence that a door opened or a person passed through. The value did not drift inside the producer; its meaning drifted at the consumer boundary.

The semantic contract should say what the event represents and explicitly exclude what it does not prove. Event identity, source, type, subject, time, and dataschema can travel in a CloudEvents 1.0.2 envelope. That envelope does not prove the event is true, authoritative, causally sufficient, reconciled, or compatible with a new meaning.

A confidence score that changes model families

Now consider a fictional confidence_score on a human-review queue. Version one is a raw model probability. Version two is a calibrated review-priority score from a different model family and evaluation population. Both values remain between zero and one.

Reusing the old 0.8 routing threshold would be a semantic error even if the new model is structurally compatible. The required evidence is not “the API returned a number.” It is the named model and contract version, evaluation population, calibration evidence, threshold disposition, queue-behavior check, knowledge limits, human-review authority, and rollback path.

The NIST AI RMF 1.0 emphasizes intended purpose, context, risk, knowledge limits, data dependencies, human-AI roles, measurement, and lifecycle management. The NIST Generative AI Profile, AI 600-1, addresses concerns including confabulation, automation bias, information integrity, and human-AI configuration. Both are voluntary and cross-sector. Neither certifies a semantic contract, validates a model, or proves a threshold operationally fit.

Give every meaning its own contract version

One semantic contract should describe one term at one version. It should be immutable once released. A correction creates a successor; it does not rewrite the record that prior decisions cite.

At minimum, record:

• contract ID and semantic version;
• stable term ID and display label;
• definition and evidence boundary;
• producer, authoritative owner, and approval owner;
• value kind, unit, scale, direction, precision, and allowed values;
• population, inclusion, and exclusion rules;
• null semantics;
• event, observation, effective, and recording clocks where applicable;
• source schema and transformation versions;
• named downstream consumers and permitted decision uses;
• predecessor contract and change summary;
• compatibility class;
• migration, dual-read, backfill, approval, and rollback requirements.

The W3C Data on the Web Best Practices recommends persistent identifiers, version indicators, version history, provenance, vocabulary reuse, appropriate formalization, and care with breaking changes. It is web-data publication guidance, not a facility change classifier. The operating team still has to define what compatibility means for a specific consumer.

PROV-O can represent entities, activities, agents, derivation, revision, generation, attribution, and invalidation. OWL 2 has formal ontology and versioning vocabulary. Those mechanisms can make lineage and relationships inspectable. They do not prove a definition correct, complete, authoritative, current, compatible, approved, or safe for a decision.

The companion semantic-contract schema demonstrates one structural envelope under JSON Schema Draft 2020-12. JSON Schema Core and Validation define identifiers, vocabularies, evaluation, applicators, and validation keywords. A conforming instance proves only that declared structural constraints pass. It does not prove that the declaration matches code, source data, owner intent, or operating reality.

Classify compatibility from the consumer's point of view

The register uses four deliberately conservative classes:

• Additive — new information is introduced without changing existing meaning, and every consumer has demonstrated safe unknown-field or unknown-value behavior.
• Non-breaking — representation changes while meaning stays stable, and affected consumers pass their declared compatibility tests.
• Breaking — a consumer assumption about identity, population, unit, time, authority, null, state, transformation, or decision use can change.
• Unknown — evidence is incomplete, ownership is unresolved, or a hidden consumer may exist.

Compatibility is not an intrinsic property of a producer schema. It is a relationship between a candidate contract and a named consumer under a named use.

Adding an enum value can be additive for a raw archive and breaking for a dashboard that maps unrecognized values to “complete.” Moving a field to a new producer can be non-breaking for a display and unknown for an action gate until source parity and clock behavior are demonstrated. Changing a description can be breaking if the code already changed and documentation merely caught up.

Semantic version labels help communicate intent, but the version number does not decide compatibility. Calling a denominator change 2.4.2 does not make it a patch. The register should reject the label when the diff says otherwise.

The seven-gate semantic release

Gate 1: Detect the actual semantic diff

Compare the candidate and predecessor contract across every dimension. A textual definition diff is not enough. Examine data population, states, source ownership, transformations, clocks, units, null handling, decision permissions, and exclusions.

Store the exact contract digests and transformation identities. A matching digest proves byte identity only. It does not prove truth.

Gate 2: Identify every consumer and decision

Inventory APIs, dashboards, exports, spreadsheets, alerts, automations, model features, retrieval corpora, prompts, reports, and human procedures. For each one, name the term version it consumes and whether the use is display-only, advisory, routing, approval input, or action gating.

An undocumented consumer is not evidence of compatibility. It is an unresolved dependency.

Gate 3: Classify compatibility and consequence

Classify from each consumer's view. A single field change can be non-breaking for one use and breaking for another. Apply the highest consequence until the dependency set is complete.

Keep reversibility separate from consequence. A change can be easy to roll back technically and still corrupt a historical comparison or human decision record.

Gate 4: Dual-read and reconcile

For breaking or unknown changes, calculate or read the predecessor and candidate side by side during a bounded interval. Preserve both contract IDs and observation clocks. Log every disagreement by reason rather than averaging it away.

Dual-read is not migration acceptance. It is evidence collection. The owner must decide whether each difference is intended, erroneous, late, outside scope, or unresolved.

Gate 5: Test history, thresholds, and AI paths

Replay representative historical cases without overwriting original series. Revalidate thresholds against the new meaning. Test late events, timezone edges, nulls, unknown codes, identity conflicts, and state transitions.

For AI-assisted work, test the entire knowledge path. A retriever that mixes work-order examples from semantic versions three and four can produce a fluent answer whose citations individually exist but whose operating meaning is incoherent. Pin the approved corpus or expose the conflict. Do not let generated summaries recirculate as source authority.

The companion 40-case readiness suite supplies fictional cases from beginner label and unit checks through architect-level version graphs, cross-contract dependencies, event-schema negotiation, retrieval-version mixing, and executable rollback.

Gate 6: Approve the migration contract

Approval should bind to the exact predecessor, candidate, consumers, effective interval, dual-read evidence, backfill decision, threshold decision, and rollback version. Source authority, transformation ownership, decision authority, and execution authority may belong to different people or systems. Preserve those distinctions.

If required evidence or ownership is missing, keep the candidate quarantined. A display may show a provisional value with a visible boundary; a consequential action should not inherit certainty the evidence does not support.

Gate 7: Release, read back, and preserve rollback

Release the contract and implementation together. Verify consumer behavior from governing output, not merely from a successful deployment command. Record the effective time, actual bytes, source and deployment identities, migrated consumers, remaining exceptions, and readback result.

Keep the prior contract, executable transformation, inputs needed for rollback, and historical series. If rollback cannot reproduce the prior meaning, it is not a rollback plan.

Treat time as part of meaning

“Latest” is not a semantic definition.

The W3C Time Ontology distinguishes instants, intervals, durations, positions, reference systems, and temporal relations. It does not select the governing business clock. A facility contract should declare whether a value is governed by event time, observation time, posting time, facility-local day, report interval, or another explicit rule.

For a change itself, preserve at least:

• when the candidate was authored;
• when evidence was observed;
• when approval occurred;
• when the new meaning becomes effective;
• when each consumer migrated;
• when dual-read begins and ends;
• and when prior meaning becomes invalid for new decisions.

This prevents a future-effective contract from rewriting today's value and prevents a late-arriving observation from masquerading as a new operating state.

Do not confuse structural validation with semantic truth

Structural validators are valuable because they catch missing fields, invalid datatypes, malformed versions, and declared constraint failures. SHACL defines shapes, targets, constraints, results, and conformance reports for RDF graphs. JSON Schema serves a similar structural role for JSON instances.

Neither can determine, by itself, whether occupancy_rate excludes the right units, whether the claimed owner has authority, whether code matches the declaration, whether the consumer found every dependency, or whether an operational decision is justified.

A strong release record therefore separates four states:

1. syntactically valid — the file parses;
2. structurally conforming — declared machine constraints pass;
3. semantically reviewed — responsible owners disposition the meaning and compatibility evidence;
4. operationally reconciled — named consumers and governing outputs match the approved contract after release.

None of those states is publication, indexing, coverage, recognition, certification, or proof of measured value.

Start small: one field, one predecessor, one decision

An operator does not need an enterprise ontology program to begin.

Choose one consequential field that has caused disagreement. Record the current term ID, definition, population, unit, clock, source owner, null meaning, transformation, consumers, decision use, and evidence boundary. Find the predecessor meaning. Classify the change. Run one dual-read. Ask one owner to disposition the mismatches. Preserve one rollback.

For beginners, the companion register can be used as a spreadsheet. Intermediate teams can validate change manifests in release review. Advanced teams can bind contract IDs to events, metrics, feature pipelines, dashboards, and retrieval corpora. Architects can add dependency graphs, immutable digests, automated semantic diffs, policy checks, and consumer conformance suites.

The maturity test is not how formal the vocabulary looks. It is whether an operator can answer five questions before a changed field reaches work:

1. What did this term mean before?
2. What exactly does it mean now?
3. Which consumers and decisions depend on that difference?
4. Who approved the migration from which evidence?
5. How do we detect failure and restore the prior meaning?

If those answers are missing, the field has not been safely versioned. It has only been renamed by implication.

The operating principle

Stable labels create confidence. Versioned meaning creates control.

A self-storage operating system should never assume that a field is unchanged because its name, datatype, route, or screen position survived a release. The system should be able to reconstruct the semantic contract that governed the value, the consumer assumption that governed the decision, and the evidence that justified the transition.

The semantic drift register turns a subtle data problem into visible operating work. It gives the beginner a precise question, the operator a release checklist, the data owner a compatibility record, and the architect a contract that can be tested without pretending that machine conformance is truth.

When a facility field keeps its name but changes its meaning, the change should not hide inside the next dashboard refresh. It should arrive as a versioned, reviewable, reversible decision.