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 canonical reusable building block defined by a specificationView reference →.

How it works in practice

A platform team ships three products that each implement GROQ as a query surface🪟SurfaceExperience DesignA place inside a screen, the features that occupy it, and the rule that decides who wins itView reference →. 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. A single update touches one node, and a query for every product claiming GROQ resolves against one shared entity instead of a string repeated per product. Competitive relationships link via specification_competes_with_specificationSpecificationcompetes withSpecificationsemantic, making the landscape visible without polluting any product node. The conformance claim has a typed edge of its own: each of the three products records its claim with product_implements_specification, a portfolio🧸PortfolioPortfolioA grouping of products by strategic axisView reference →-native cross-product edge that has existed since 0.9.12 and points at the one canonical node in the registry.

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. Within the edge catalog, what points at it is narrower than most readers expect: primitive_defined_by_specificationPrimitivedefined bySpecificationsemantic and operating_lifecycle_defined_by_specificationOperating Lifecycledefined bySpecificationsemantic anchor the things a spec defines, and specification_governed_by_organizationSpecificationgoverned byOrganizationsemantic names the body that stewards it. Dialect relationships are captured via specification_extends_specificationSpecificationextendsSpecificationhierarchy (GFM extends CommonMark) and competitive tension via specification_competes_with_specificationSpecificationcompetes withSpecificationsemantic. Conformance is typed as well, and this is the point at which a catalog-only reading goes wrong. product_implements_specification, product_exposes_specification and feature_conforms_to_specification have all existed since 0.9.12. They are absent from the within-graph catalog because they belong to the portfolio-native cross-product tier, where a product links to the canonical spec at registry/{node_id}, exactly as instance_of does. Nothing in the catalog points from a product or a feature at a specification, and that is deliberate rather than missing: a governed specification is a registry canonical, so conformance is a relationship that crosses graphs by construction. One case does still lack a typed edge, and it is worth naming rather than glossing. A specification held inside a single product graph, with no portfolio around it, has no conformance edge available, because the cross-only tier needs🫀NeedUserA user need, pain, desire, or constraintView reference → a registry target. There a claim can ride the universal node_constrains_node, which is honest and unqueryable as conformance. The specification lifecycle runs draft to active to deprecated to superseded, keeping version history explicit rather than implied by a field on a product feature.