Documents, types, and BlueId

Begin with the smallest document#

A Blue document is the root node of a serialized graph slice. It may be a scalar, list, object, or a pure { blueId: ... } reference. There is no required wrapper called document above it.

name: Vet Order
customer: Maya
provider: Riverside Vet
status: Draft

This document has no executable contracts yet. It is already valid content that can be typed, resolved, validated, and given semantic identity.

A document is a graph slice#

Ordinary child fields, list items, type links, and pure BlueId references are graph edges. A serialized file does not need to contain every node it depends on. A canonical type or policy may be represented by a pure reference and materialized only when required.

A pure reference contains exactly one field:

blueId: <exact-content-address>

Siblings are forbidden because they would make it ambiguous whether the extra fields describe, override, or extend the referenced node.

Types are content#

Any Blue node can serve as a type. An instance overlays its type chain. Types can define fields, fixed values, schemas, nested types, contracts, and semantic descriptions.

A valid subtype preserves ancestor promises while becoming more specific. A descendant may require a previously optional field or narrow a constraint. It cannot contradict a fixed ancestor value or weaken required meaning.

BlueId is semantic identity, not a hash of YAML bytes#

The identity pipeline is:

Source Document
→ deterministic preprocessing
→ type and reference resolution
→ validation
→ canonical identity input
→ BlueId

Equivalent source forms can converge on the same content identity. Exact text, numeric type, effective type, and identity-bearing descriptions remain significant.

What BlueId proves#

A verified BlueId can establish that materialized content matches the requested exact content, that a type or policy was not silently substituted, and that expanded or collapsed views preserve the same node when processed correctly.

What BlueId does not prove#

BlueId alone does not establish authorship, approval, freshness, actor identity, provider authority, external truth, Mandate state, money movement, or availability. Those questions belong to other evidence layers.

Names and BlueIds serve different audiences#

Names help humans. BlueIds establish exact semantic dependencies across organizations and implementations. A UI should show friendly names by default and make exact identities accessible in an audit or developer view.