Product Language and Data Semantics

Software products depend on words and data whose meaning is often more specific than their names suggest. For example, a field called country may represent legal employment country, residence, nationality, or the jurisdiction used for a particular calculation. An organizational term may carry one enterprise-wide definition while a product uses a narrower interpretation. An upstream system may expose one hundred fields while holding business authority for only a subset of them. Humans with long product history often resolve these cases from experience. AI systems can instead produce a plausible interpretation from the field name, provider documentation, or general-language meaning and proceed as though that interpretation were established product knowledge.

Specification-First Delivery treats product language and data semantics as durable product context within the Shared Knowledge System. The required outcome is current product meaning that qualified humans and AI can discover before they rely on terminology or external data in a specification, implementation, test, review, or operational decision.

The product can inherit organizational terminology and provider semantics when those meanings fit its consumer context. It can also record a product interpretation when the organization or external system uses a concept differently. The authority to change a semantic definition follows its scope: organizational definitions remain under organizational authority; product-wide meanings require delivery-team consensus; a meaning confined to one functional area can remain under the accountable authority for that area when no wider product behavior depends on it.

Data semantics extend the same responsibility to interfaces. APIs, databases, event streams, files, MCP tools, knowledge graphs, and other external systems need a semantic interface that communicates enough meaning for the product to use their data responsibly. OpenAPI provides a mature precedent for the underlying design philosophy, even when a product does not expose APIs. Its maintained description brings machine-readable structure together with human-readable descriptions, constraints, enumerations, examples, and other interface information that humans and software can interpret.¹ Specification-First Delivery applies this semantic-design principle across external system types without requiring OpenAPI or any single documentation technology.

Back to top

1. Product Language and Semantic Authority

Product language is the current vocabulary through which a delivery team interprets product concepts consistently. It includes terms that name users, business facts, states, responsibilities, workflows, categories, and other concepts whose meaning can affect delivery. Its purpose is operational: another qualified participant should be able to use the same term in a requirement, specification, data interpretation, implementation, and review without reconstructing its meaning from private memory.

When independent systems need to exchange and reason over a shared domain, a formal ontology is one way to make that meaning explicit. It names the concepts in the domain, defines the relationships among them, and constrains how those concepts should be interpreted so that different systems can use the same vocabulary consistently. Gruber's work on portable ontology specifications formalized this problem as defining a common vocabulary for a shared domain of discourse so represented knowledge could be shared across AI systems.² Product Language usually needs a lighter representation. The product still needs explicit concepts, meanings, relationships, and constraints wherever ordinary language or external terminology permits more than one materially different interpretation.

The Shared Knowledge System paper establishes organizational context and product context as separate layers of knowledge. Product Language applies that model to terminology. An organization may maintain enterprise definitions in a glossary, knowledge graph, data catalog, internal portal, or another context layer. The product can reference those definitions directly when they express the meaning the product uses. When the product's consumer context requires a narrower, mapped, or otherwise different interpretation, product context records that interpretation while preserving the relationship to the organizational source.

An organizational context layer can make shared enterprise meaning easier to discover. A central glossary, data catalog, or knowledge graph can expose common definitions, relationships, ownership, and authoritative references without requiring every product to reproduce them. It is particularly useful when many products need to identify the same enterprise concepts or route a question to the organizational function that owns them.

For AI-assisted software delivery, product context should be the primary semantic context for product decisions. A single enterprise definition may be correct at organizational scope and still be too broad, differently scoped, or incomplete for a particular product. Organizational context therefore serves as an upstream and secondary semantic source unless the product explicitly adopts its definition. When organizational knowledge is loaded automatically, the product interpretation or override must remain discoverable with sufficient authority that a human or AI participant can determine which meaning governs the current product decision.

Semantic scope determines the impact of change. A product-wide term can appear across requirements, interfaces, source code, tests, analytics, operational procedures, and user communication. Changing its meaning changes the interpretation of all of those surfaces even when no identifier changes immediately. A product-wide semantic change therefore requires reviewed agreement across the delivery team functions that depend on the meaning.

Some semantics have a legitimately smaller scope. A field used only inside one specialist calculation may have a meaning that no other product function consumes. The accountable specialist can own that semantic decision when its scope is demonstrably confined. If later work makes the concept shared, its semantic scope and review responsibility expand with that use.

Back to top

2. Consumer-Context Semantics

The meaning supplied by an external source describes the source's own model. A product also needs to know what that concept means when consumed for its own purpose. The resulting interpretation is consumer-context semantics: the product records the meaning it needs from the provider concept and the mapping between them when the two are not identical.

Database-integration research provides a strong precedent for treating context as part of meaning. Kashyap and Sheth model semantic proximity between database objects relative to a context of comparison, making the context part of how semantic similarity and schema correspondence are understood.³ The Context Interchange work of Goh, Bressan, Madnick, and Siegel similarly treats semantic heterogeneity through source and receiver contexts, allowing information to be interpreted according to the assumptions of the consuming context instead of assuming that one representation carries a universal meaning.⁴

Consider a large organization with a central workforce platform. An enterprise catalog may correctly describe it as the authoritative workforce system. A payroll product may consume employee identity, employment status, compensation attributes, and payment-related organizational facts from that platform. A workforce demographics dashboard may consume organizational hierarchy and demographic attributes from the same platform. The upstream system is identical, but the relevant business meaning of the dependency differs because each product consumes a different subset of facts for a different purpose.

The product should therefore record the relationship that matters to its own decisions. For the payroll product, the workforce platform may be the canonical consumption source for employment status while another system remains the underlying business authority for a tax classification. For the demographics product, the same workforce platform may be relevant primarily as the source of hierarchy and demographic facts. A relationship recorded only as depends on workforce platform leaves a human or AI participant to infer which facts and meanings are actually relevant.

Consumer context also affects whether data is suitable for the task. Wang and Strong's data-quality framework identifies contextual data quality as the requirement for data to be appropriate to the task at hand, based on evidence gathered from data consumers.⁵ Product semantics give that task context a durable form for delivery. A provider's value can be valid within its own model while still requiring a product-specific interpretation, mapping, representation rule, or authority check before the product relies on it.

A semantic mapping may preserve the same stored value while changing the scope or business interpretation applied by the product. Other mappings change both representation and meaning. The Knowledge System should preserve whichever relationship another participant needs in order to use the data correctly.

Back to top

3. Structural and Semantic Representation of Data

A useful data contract communicates structure together with the business meaning needed to interpret that structure. Types, formats, enumerations, descriptions, examples, units, lifecycle meaning, and other constraints can all contribute. The required depth depends on the ambiguity and consequence of the data being consumed.

OpenAPI is a useful semantic-design precedent because it places structural and descriptive information in a shared contract that human readers and software tooling can both consume.¹ A field can carry its type and format together with a description, allowed values, examples, and other constraints, while operations can carry enough description for a consumer to understand their intended use. The useful principle is the co-location of machine-readable structure and explanatory semantics in an accessible maintained interface. Specification-First Delivery applies that principle to any external system communication method that materially affects the product.

For example, a physical database definition such as:

country VARCHAR(3)

only communicates storage structure, while several product meanings remain possible. A semantic definition can establish that the concept is the country of legal employment, that the product's canonical representation is ISO 3166-1 alpha-2, and that residence country and nationality are separate concepts. The same principle applies to a timestamp: its semantic definition states whether it represents event time, effective time, processing time, record-update time, or another lifecycle point that affects product behavior.

Wand and Wang model information systems as representations of real-world systems and derive data-quality problems from possible failures of that representation, including ambiguity and lack of meaningfulness.⁶ A structurally valid field can therefore remain semantically inadequate for delivery when the participant cannot tell which real-world fact, state, unit, or lifecycle point it represents.

Back to top

3.1. Semantic Interfaces for External Systems

Specification-First Delivery requires an understandable semantic interface for external information that materially affects delivery. The implementation mechanism can match the system and organization:

• An API may expose OpenAPI, equivalent machine-readable documentation, or another maintained contract.

• A database may expose schema metadata, column descriptions, a data catalog, governed documentation, or a product-level semantic mapping.

• An event stream or file interface may maintain event and field semantics alongside its schema and compatibility rules.

• An MCP server may carry meaningful tool, parameter, and result descriptions that the AI client can retrieve during work.

• A knowledge graph may expose organizational concepts while the product records the interpretation that applies to its own consumer context.

Modern AI tool-use research reinforces the value of an accessible semantic interface. Gorilla identifies incorrect or hallucinated API use as a material LLM failure mode and reports that combining the model with document retrieval improves adaptation to changed API documentation and reduces hallucination.⁷ ToolLLM approaches tool use at larger scale by training and evaluating against 16,464 real-world REST APIs while using API retrieval to select relevant tools.⁸ These studies focus on selecting and invoking tools correctly. Product delivery adds another responsibility: after the correct external interface is found, the participant must still apply the product's intended meaning, authority, and consumer context.

The semantic interface therefore needs to be reachable through the access path that participants actually use. Documentation that is clear to a human but unavailable to an AI coding agent leaves the AI to infer meaning from schema names or examples. Machine-readable metadata that an AI can retrieve but whose authority is unclear to the delivery team creates the inverse problem. The Knowledge System Readiness for Specification-First Delivery paper requires the relevant knowledge to be both reachable and authoritative for the responsibility being performed.

Back to top

3.2. Minimum Semantic Records

The practical record should remain small enough to maintain. A semantic entry usually needs five fields:

Concept:
Meaning:
Source:
Scope:
Date:

Concept identifies the term or data concept being interpreted. Meaning states the current product meaning in natural language. Source identifies where the relevant definition or data is obtained, such as an organizational definition, provider contract, product decision, API, database, or other governed source. Scope states where the meaning applies, such as product-wide or a named functional area. Date records when the current semantic decision became authoritative or was last materially revised, which helps a participant recognize that an older copy may have been superseded.

For example:

Concept: Employment country
Meaning: Country under which the employee is legally employed.
Source: Workforce API; canonical consumption source for this product.
Scope: Product-wide.
Date: 2026-08-28.

Additional fields are added only when they remove a material ambiguity. Representation may state ISO 3166-1 alpha-2 when the product must distinguish US, USA, and United States. A mapping note may explain that an external concept maps to a narrower internal concept. An active alias may be recorded when a current interface, user group, or legacy identifier still uses it. The record stays proportionate because many ordinary product terms need only concept, meaning, source, scope, and date.

Back to top

3.3. Creation Triggers and Maintenance Routing

A semantic entry becomes useful when delivery encounters a meaning that can no longer be left implicit. The trigger is material ambiguity or new semantic responsibility, not the mere existence of a field or term.

The authoritative record can live where its meaning is easiest to maintain and retrieve. Provider semantics may remain in OpenAPI, schema metadata, a data catalog, MCP descriptions, or another external contract when that source is adequate and reachable. Product interpretations should remain in product context, such as a product glossary, a small data-semantics document, or another governed product knowledge source. The product should reference existing authoritative semantics instead of copying them when a reference gives humans and AI a reliable access path.

Governing Instructions can make semantic maintenance part of normal delivery. For example, repository-level instructions may require a human or AI participant to check applicable Product Language and Data Semantics before changing an external field, shared product term, canonical source, or representation rule, and to propose a semantic update when the increment creates one of the triggers above. In a repository-centered implementation, AGENTS.md can carry those always-applicable instructions. A Structured Discussion with AI coding agents can also identify, revise, or maintain relevant semantic records.

A selectively loaded Skill can reduce the navigation and clerical overhead as the semantic library grows. A semantic-directory Skill can identify relevant concepts from the terms, fields, interfaces, or sources touched by the current job; load the authoritative records; compare current external definitions with product mappings; and draft candidate updates when it detects a gap. Material changes still follow the semantic authority defined later in this paper. Automation can therefore reduce maintenance effort while accountable humans retain authority over product-wide or specialist semantic decisions.

Back to top

4. Data Authority, Canonicality, and Provenance

Business authority belongs to the underlying fact or decision within a defined context. The interface that exposes a value may originate it, copy it, transform it, enrich it, aggregate it, cache it, or republish it. Product semantics therefore need enough authority and provenance information to distinguish the approved place to consume a value from the authority that establishes the underlying business fact.

Three related questions are useful.

This model handles a common enterprise integration case. Suppose a service exposes one hundred employee fields. Twenty are maintained directly by the service's owning domain, while eighty arrive through ETL from other systems. The service may still be the organization's canonical consumption interface for all one hundred fields. A product can therefore be expected to consume every field from that service while recognizing that business authority for many of those facts remains elsewhere.

The reverse case is also possible. A convenient reporting database may expose a field that originated in the authoritative source while the product's approved canonical consumption source is another interface whose refresh cycle, transformation, and operating contract fit the intended use. Canonicality is a fact-and-consumer-context designation: it identifies which source the product should use for a defined fact in that context.

Data-integration practice has long treated heterogeneous source data, schema transformation, and cleaning as related responsibilities. Rahm and Do describe data cleaning as especially important when heterogeneous sources are integrated and argue that it should be addressed together with schema-related transformation.⁹ For a product that requires one canonical country representation, or that must distinguish provider values with different business meanings, the semantic requirement can be made accessible before implementation so an engineer or AI agent has an agreed basis for transformation.

Back to top

5. Establishing Product Language and Data Semantics

Establish product semantics from the terminology and external information that current delivery actually depends on. A usable semantic baseline focuses on current product decisions and expands as later work exposes additional ambiguity.

The first pass should focus on concepts where a plausible alternative interpretation would change behavior. Common candidates include overloaded business terms, states with lifecycle significance, identifiers whose uniqueness is scoped, measurements with implicit units, country or jurisdiction codes, timestamps, externally supplied categories, calculated values, and fields that appear authoritative because they are widely exposed.

Existing semantics should be reused when they are adequate. If an organizational glossary already defines a term exactly as the product uses it, the product can reference that definition and record its scope. If an OpenAPI description already communicates the provider concept and the product uses the same meaning, the product can link to that contract. A new product record becomes useful when the consumer context adds or changes meaning, source authority, representation, or scope.

A team can begin with the semantics material to the decisions it is making. When an engineer, Product Owner, analyst, specialist, or AI participant encounters an ambiguity that can alter intended behavior, the ambiguity becomes a readiness gap and is routed to the role with the relevant authority before dependent work relies on an invented answer. Subsequent increments extend the semantic baseline when they introduce or expose additional concepts.

Back to top

6. Semantic Lifecycle, Scope, and Change Authority

Product semantics are intended to be relatively stable current-state knowledge. Implementation changes can reuse the same semantic record for many increments when the underlying product concept, consumer context, representation, and authority remain unchanged. A semantic revision becomes necessary when the meaning that future delivery should use has materially changed.

Common change triggers include material product drift that changes what a concept means or where it applies; a new product function that broadens a previously local concept; a provider, organizational definition, code set, or external contract that changes the facts supplied to the product; a canonical source or provenance decision that changes how the product should obtain a fact; and new operating or domain evidence showing that the current semantic record no longer describes reality. A representation-only change can update the applicable representation rule while preserving the underlying concept when the business meaning remains the same.

Semantic authority follows the scope of the meaning being changed. This keeps shared definitions stable while allowing local expertise to maintain genuinely local semantics.

Organizational semantics remain under the authority of the organizational owner. A product can adopt the definition, reference it, or record a product interpretation. The organizational definition remains under its existing authority while the product governs its own interpretation.

Product-wide semantics are shared current-state product knowledge. A material change can affect Product Intent interpretation, Stable Use Cases, specifications, source code, integration logic, test expectations, analytics, support procedures, and other delivery surfaces. The delivery team therefore reaches consensus on a product-wide semantic change before the new meaning becomes authoritative. Relevant domain, product, data, architecture, engineering, and specialist participants contribute according to where the meaning is used.

Function-scoped semantics can remain under the accountable authority of the function that owns them when the concept is demonstrably confined to that area. A data specialist may maintain the meaning of a field used only in one analytic calculation, for example. If another product function begins to consume the concept, the scope is reassessed and the semantic decision is reviewed at the wider level.

External systems can publish their own semantic definitions, and those definitions remain important source context. The product decides how those concepts map into its own language. A provider field may map directly to one product concept, map to a narrower internal concept, require a representation conversion, or be unsuitable for a particular use. Engineers and AI participants can identify mismatches and propose mappings, while the accountable product, domain, data, or specialist authority confirms the meaning that becomes current product knowledge.

A proposed semantic change triggers a scope-based impact review. The delivery team identifies the specifications, interfaces, implementation, tests, current documentation, analytics, operational procedures, or downstream consumers that rely on the current meaning. The review establishes both whether the semantic change is approved and which dependent surfaces must change with it.

After approval, the team completes the semantic change through the delivery path that its scope requires:

1. update the authoritative current semantic record, including its date, scope, source, representation, and mapping information that changed;

2. update affected current-state knowledge, interface descriptions, specifications, implementation, tests, and other dependent surfaces through the applicable delivery increment;

3. preserve material rationale in decision history when future participants may need to understand why the meaning changed; and

4. verify that normal human and AI context resolves to the new current meaning without presenting a superseded definition as an equally authoritative choice.

A semantic revision becomes complete when the current record and the product surfaces that depend on it express the same approved meaning.

Back to top

7. Semantic Maintenance and Context Control

Product semantics are current-state knowledge. As the product evolves, the maintained language should reflect the meaning that participants are expected to use now. This is especially important for AI context because old and current definitions presented together can turn a resolved ambiguity back into an active choice.

Active aliases can remain when they help participants interpret a current interface, legacy identifier, user expression, or external source. They can be recorded beside a glossary entry or in a small aliases.md index. Current-state knowledge should otherwise use the replacement terminology consistently so the normal context presented to humans and AI remains concise and authoritative.

Material semantic decisions can remain available through decision history. For example, if two terms were once ambiguous and the delivery team resolved them into separate concepts, the current glossary can present the resolved meanings while a decision-history.md file, governed decision system, or equivalent source preserves why the decision was made. The historical record can be loaded when rationale is needed without occupying the default context for every future job.

Organizational and provider changes trigger the same maintenance discipline. When an enterprise glossary, knowledge graph, API contract, or external schema changes, the product reassesses the mappings that depend on the changed semantics. The current product interpretation remains authoritative until the appropriate product-level review revises it. This gives external semantic change a clear route into the product without allowing upstream wording alone to alter product meaning.

This maintenance model applies Progressive Context Loading to semantics. Current product language and directly applicable data meaning stay easy to reach. Detailed provider definitions, organizational context, transformation history, and prior semantic decisions are loaded when the responsibility requires them. The result gives AI enough context to avoid guessing while keeping the normal context focused on current meaning.

Back to top

8. Validation of Semantic Readiness

Semantic readiness can be tested through the unfamiliar-participant method defined in the Knowledge System Readiness for Specification-First Delivery paper. A qualified participant with no prior product history is given a representative product term or external data dependency and asked to interpret it through the normal Knowledge System access path. The participant may be a human or an AI system operating with the same authorized product context available during delivery.

A semantic area is ready when an unfamiliar qualified participant can retrieve the current meaning, apply it to the relevant consumer context, identify the source and representation details needed for the task, and route unresolved material questions to the correct authority without relying on private product history. The AI version of the test should use the actual context path available to the delivery tool. If the required meaning exists but the AI cannot reach it, or if several retrievable definitions compete without a clear product interpretation, the Knowledge System still contains a semantic readiness gap.

A failed validation should produce a concrete follow-up action. The team identifies whether the failure came from missing semantics, an inaccessible source, a competing definition, an unclear product mapping, stale temporal information, or missing authority. It then updates the current semantic source or routing mechanism, records any material decision under the correct authority, and repeats the test through the same human or AI access path. A semantic area passes when the unfamiliar participant reaches the intended current meaning without relying on private product history or an unsupported inference.

Back to top

9. Reference Knowledge-System Structures

Specification-First Delivery does not require a particular file layout. The semantic responsibility may be satisfied through OpenAPI, schema metadata, an external data catalog, a knowledge graph, governed documents, repository files, or a combination of sources. Repository-centered products can nevertheless use simple reference structures to make current Product Language and Data Semantics easy for humans and AI to discover.

A small product can keep the implementation deliberately compact. Product-wide vocabulary and aliases can live together, data semantics that are not already carried adequately by their authoritative interface can remain in one file, and material rationale can remain outside normal current-state context:

As semantic coverage grows, separate records become useful when concepts have different functional scope, owners, sources, or loading needs. A compact directory can route humans directly, while an optional Skill can give an AI coding agent a smaller first-step index and load only the semantics relevant to the current job:

The optional semantic-directory Skill is a navigator and maintenance aid. The authoritative meaning remains in the product semantic records or external contracts that own it. Governing Instructions establish when semantic checks are mandatory; the Skill helps an AI participant locate the right current meaning and propose maintenance work with less retrieval and clerical overhead. The product adopts the richer structure only when the semantic knowledge set creates a concrete discovery or maintenance need.

The strongest result is that a product term or external field carries enough current meaning for a newly qualified participant to use it correctly without inventing missing semantics. The implementation may remain compact while authority, consumer context, temporal relevance, and AI-readable access stay explicit.