TypeRef

TypeRef is the discriminated union that describes the type of every node port and every object field in Meridian. It is defined in libs/shared/src/domain/types.ts and re-exported to plugins from @meridian/shared/domain/types. A TypeRef value is pure data (JSON-serializable) — the same descriptor is written in a plugin's plugin.yaml, carried at runtime on PortDef/ConfigFieldDef/FieldDescriptor, projected to TypeScript by codegen, and consumed by the static-validation and runtime-validation engines.

The union

export type TypeRef =
  | { kind: "primitive"; name: PrimitiveName }
  | { kind: "coded"; valueSet: string }
  | { kind: "quantity"; dimension?: Dimension }
  | { kind: "ref"; entity: string }
  | { kind: "object"; name: string }
  | { kind: "list"; of: TypeRef }
  | { kind: "any" };

list is the only recursive case (of: TypeRef); every other kind is a leaf. Dimension is the closed string union from libs/shared/src/domain/dimensions.ts.

The vocabulary is layered, per the module's header comment:

any and list sit outside the layering: any is a wildcard (see Structural assignability); list wraps any other TypeRef, including another list.

Kinds

Primitive names

PrimitiveName is a closed, FHIR-aligned enum — the only kind with no backing registry:

Codegen looks the name up in a fixed PRIMITIVE_TS map (libs/plugin-cli/src/codegen.ts); every PrimitiveName has an entry, so the map's ?? "unknown" fallback is never exercised in practice.

Construction helpers — the t namespace

domain/types.ts exports a t object of ready-made TypeRef values and factories, used throughout the core catalogue (engine/catalog-metadata.ts) and available to plugin code:

Human-readable labels — typeLabel

typeLabel(type: TypeRef): string (domain/types.ts) renders a TypeRef for logs, error messages, and the catalogue UX:

Structural assignability — isAssignable

isAssignable(from: TypeRef, to: TypeRef): boolean (libs/shared/src/engine/type-system.ts) decides whether a connection's source output type (from) may feed a target input type (to). It is evaluated in this order:

1. any wildcard. If either from.kind or to.kind is any, the connection is allowed.
2. coded → primitive widening. A coded output may feed a primitive input only if the target is Code or String.
3. Otherwise from.kind must equal to.kind; the rule then depends on the kind:

Runtime validation — validateValue

validateValue(type: TypeRef, value: unknown): { ok: boolean; error?: string } (engine/type-system.ts) checks a concrete value against a TypeRef at port boundaries (trigger payload → outputs, node outputs → downstream inputs). The per-kind checks are listed in Kinds and Primitive names above; list and object recurse and report the first failing element/field (élément [i] : …, TypeName.field : …).

Example values — exampleValue

exampleValue(type: TypeRef): unknown (engine/type-system.ts) produces a deterministic value conforming to a TypeRef, used by the mock agent runner and default-value generation:

YAML encoding (plugin manifest)

plugin.yaml encodes TypeRef values with the exact same shape, validated by the recursive TypeRefSchema (Zod) in libs/shared/src/plugin/manifest.ts:

const TypeRefSchema: z.ZodType = z.lazy(() =>
  z.union([
    z.object({ kind: z.literal("primitive"), name: PrimitiveName }),
    z.object({ kind: z.literal("coded"), valueSet: z.string() }),
    z.object({ kind: z.literal("quantity"), dimension: z.string().optional() }),
    z.object({ kind: z.literal("ref"), entity: z.enum(["Patient", "Encounter", "Order", "Document"]) }),
    z.object({ kind: z.literal("object"), name: z.string() }),
    z.object({ kind: z.literal("list"), of: TypeRefSchema }),
    z.object({ kind: z.literal("any") }),
  ]),
);

One asymmetry: the manifest schema types quantity.dimension as a bare z.string().optional(), while the internal TypeRef types it as the closed Dimension union. A manifest is free to name any dimension string; it only becomes meaningful once that name resolves in the DIMENSIONS registry (see below).

TypeRef values appear in a manifest wherever a type field is expected: contributes.types[].fields[].type, contributes.nodes[].inputs[].type / outputs[].type, and contributes.nodes[].config[].type. The host applies a fixed contribution order — value-sets → dimensions → types → conversions → nodes → adapters → agents → eventSources → eventBindings — so any coded/quantity/object reference inside a types or nodes contribution resolves against a registry already populated earlier in the same load pass. See Plugin manifest.

Backing registries

coded, quantity, object, and ref resolve names against open, in-memory registries. All of them are populated by plugins at load time; none is exposed for direct mutation outside their registration function.

The Dimension TS union additionally lists filtration-rate, which is not among the core-seeded entries: it is declared in the shared vocabulary but only becomes usable once something (typically a clinical plugin) calls registerDimension("filtration-rate", …).

getType/hasValueSet/dimensionOfUnit (and friends) are the read-side accessors isAssignable, validateValue, and exampleValue use to resolve a TypeRef against these registries. See Type-system registries and Add vocabulary and types.

Ambient context (same module)

domain/types.ts also defines ContextKey (an open string — a context-kind name) and ContextEnvelope (Record<string, { id: string } | undefined>, one key per established kind) — the ambient context a workflow run carries, distinct from TypeRef's ref kind (which types a single port value, not the run's context). Node metadata references ContextKey in its context/establishes fields. See Workflow DSL and Core primitives.

Related

• Plugin manifest — the full plugin.yaml schema, including where TypeRef appears.
• Generate types and Codegen internals — how TypeRef is projected to TypeScript.
• Add vocabulary and types — contributing value-sets, dimensions, and types from a plugin.
• Type-system registries — OBJECT_TYPES, VALUE_SETS, DIMENSIONS, CONTEXT_KINDS in depth.
• Static validation engine — how isAssignable is used to check a whole workflow.
• The type system — the conceptual model behind the layered vocabulary.
• Port contracts — how TypeRef shows up on PortDef/ConfigFieldDef.
• MapExpr — the separate grammar for projecting raw records into typed event fields.