Primitive

Origin & evolution

The word primitive entered computer science through programming language theory, where primitive types (integers, booleans, characters) are the atoms the language defines directly, as opposed to compound types the programmer composes from them. The distinction between a primitive and a composite shows up everywhere a type system exists: in SQL (VARCHAR, INTEGER vs. a table row), in JSON Schema (string, number vs. an object), and in every API contract🤝API ContractEngineeringAn API contract or specificationView reference → that names its first-class objects.

At the application layer, the idea carries forward into protocol design. REST popularised the resource as the first-class noun an API exposes. Event-driven architectures name their events as the atoms that flow between services. Domain-Driven Design calls them value objects💎Value ObjectEngineeringA DDD value objectView reference → and entities. In every case the underlying insight🔦InsightUser ResearchA synthesised finding from researchView reference → is the same: name the atoms before you name the operations, because the atoms are what interoperability is built on.

In UPG the primitive entity was introduced alongside specification to close a modelling gap. Before it, a product that implemented GROQ had a feature⭐FeatureProduct SpecificationA product capability or featureView reference → node for GROQ support, but there was no way to represent the GROQ expression, operator, or result type as a named thing that multiple features across multiple products pass around. The primitive entity names those atoms, links them to their governing specification, and makes their composition explicit in the graph.

How it works in practice

A content platform builds three features that all operate on Portable Text: a rich-text editor, a plain-text export utility, and a search indexer. Without primitive nodes, each feature node implicitly assumes a shared understanding of what a "block" and a "span" are, but that understanding is nowhere in the graph. Two teams can drift on the schema without the graph revealing the inconsistency.

With primitive nodes, the team creates block, span, and mark nodes linked to the Portable Text specification via primitive_defined_by_specificationPrimitivedefined bySpecificationsemantic. Composition is modelled via primitive_composes_primitivePrimitivecomposesPrimitivehierarchy (block contains span, block contains mark). Each of the three features declares which primitives it consumes. A graph query for "all features that operate on the span primitive" returns all three, surfacing the shared dependency⛓️DependencyTeam & OrganisationA cross-team or system dependencyView reference → that was previously invisible.

Primitive vs. its neighbours

• Specification. The specification is the contract; the primitive is the atom the contract defines. Portable Text is the specification; a block is a primitive. A primitive links back to its specification via primitive_defined_by_specification. A primitive may exist without a governing specification if it is an internal platform primitive.
• Feature. A feature is something a team ships. A primitive is something a specification defines. A feature may operate on or produce a primitive, but the primitive exists independently of whether any one product ships support for it.
• Data model🗃️Data ModelData & AnalyticsA data model or schemaView reference → / schema. A data model or database schema🗄️Database SchemaEngineeringA database schema definitionView reference → is an internal design artefact for how a product stores data. A primitive is an externally-defined atom that a specification names and that products exchange across boundaries. The Stripe PaymentIntent is a primitive of the Stripe API; an internal payments table is not.

In the graph

In the Unified Product Graph a primitive is a lifecycle-free entity in the Foundations domain, modelled after the same pattern as metric🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference →: it exists or it is deprecated; there is no draft-active-shipped progression. Its primary edge is primitive_defined_by_specificationPrimitivedefined bySpecificationsemantic, which links the atom to its governing contract. Composition is modelled via primitive_composes_primitivePrimitivecomposesPrimitivehierarchy, allowing the graph to represent nested or container structures (a block contains spans). Like specification, a primitive is registry-hostable: one canonical block node can be shared by every product that implements Portable Text, rather than each product inventing its own representation.

The primitive_kind field classifies the atom: data_type for scalars and structured types, object for named record types, block for container units, and unit for indivisible atoms. A primitive that belongs to no governing specification is still valid — it represents an internal platform primitive that the team has named but not (yet) standardised.