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: "record"; name: string; fields: Record<string, { type: TypeRef; required?: boolean }> }
  | { kind: "list"; of: TypeRef }
  | { kind: "any" };

list and record are recursive cases. Dimension is a string, the name of a dimension of the DIMENSIONS registry (libs/shared/src/domain/dimensions.ts), contributed by a plugin.

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.

Date and DateTime formats

Date and DateTime are the only string primitives whose content is checked. Time, Duration, Code and Uri accept any string. The two predicates are exported from @meridian/shared/engine/type-system so plugin code can check a value before emitting it:

The DateTime grammar is the FHIR dateTime grammar, because FHIR adapters read and write these values as dateTime elements (effectiveDateTime, onsetDateTime, authoredOn, Communication.sent). Consequences:

• Reduced precisions are accepted. 2026 and 2026-06 are valid FHIR dateTime values, and clinical data carries them (a condition onset known only by year). A consumer that needs an instant reads the start of the period: Date.parse("2026") is 2026-01-01T00:00:00Z.
• A time requires seconds and an offset. Without an offset, Date.parse reads the time in the host's local time zone, so the same string would mean different instants on different servers; FHIR also requires the offset.
• Date.parse alone is not the rule. It accepts 1, May 11, 2026 and 01/05/2026 (read as January 5), and rolls 2026-02-30 over to March 2.

Date is stricter than FHIR date, which also allows YYYY and YYYY-MM: a Date value is always a full calendar day. Every valid Date is therefore also a valid DateTime.

A producer with no date to report emits nothing on the port (the key is absent from the returned outputs): absence propagates downstream, whereas "" fails the check. A source date in another format (HL7 v2 TS/DTM, dd/mm/yyyy) is converted before it is emitted.

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:

Homonyms — distinctTypeLabel

Two distinct types can share a typeLabel: the core quantity kind and an object type registered as Quantity (by @posos/common), a primitive and an object type of the same name, a workflow record and a registered type. The labels written for a reader then carry the type's origin, read from the registries (libs/shared/src/engine/type-system.ts):

The connection check of validateSpec, the memory read and write messages, the editor's refused-connection message and the assistant's catalog digest use these labels:

Connexion trigger.result.value → b.value : type incompatible (Quantity (type du cœur) → Quantity (@posos/common)).

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 : …). A Date/DateTime string outside its format gets an error naming the expected format and the received value, truncated to 40 characters: attendu DateTime ISO 8601 (ex. 2026-06-11T08:30:00Z, 2026-06-11T08:30:00+02:00 ou 2026-06-11), reçu « 20260611083000 ».

The same function checks every boundary, so the date formats apply to all of them:

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.string().min(1) }),
    z.object({ kind: z.literal("object"), name: z.string() }),
    z.object({ kind: z.literal("record"), name: z.string().min(1), fields: z.record(z.object({ type: TypeRefSchema, required: z.boolean().optional() })) }),
    z.object({ kind: z.literal("list"), of: TypeRefSchema }),
    z.object({ kind: z.literal("any") }),
  ]),
);

A manifest names a dimension by a string (quantity.dimension, z.string().optional()), like the internal TypeRef. The name only becomes meaningful once it resolves in the DIMENSIONS registry (see below). At load, a declared event field or a node port on a dimension outside the plugin's dependsOn closure is dropped. At runtime, a value on a dimension that is not registered is refused with « dimension « X » inconnue. Charger le plugin qui la contribue. »

TypeRef values appear in a manifest wherever a type field is expected: contributes.types[].fields[].type, contributes.events[].fields[].type (a type name, resolved like a type hint, or a full TypeRef), contributes.nodes[].inputs[].type / outputs[].type, and contributes.nodes[].config[].type. The host applies a fixed contribution order — value-sets → context kinds → dimensions → types → conversions → events → nodes → adapters → agents → event sources → message bindings → event bindings → port sandboxes — so any coded/quantity/object reference inside a types, events or nodes contribution resolves against a registry already populated earlier in the same load pass. An event's field types, like its context kinds, must resolve in the plugin's dependsOn closure, and so must the dimensions of an event field or a node port. See Plugin manifest.

Backing registries

coded, quantity, object, and ref resolve names against open, in-memory registries. A record carries its field descriptors inline and needs no registry. The registries are populated by plugins at load time; none is exposed for direct mutation outside its registration function.

A plugin whose ports use a dimension of another plugin declares that plugin in its dependsOn, so it loads after it: a port typed { kind: quantity, dimension: mass } needs @posos/common.

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.