Typed Map Composition

Purpose

Compose protocol instances as typed maps within a parent entity

Context

Protocol-driven frameworks where entities compose other protocol instances. The parent entity needs to reference child instances without inlining their full schema. The child instances are independently defined, validated, and potentially shared across multiple parents. The framework uses YAML as its data format with schema-level validation tooling.

Problem

How to compose independently-defined protocol instances into a parent entity
while maintaining type safety and normalization?

Forces:
(1) Protocol instances must be independently definable and validatable
(2) Parent entities must reference instances without duplicating schema
(3) Referenced instances must conform to a known protocol (type safety)
(4) The same instance may be shared across multiple parents
(5) The composition must be discoverable by tooling (not opaque strings)

Solution

Define a typed map property on the parent entity. The map key is the instance identity (name). The map value conforms to a specific protocol indicated by the `items_conform_to` meta-property. The framework's validation tooling resolves `items_conform_to` to verify that each map entry satisfies the referenced protocol's required properties.

The parent declares WHAT it composes (the map + conformance target). The child instances declare HOW they fulfill the protocol (their properties). Validation connects the two at schema check time.

Consequences

Benefits: - Full normalization: each protocol owns its schema, no duplication - Type safety: items_conform_to enables automated conformance checking - Composability: any entity can compose any protocol via typed maps - Shareability: same instance can appear in multiple parent maps - Discoverability: tooling can enumerate all compositions by scanning items_conform_to

Liabilities: - Indirection: reader must follow items_conform_to to understand map entry structure - Tooling dependency: without validation tooling, items_conform_to is just a comment - Resolution overhead: cross-referencing requires file system scanning - Naming discipline: map keys must match instance identity names exactly

Collaborations

ParentEntity declares a TypedMap property. TypedMap references ProtocolTarget via items_conform_to meta-property. At instantiation time, each InstanceEntry is keyed by identity name in the TypedMap. At validation time, the framework resolves items_conform_to to the ProtocolTarget and validates each InstanceEntry against the target protocol's required properties.

Structure

Participants:
- ParentEntity: Entity protocol with a typed map property
- TypedMap: Map property with items_conform_to meta-property
- ProtocolTarget: The protocol that map entries must conform to
- InstanceEntry: A map entry that satisfies the protocol target

Relationships:
- ParentEntity contains TypedMap (ownership)
- TypedMap references ProtocolTarget via items_conform_to (conformance)
- InstanceEntry satisfies ProtocolTarget (conformance)
- InstanceEntry is keyed by identity name in TypedMap (identity)

YAML Structure:
  # In parent protocol (e.g., entity.yml)
  patterns:
    type: map
    items_conform_to: pattern    # ← typed map composition
    purpose: Architecture patterns informing this entity

  # In parent instance (e.g., my-entity.yml)
  patterns:
    typed-map-composition:       # ← key = pattern instance name
      description: Used for protocol composition

Implementation

In YAML protocol definitions:
  1. Add a map property with items_conform_to set to the target protocol name
  2. Set type: map and required: true/false as appropriate
  3. Document in governance what kind of entries are expected

In Go validation:
  1. Parse items_conform_to from the parent protocol
  2. Load the target protocol definition from .framework/protocols/{name}.yml
  3. For each map entry, validate against target protocol's required schema properties
  4. Return typed validation results with entry-level detail

In CLI tooling:
  1. `sbx protocol validate <instance>` resolves typed maps automatically
  2. `sbx entity list --has-pattern <name>` queries across typed maps

Example

Consider an entity protocol that needs to reference architecture patterns. The entity has a `patterns` field, but the patterns themselves are defined as separate protocol instances (pattern.yml). A simple string list loses type safety — there's no way to validate that referenced patterns actually conform to the pattern protocol. A nested inline definition duplicates the pattern protocol schema inside the entity protocol, violating normalization. We need a way to reference external protocol instances with type validation.

Resolution

The entity protocol declares `patterns: { type: map, items_conform_to: pattern }`.
When an entity instance lists patterns, each entry is validated against pattern.yml's
required properties (example, context, problem, solution, consequences). The entity
author gets type safety without the entity protocol duplicating pattern.yml's schema.
The same pattern instance ("typed-map-composition") can appear in multiple entities'
pattern maps. Validation tooling resolves the cross-reference automatically.

Known Uses

SBX .framework entity.yml — patterns and standards maps (Decision #0007)
SBX .framework process.yml — activities map with items_conform_to: activity (Decision #0011)
OpenAPI 3.0 — components/schemas with $ref cross-referencing
JSON Schema — definitions/$defs with $ref resolution
MOF/UML — Package::ownedElement with typed containment

Tags

Overview