Plugin manifest

A plugin is a versioned bundle that contributes to a fixed set of extension points: value-sets, dimensions, context kinds, types, conversions, nodes, agents, adapters, event sources, event bindings and port sandboxes. Its plugin.yaml is validated by the zod schema in libs/shared/src/plugin/manifest.ts. This page documents that schema field by field; it is the authoritative source for the manifest grammar. It does not cover authoring workflows — see the how-to guides linked from each section.

The manifest is browser-safe grammar only. The loading logic (filesystem discovery, dynamic import) lives in the API host (PluginHost); the manifest schema defines structure and validation, nothing else.

Top-level fields

contributes sections

Load order and resilience

The host applies contributions in a fixed order so that a symbol is always registered before anything that references it:

valueSets → contextKinds → dimensions → types → conversions → nodes → adapters → agents → eventSources → eventBindings → portSandboxes

An invalid manifest, or a node referencing an unknown type/value-set/dimension, is logged and skipped; the other contributions still load and a plugin never blocks startup. Plugins are discovered from a built-in directory plus every path in PLUGINS_PATH, or downloaded from a registry per the instance manifest's plugins: map. See Bundling and distribution and Publish to the registry.

Manifest skeleton

apiVersion: meridian/plugin-v1
name: "@scope/name"
version: 0.1.0
sdk: "^0.1.0"
locale: fr
dependsOn:
  "@posos/clinical": "*"
description: What this plugin does.
contributes:
  valueSets:     [ … ]
  dimensions:    [ … ]
  contextKinds:  [ … ]
  types:         [ … ]
  conversions:   [ … ]
  nodes:         [ … ]
  adapters:      [ … ]
  agents:        [ … ]
  eventSources:  [ … ]
  eventBindings: [ … ]
  portSandboxes: [ … ]

TypeRef

Field and port types are described with a recursive TypeRef. The variants accepted by the manifest schema:

For the full semantics and the TypeScript each variant generates, see the TypeRef reference.

contributes.valueSets

Terminologies backing coded types.

valueSets:
  - id: renal-stage
    system: urn:acme:renal-stage
    doc: KDIGO chronic-kidney-disease stage.
    concepts:
      - { code: G1, display: "G1 — normal or high (>= 90)" }
      - { code: G3a, display: "G3a", parent: G3 }
  - id: snomed-ct
    system: http://snomed.info/sct
    external: true
    concepts: []

See Add vocabulary and types.

contributes.dimensions

Backing for quantity types (UCUM-style unit checking).

dimensions:
  - name: filtration-rate
    label: Glomerular filtration rate
    canonical: "mL/min/{1.73_m2}"
    units:
      - { symbol: "mL/min/{1.73_m2}", toCanonical: 1 }

contributes.contextKinds

The kinds of ambient context a workflow can carry (context: in a workflow spec, context:/establishes: on nodes, keys of the ContextEnvelope). The registry (libs/shared/src/domain/context-kinds.ts) is open and starts empty: the core ships none; @posos/common contributes patient, encounter, order and document. A kind ties three axes together: the context key, the id field an external caller knows how to supply (what makes the kind composable by an incoming webhook or an out-of-workflow agent invocation), and the entity name of the associated ref TypeRef.

contextKinds:
  - { name: patient, idField: patientId, entity: Patient, description: The patient whose record is in context. }

Registering an already-registered kind is a collision and fails the contribution. Kinds contributed by the dependsOn closure are referenced by name from context:/establishes:. GET /api/catalog serves the registered kinds (contextKinds), and validateSpec checks a workflow's context: against the registry. The core trigger.webhook and trigger.workflow-called triggers declare establishes: "*" — opportunistic: every registered kind whose idField is present in the call becomes ambient context.

contributes.types

Datatypes and resources. Each field carries its own TypeRef.

FieldDescriptor:

types:
  - name: EgfrResult
    doc: Estimated GFR (value + equation + stage).
    layer: resource
    fields:
      value:    { type: { kind: quantity, dimension: filtration-rate }, required: true }
      equation: { type: { kind: primitive, name: String }, required: true }
      stage:    { type: { kind: coded, valueSet: renal-stage }, required: true }

Types owned by a dependsOn plugin are referenced by name and resolved across the dependency closure. See Generate types.

contributes.conversions

A declarative conversion powering the transform.convert node. expr is a JEXL expression evaluated over value (the input).

conversions:
  - from: CreatinineClearance
    to: Decimal
    label: Clearance -> number
    expr: value.value.value

contributes.nodes

A node declares typed ports and (optionally) points at a behavior factory module.

PortDef (inputs / outputs):

ConfigFieldDef (config):

A field whose values are known in advance should never be free text. Prefer a coded type bound to a value set you contribute — you get validation, display labels, i18n and the picker in one move — and fall back to options only for technical vocabularies that are not clinical terminology (a mode, a unit, an auth scheme). An external value set (SNOMED, via a terminology server) is not enumerable, so such a field stays free text.

behavior:

The behavior module exports a factory (ctx) => NodeBehavior. The method the interpreter calls depends on kind. For the full contract see the behavior contract reference and Implement a node behavior.

nodes:
  - id: acme.egfr.ckd-epi-2021
    kind: compute
    category: Labs & calculations
    label: eGFR (CKD-EPI 2021)
    description: Estimates glomerular filtration rate.
    context: []
    inputs:
      - { name: result, type: { kind: object, name: Observation }, required: true }
      - { name: demographics, type: { kind: object, name: Demographics }, required: true }
    outputs:
      - { name: egfr, type: { kind: object, name: EgfrResult } }
    behavior: { module: ./behaviors/egfr.ts, export: egfrCkdEpi2021 }

contributes.adapters

Binds an implementation to a hexagonal port. A factory (config) => PortImpl. The port bundle is fully open: any port name is addressable, and the port's contract lives with the plugin that owns it (the SDK types only agent and terminology — see Port contracts).

Adapters are selected by the deployment's instance manifest (e.g. ports.patient = { adapter: fhir, config }); a port that nothing selects does not exist. See Port contracts, Implement a port adapter and the instance manifest reference.

adapters:
  - { port: patient, name: fhir, module: ./adapters/patient.ts, record: { contextKind: patient } }
  - { port: terminology, name: hermes, module: ./adapters/hermes.ts, systems: [snomed-ct] }
  - { port: patient, name: in-memory, module: ./adapters/in-memory.ts, export: patient, record: { contextKind: patient } }

contributes.agents

An agent is projected into a node agent.<slug> whose ports are typed from its inputs and outputs.

AgentPort (inputs / outputs):

Backward compatibility: a scalar input: <TypeName> / output: <TypeName> is accepted and rewritten to a single named port (inputs: [{ name: "input", type: … }], outputs: [{ name: "output", type: … }]).

agents:
  - name: Renal triage
    provider: anthropic
    model: claude-sonnet-4-5
    inputs:  [ { name: observation, type: Observation } ]
    outputs: [ { name: condition,   type: Condition } ]
    maxIterations: 6
    tools: [patient.load-demographics, acme.egfr.ckd-epi-2021]
    prompt: |
      You are a nephrologist. From the creatinine result, estimate renal function
      (use the tools) and propose a Condition if warranted.

The agent runner is itself a port adapter (provided by a plugin such as @posos/llm). See Author an agent.

contributes.eventSources

A generic ingestion mechanism (polling, an HL7 socket…). It receives a connection config and a list of feeds (opaque queries) and emits raw records; it has no knowledge of domain events.

eventSources:
  - { name: fhir-poll, module: ./sources/poll.ts, description: Polls a FHIR server and emits raw resources. }

See Contribute an event source and binding and The open event model.

contributes.eventBindings

The declarative, reusable link between a source feed and a domain action. Any plugin may contribute bindings; the instance activates them and supplies connection config. A binding declares either event (start a run) or resolve (resolve a pending human validation) — exactly one of the two.

resolve:

Validation rule (zod refine): a binding must declare event xor resolve. Declaring both, or neither, is rejected.

eventBindings:
  - name: fhir-creatinine
    source: fhir-poll
    event: BioResultReceived
    query: { resource: Observation, params: { code: "http://loinc.org|2160-0" } }
    map:
      patientId:  { path: subject.reference, ref: true }
      analyte:    { const: creatinine }
      value:      valueQuantity.value
      loincCode:  { jsonpath: "$.code.coding[?(@.system=='http://loinc.org')].code" }

The deployment supplies only the connection config (and an optional binding allow-list) in its instance manifest. See Connect an event source.

MapExpr

The projection grammar used by map and by resolve. Its evaluation lives in the API host (JSONPath-based). Accepted forms:

Defined in libs/shared/src/plugin/mapping.ts. See the MapExpr reference for full semantics.

contributes.portSandboxes

A simulation sandbox for a port the plugin owns — the engine ships no business sandbox of its own. The module exports a factory (seed, record) => portImpl: reads are served from the seed (shape defined by the owning plugin, opaque to the engine), writes are captured through record(op, targetId, payload) (never applied to a real system) while staying re-readable (copy-on-write). A port with no contributed sandbox is simply absent in simulation — a behavior that needs it fails with the clear "Port « X » non branché" error, visible in the report.

portSandboxes:
  - { port: patient, module: ./simulation/sandbox.ts, export: patientSandbox }

@posos/clinical contributes the patient and prescription sandboxes, @posos/notify the notification one. Seeds are supplied per port name in POST /api/simulate (options.seeds), or read from a real record with options.subject: { kind, id } (the record port of that context kind seeds the corresponding port). See the simulation engine.

Related references

• TypeRef — the type grammar used across fields and ports.
• MapExpr — the binding projection grammar.
• Behavior contract — what a node behavior module exports.
• Port contracts — the interfaces adapters implement.
• SDK surface — the @meridian/shared sub-paths a plugin imports.
• CLI — meridian-plugin commands (gen-types, build, validate, publish, i18n).
• Instance manifest — how a deployment selects adapters, sources and bindings.
• Bundled plugins — real manifests to read.