Specification

Origin & evolution

The idea of separating a specification from its implementations is as old as standards bodies. The IETF has published RFC documents since 1969, treating the document as the normative contract and the software as the thing that claims conformance. The W3C formalised the same pattern for the web: HTML, CSS, and XML are specifications; browsers and editors are implementations. The spec outlives any one implementation, and any number of implementations can independently claim conformance.

In modern product ecosystems the pattern reappears at the application layer. OpenAPI describes REST APIs; GraphQL is stewarded by the GraphQL Foundation; OAuth 2.0 and OpenID Connect are ratified by the IETF. The identity providers and relying parties that implement them are the products — the specifications belong to no one product.

What distinguishes a specification in UPG from a feature⭐FeatureProduct SpecificationA product capability or featureView reference → is governance and reuse. A feature is a capability💪CapabilityStrategyAn ability that enables value deliveryView reference → a product team owns and can change on their roadmap🛣️RoadmapProduct SpecificationA strategic plan of features and milestonesView reference →. A specification is a contract that many products point to, and changing it requires a process separate from any one product's release🚢ReleaseProduct SpecificationA shipped version of the productView reference → cycle. The governance field carries whether the contract was ratified by a formal standards body, reached de-facto status through wide adoption, or exists only inside one organisation as an internal primitive📋PrimitiveFoundationsA primitive entityView reference →.

How it works in practice

A platform team ships three products that each implement GROQ as a query surface. Without the specification entity, each product carries a feature node like "GROQ query support" with no shared identity. When the GROQ spec updates, the team must find all three feature nodes and update them independently. Worse, no one can query the graph to ask which products conform to GROQ, because there is no single node to ask about.

With the specification entity, the team creates one canonical GROQ node in the registry. Each product links to it via product_implements_specification or product_exposes_specification. A single update touches one node. A query for all products conforming to GROQ resolves instantly. Competitive relationships link via specification_competes_with_specificationSpecificationcompetes withSpecificationsemantic, making the landscape visible without polluting any product node.

Specification vs. its neighbours

• Feature. A feature is something a product team owns, builds, and ships. A specification is a contract outside any one product that teams conform to. A product can have a feature that implements a spec — the feature is the work; the spec is the contract the work satisfies.
• Library dependency📚Library DependencyEngineeringA third-party library dependencyView reference →. A library dependency is a software package you import; a specification is a contract you implement. You can depend on a parser library that itself implements a spec without your product directly claiming conformance.
• Primitive. A primitive is the foundational unit a specification defines: the noun products pass around. A specification is the contract; its primitives are the atoms. Portable Text is the specification; a block, a span, and a mark are the primitives it defines.

In the graph

In the Unified Product Graph a specification is a registry-hostable canonical entity in the Foundations domain. Product nodes link to it via product_implements_specification or product_exposes_specification; individual features link via feature_conforms_to_specification when only a capability slice claims conformance. Dialect relationships are captured via specification_extends_specificationSpecificationextendsSpecificationhierarchy (GFM extends CommonMark) and competitive tension via specification_competes_with_specificationSpecificationcompetes withSpecificationsemantic. The specification lifecycle runs draft → active → deprecated → superseded, keeping version history explicit rather than implied by a field on a product feature.