Product Language and Data Semantics

Every software product relies on words and data whose meaning is more specific than their names suggest. A field called country may mean legal employment country, residence, nationality, or the jurisdiction used for a calculation. An organizational term may have one enterprise definition while a product uses a narrower interpretation. A system may expose one hundred employee fields while holding business authority for only some of them.

Product Language defines the concepts, conventions, and source roles through which the product is understood. Data semantics define what structured data from an internal or external source represents. The two knowledge areas connect when a data value establishes, qualifies, or routes a Product Language concept, but they carry different responsibilities. This gives qualified humans and AI coding agents a reliable basis for specifications, implementation, verification, review, and operations.

Specification-First Delivery treats Product Language and Data Semantics as durable product context within the Shared Knowledge System. The required outcome is current meaning that participants can discover through their normal access path before they rely on a term or data dependency.

Zoom out

100%

Zoom inReset zoom and position

Back to top

1. Product Language and Ownership

Product Language is the current vocabulary through which participants interpret product concepts consistently. It includes terms that name users, business facts, states, responsibilities, workflows, categories, and other concepts whose meaning can affect delivery. A glossary is a practical representation: a qualified participant can 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 can make its vocabulary, relationships, and constraints explicit. Gruber defines an ontology as a specification of a representational vocabulary for a shared domain of discourse, enabling formally represented knowledge to be shared across AI systems.² Product Language usually needs a lighter representation. It still makes material concepts, meanings, relationships, and constraints explicit wherever ordinary language permits more than one delivery-relevant interpretation.

Specification-First Delivery separates organizational context from product context. An organization may maintain enterprise definitions in a glossary, knowledge graph, data catalog, internal portal, or another governed source. A product can adopt a definition that fits its consumer context or record the interpretation it needs while preserving a route to the organizational source.

Product Language has an explicit ownership and maintenance lifecycle. Each glossary entry identifies one or more owning functions, and those owners establish its current meaning, review a material change, and resolve a question that delivery cannot answer from the existing record. Common ownership patterns include:

• Product-owned language: The Product Owner or equivalent product authority owns terms that define product purpose, user-visible outcomes, product conventions, and the product-specific role of an external system.

• Domain-owned language: A domain owner owns business concepts, classifications, policies, and distinctions that depend on domain judgment.

• Shared delivery language: When a term governs decisions across product, domain, data, architecture, engineering, quality, or operations, the accountable functions level-set the meaning and reach the consensus appropriate to that shared responsibility.

• User-calibrated language: When the product must use a term as its users understand it, the Product Owner level-sets the meaning with representative users and the engineering team before the term becomes current product language.

The owner tag remains with the glossary entry so that a human or AI participant can route a proposed change to the right functions. A participant who discovers an ambiguity can prepare evidence and draft a proposal; the listed owners decide the meaning that becomes current product knowledge. As Product Language grows, a team can separate entries into focused Markdown files or documents by owner or domain. The glossary remains the discovery path, while the focused records carry the current meaning and ownership for their area.

For example, a payroll user interface can define a system called "HR Go" as its payroll-data source, and LDAP as its employee-data source. HR Go may also expose employee information, but that does not make it the source that this product uses for employee data. Those product-specific source roles belong in Product Language and are related to the canonical-consumption decisions described later in this paper.

Back to top

2. Internal and External Data Semantics

Data semantics establish the meaning of structured data beyond what source code, a database schema, type declaration, or field name can express. They identify the real-world fact, state, or condition represented by a structure, field, value, or relationship, together with any material representation, lifecycle, validity, or compatibility condition. Code, schemas, constraints, and tests can express and enforce part of this knowledge, but a maintained semantic source lets a human or AI participant discover and apply the meaning without reverse-engineering it from implementation evidence.

Internal and external data semantics have different source authorities:

The meaning supplied by an internal or external source describes that source's model. Product Language records the product concept, convention, or source role that the data supports. Kashyap and Sheth describe semantic proximity between database objects relative to a context of comparison, making context part of how semantic similarity and schema correspondence are understood.³ Context Interchange likewise treats source and receiver contexts as material to semantic interpretation across heterogeneous systems.⁴

Consider the payroll user interface. LDAP returns a group-membership structure and a company value for an employee. Its data semantics can establish that membership in Payroll-Externally-Managed indicates that the employee's payroll is administered by an external vendor. In that condition, the company value is a controlled payroll-vendor identifier, not a generic employer-company name. The Payroll UI uses the identifier to select an approved vendor payroll destination and presents a link to that system. The vendor system authenticates the user through its B2B Entra connection.

Here, externally managed payroll employee and payroll vendor are Product Language concepts. The LDAP group and company field are structured data whose semantics establish when the first concept applies and which vendor the product should use.

The example also shows why consumer context is part of correct interpretation. The group and field values matter to this product because they determine its payroll path, not merely because LDAP makes them available. Wang and Strong identify contextual data quality as the appropriateness of data for the task performed by its consumer.⁵ Product Language records that payroll context, while Data Semantics state the meaning of the structured values used within it.

The B2B Entra connection, vendor destination, and link behavior are architecture, interface, and security concerns. This paper records their relevance to meaning without defining their technical configuration.

An external source remains authoritative for its own structure and values. The product retrieves those semantics through provider documentation, an API contract, schema metadata, a data catalog, an MCP interface, or another supported route. The product then relates a data-semantic record to Product Language whenever structured data establishes a product concept, source role, or decision.

Legacy external platforms can require a different operating pattern. When authoritative source semantics are inaccessible, incomplete, or impractical to retrieve during delivery, the product can internalize a governed external-data record. That record preserves the available provenance, identifies its owners, and states the limitation that required internalization. A legacy platform may change slowly, but an integration change, revised provider contract, or new product use still triggers reassessment of the local interpretation.

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 provides a mature example of this principle for HTTP APIs. It defines a language-agnostic interface description that lets people and software discover and understand service capabilities, and supports structured models alongside descriptive fields and examples.¹ Specification-First Delivery applies the underlying principle to the external information that materially affects a product without requiring OpenAPI or a particular documentation technology.

For example, an LDAP response might contain:

memberOf: Payroll-Externally-Managed
company: Alder Payroll Services

communicates values while leaving product use unresolved. Data semantics establish that the group membership signals externally managed payroll and that company identifies a payroll vendor in this condition. Product Language defines the corresponding product concepts, including the payroll vendor and externally managed employee. A timestamp likewise needs to identify whether it represents event time, effective time, processing time, record-update time, or another lifecycle point that affects product behavior.

Wand and Wang describe data-quality problems as possible failures in how an information system represents a real-world system, including ambiguity and lack of meaningfulness.⁶ A structurally valid field therefore remains inadequate for delivery when a participant cannot tell which fact, state, unit, or lifecycle point it represents.

Back to top

3.1. Semantic Interfaces for External Systems

External information that materially affects delivery needs an understandable semantic interface. 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 record.

• 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 consumer context.

Research on AI tool use reinforces the value of accessible source information. Gorilla reports that retrieval of API documentation improves adaptation to changed documentation and mitigates hallucinated API use; ToolLLM uses retrieval to select among 16,464 real-world REST APIs.⁷⁸ Correctly finding and invoking an interface remains only one part of delivery. The participant must also apply the current product meaning and route an unresolved semantic question to the owners who can decide it.

The semantic interface must be reachable through the access path that participants actually use. The Knowledge System Readiness for Specification-First Delivery paper requires relevant knowledge to be both reachable and authoritative for the responsibility being performed. Human access to a provider portal does not establish that an AI coding agent can retrieve the same source, and AI retrieval alone does not establish which product interpretation governs a decision.

Back to top

4. Data Authority, Canonicality, and Provenance

Semantic-record ownership, business authority, and canonical consumption are related but separate. Semantic-record owners maintain the record and make the decisions assigned to their functions. Business authority establishes an underlying fact or decision in a defined context. Canonical consumption identifies the interface from which this product should obtain that fact. Provenance records the origin or material transformation path needed to interpret the consumed value responsibly.

Suppose a service exposes one hundred employee fields. Twenty are maintained by the service's owning domain, while eighty arrive through ETL from other systems. The service can still be the canonical consumption interface for all one hundred fields, while business authority for many of those facts remains elsewhere. Canonicality is therefore a designation for a defined fact in a defined consumer 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.⁹ Data-semantic records give an engineer or AI participant an agreed basis for transformations that rely on a canonical representation or distinguish provider values with different business meanings.

Back to top

5. Establishing and Maintaining Current Meaning

Establish Product Language and Data Semantics from the terminology and information that current delivery depends on. A usable baseline focuses on active decisions and grows when later work exposes additional ambiguity or semantic responsibility.

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 and reachable. If an organizational glossary already defines a term as the product uses it, the product can adopt the definition and retain its route to the source. If an API contract communicates a data structure adequately, the product can reference that contract. A focused data-semantic record becomes useful when the product needs to explain a field or value, its relationship to a Product Language term, a representation, or a canonical consumption decision.

When any participant encounters an ambiguity that can alter intended behavior, the ambiguity is a readiness gap. It is routed to the listed product, domain, data, or specialist owners before dependent work relies on an invented answer. Subsequent increments extend the semantic baseline when they introduce or expose additional concepts.

Semantic records are current-state knowledge. A revision is required when a future participant needs a materially different meaning, source relationship, ownership arrangement, or use condition. The affected owners review the impact on specifications, interfaces, implementation, tests, analytics, operational procedures, and downstream consumers. A completed semantic revision updates the current record and every dependent product surface that must express the approved meaning; material rationale can remain available through decision history.

Back to top

6. Optional Semantic-Record Working Patterns

Specification-First Delivery does not require a particular file layout, YAML header, Skill, or repository-centered Knowledge System. The semantic responsibility can be satisfied through OpenAPI, schema metadata, an external data catalog, a knowledge graph, governed documents, repository files, or a combination of sources. The following reference patterns can make current semantics easy for humans and AI to discover.

A small product can stay compact. Its glossary records Product Language, while one data-semantics document records the material data meaning that is not already available adequately through an authoritative interface:

As coverage grows, a product can separate records by data-semantic kind, owner, source, or loading need. Each focused Markdown record can use a small YAML header that makes its identity, kind, and owners discoverable without forcing generic fields that do not apply:

---
id: ldap-payroll-routing
kind: external-data
owners:
  - identity-data-owner
  - payroll-domain-owner
---

# LDAP payroll routing

`Payroll-Externally-Managed` in `memberOf` establishes that an employee's payroll is externally managed. When this membership is present, `company` identifies the payroll vendor for the product's approved vendor destination.

The record body describes the semantics that matter for that concept. In this example, it establishes the Product Language concept externally managed payroll employee and identifies the vendor destination in that condition. A record may also link to a provider source, name a representation, or state a legacy limitation when the task requires that information. The pattern leaves irrelevant details absent instead of using N/A placeholders merely to conform to a template.

A team that adopts this working pattern can use its root AGENTS.md to require contributors and AI coding agents to invoke a semantic-record Skill for relevant changes. The Skill identifies the applicable record type, locates the authoritative source, and prepares a supported update in the appropriate location. It routes missing evidence and material semantic changes to the listed owners. The Skill supports accountable maintenance; it does not create authority to infer a definition or approve a semantic decision.

Back to top

7. 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 receives a representative product term or data dependency and interprets 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 owners and source details needed for the task, and route unresolved questions correctly. The AI version of the test uses the actual context path available to the delivery tool. If required meaning exists but the AI cannot reach it, or if several retrievable definitions compete without a clear product interpretation, the Knowledge System contains a semantic readiness gap.

A failed validation produces a concrete follow-up action. The team identifies whether the cause is missing semantics, an inaccessible source, a competing definition, an unclear mapping, stale information, or missing ownership. It updates the current semantic source or routing mechanism, records any material decision with the correct owners, and repeats the test through the same human or AI access path.