Component Manifest Schema

Every SDK component declares itself to the platform through a JSON manifest packaged with the component. The platform reads the manifest at load time, registers the component, and renders its setup form and operational dashboard directly from the manifest. No frontend code is written, shipped, or installed for a new component.

This page documents the JSON contract: the top-level structure, the JSON Schema body that defines the configuration form, and the full set of x- extension keys the platform interprets.

Manifest format is evolving

The Component Manifest contract is still maturing as the plugin surface area grows. Field names, accepted values, and x- extension keys may change between releases, sometimes in ways that require plugin authors to update their manifests. To stay ahead of breakage: pin the SDK version your plugins build against, watch each release's migration note for manifest changes, and treat any net-new field documented here as potentially unavailable on older platform versions.

Schema-Driven Architecture

The platform is split across three responsibilities, all of which agree on the manifest as the contract.

Responsibility	What it owns
Plugin component	Authors the manifest. Declares the component's identity, its configuration JSON Schema, and any operational dashboard layout.
Orchestrator	Validates the manifest at install time (a plugin upload containing a component manifest that cannot be parsed is rejected, naming the failing component), serves it to the Portal on request, and uses it to extract operational metadata (such as which fields hold network ports).
Portal	Reads the manifest and renders the setup wizard, the configuration form, and the operational dashboard. The Portal knows nothing about the component beyond what the manifest declares.

Because the contract is the manifest itself, a developer adding a new component writes only Java (the runtime) and JSON (the manifest). There is no frontend code to build, ship, or version separately.

Visual rendering is owned by the Portal

The schema is declarative. The exact visual layout, spacing, typography, and rendering of these components are managed by the Portal and are subject to change in future platform updates. Do not attempt to hack the schema for pixel-perfect layouts. Components that rely on undocumented Portal rendering behavior will break across upgrades. Treat the extension keys below as semantic intent (for example, "this is the primary section header"), not as direct visual instructions.

Top-level manifest

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the component inside its owning plugin (for example, `tag-count-processor`). This is the runtime dispatch key. The platform resolves a route step to its component by calling the owning plugin's `createComponent(id, ...)`, so this value must match the type id the plugin registers in its `SimpleComponentRegistry`. A mismatch fails the route with `No plugin found that handles component type: <id>`.
`pluginId`	string	No	Informational only. The owning plugin's identity is taken from the plugin package at index time, not from this field, so it may be omitted.
`functionalType`	string	No	A classifying label the Orchestrator uses to group and filter component definitions in the catalog. It is not the runtime dispatch key: dispatch is on `id`. Defaults to a placeholder when omitted; conventionally set equal to `id`.
`displayName`	string	Yes	Human-readable label shown in the Portal's component list.
`description`	string	No	Short human-readable summary of the component. Shipped by nearly every component and shown alongside the display name.
`category`	enum	Yes	One of the values listed below. Decides where the component appears in the Pipeline Designer.
`compatibility`	object	No	Declares which protocols the component works with (`protocols`, an array) and its data-flow direction (`direction`, default `BOTH`). Used by the Orchestrator to group and filter the catalog.
`configuration`	object	Yes	JSON Schema (Draft 07) that defines the setup form for this component. See Configuration schema.
`ui`	object	No	Operational dashboard configuration. See Dashboard configuration.

`category` values

Value	Used when the component is
`CONNECTOR`	A source or target that owns an external session.
`TRANSFORMER`	A pipeline stage that mutates the message in flight.
`PROCESSOR`	A pipeline stage that produces a side effect (such as dispatch).
`CONDITION`	A predicate that gates whether a route runs for a given message.
`ERROR_HANDLER`	A terminal handler for the route's error chain.
`ERROR_PROCESSOR`	A processor that participates in the error chain (for example, retry plus DLQ escalation).

Configuration schema

The configuration block is a JSON Schema Draft 07 document. The platform reads it at load time and renders form fields, validation, tooltips, and defaults directly from the schema.

Schema wrapper

Key	Expected value
`$schema`	`http://json-schema.org/draft-07/schema#`
`type`	`object`
`title`	A short human-readable title for the form section.
`properties`	Standard JSON Schema property definitions.
`x-order`	Array of property keys in the order the form should render them. Optional; keys not listed are appended after the ordered ones.

Standard Draft 07 validators (minimum, maximum, pattern, enum, minLength, maxLength, required, default) apply unchanged. The platform enforces them before the configuration is saved. Only type: object and properties are load-bearing: the platform validates against Draft 07 regardless of the $schema value, so $schema and title are recommended but not enforced.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Tag Count Settings",
  "x-order": ["headerName"],
  "properties": {
    "headerName": { "type": "string", "title": "Output Header Name" }
  }
}

Supported schema shapes

The setup form renders the following property shapes. Anything outside this list renders as a visible "not editable here" notice in the form, so operators and manifest authors see the gap instead of a silent blank.

Shape	Renders as
`string`, `number`, `integer`, `boolean`	The matching input control (see `x-widget` for overrides).
`enum`	Radio group (fewer than four options) or dropdown.
`object` with `properties`	A nested form section.
`object` with `additionalProperties` of a primitive type	A key/value map editor with add and remove controls.
`array` of objects	A managed list with a full-screen item editor.
`array` of primitives	A managed list with inline inputs per row.
`oneOf` / `anyOf` without a `type`	The form renders the first branch it can render; the other branches remain accepted by server-side validation. Prefer a single concrete shape in new manifests.

$ref is not resolved, and composition keywords (allOf, if/then) are validated server-side only: the form does not change what it shows based on them.

Extension reference

The platform interprets the following x- keys in addition to standard Draft 07. Every extension is optional.

Layout extensions

Extension	Applies to	What it does
`x-order`	Object schema	Ordered list of property keys. Sets the render order; keys not listed are appended after the ordered ones (they are not hidden). Recommended, not required.
`x-section-title`	Property	Marks a property as the first field under a new section. Properties below it (until the next section title) are grouped under the same heading.
`x-advanced`	Property	Moves the field into a collapsed Advanced area, keeping it out of the primary form.
`x-col-span`	Property	How many columns the field spans in the form's two-column grid. Accepts `1` (the default, half width) or `2` (full width); `full` is an accepted synonym for `2`.

{
  "type": "object",
  "x-order": ["host", "port", "tlsEnabled", "ciphers"],
  "properties": {
    "host":       { "type": "string",  "title": "Host", "x-col-span": 2 },
    "port":       { "type": "integer", "title": "Port" },
    "tlsEnabled": { "type": "boolean", "title": "TLS Enabled", "x-section-title": "Security" },
    "ciphers":    { "type": "string",  "title": "Cipher Suite", "x-advanced": true }
  }
}

UX extensions

Extension	Applies to	What it does
`x-placeholder`	Property	Placeholder text shown when the field is empty.
`x-tooltip`	Property	Help text shown on hover. Used only when the property has no `description`; when both are set, the `description` is shown.
`x-widget`	Property	Overrides the default control the platform infers from the property's type. See the widget table below.
`x-ui-disabled`	Property	Disables the input control for the field while still rendering its current value. Use for fields whose value is owned by an upstream system.

{
  "type": "object",
  "properties": {
    "mappingTemplate": {
      "type": "string",
      "title": "Mapping Template",
      "x-widget": "textarea",
      "x-placeholder": "One source-to-target field mapping per line",
      "x-tooltip": "Applied to every outbound message on this route."
    }
  }
}

`x-widget` values

The x-widget key accepts the following values. Use one only when the platform's default control for the field's type does not fit the data.

Value	Renders as	When to use
`text`	Single-line text input.	Default for `string`. Set explicitly only to override another widget further up the schema.
`textarea`	Multi-line text input.	Free-text fields that may contain more than a short line (descriptions, inline templates, pasted payloads).
`password`	Masked text input.	Rarely. It masks the input box and nothing else: the value is stored, exported, and displayed like any other. It is not a security control, and a credential field holds an `${env:VAR_NAME}` reference rather than a secret, which is easier to check when it is visible.
`select`	Dropdown of static options.	Default for a `string` with `enum` and four or more options.
`radio`	Radio-button group.	Default for a `string` with `enum` and fewer than four options.
`checkbox`	Single checkbox.	A boolean rendered inline with its label.
`switch`	On / off toggle.	A boolean that reads more clearly as a switch than a checkbox.
`dynamic-select`	Dropdown populated at form-render time.	Fields whose valid options come from a platform resource computed at load time. Pair with `x-resource`, `x-label-key`, and `x-value-key`.

Dynamic-data extensions

These keys are used together with "x-widget": "dynamic-select" to populate a dropdown from a platform-provided resource list at form render time.

Extension	Applies to	What it does
`x-resource`	Property	Names the platform resource to fetch (for example, the catalog of uploaded artifacts).
`x-filter`	Property	Optional filter object passed to the resource so the dropdown shows a subset.
`x-label-key`	Property	The field on each resource entry to use as the visible label. Defaults to `name`.
`x-value-key`	Property	The field on each resource entry to use as the persisted value. Defaults to `id`.
`x-item-label`	Array item	Template used to render each item's summary line in array editors.
`x-component-props`	Property	Free-form bag of widget-specific options. Only used by widgets that explicitly document a key inside it.

{
  "type": "object",
  "properties": {
    "dictionaryArtifactId": {
      "type": "string",
      "title": "Data Dictionary",
      "x-widget": "dynamic-select",
      "x-resource": "artifacts",
      "x-filter":   { "type": "fix-data-dictionary" },
      "x-label-key": "name",
      "x-value-key": "id"
    },
    "sessions": {
      "type": "array",
      "items": {
        "type": "object",
        "x-item-label": "{SenderCompID} → {TargetCompID}",
        "properties": {
          "SenderCompID": { "type": "string", "title": "Sender CompID" },
          "TargetCompID": { "type": "string", "title": "Target CompID" }
        }
      }
    }
  }
}

Operational metadata extensions

These keys are read by the Orchestrator (not the form renderer) to drive cross-cutting platform behavior.

Extension	Applies to	What it does
`x-is-port`	Property	Marks a field whose value is a network port that the platform must reserve, expose, and surface in deployment manifests. The platform reads every `x-is-port: true` field at deploy time and turns the values into Kubernetes Service ports.

{
  "type": "object",
  "properties": {
    "SocketAcceptPort": {
      "type": "integer",
      "title": "Listen Port",
      "minimum": 1,
      "maximum": 65535,
      "x-is-port": true
    }
  }
}

Dashboard configuration

The optional ui block defines the operational dashboard for the component. It is organized into pages and widgets. Omit it when the component has no custom dashboard.

Widget category	Renders
Data Cards	Single-value displays or lists of status values pulled from a component-provided API.
Action Widgets	Buttons that trigger an operation on the component (for example, Reset Statistics, Flush Cache).
Custom Components	Links to pre-built UI components for richer views such as message logs or charts.

Authoring guidance

Operator-friendly names. Use labels operators recognize (Heartbeat Interval) instead of internal field keys (hb_int_ms). The schema's title and description are what appears in the form.
Sensible defaults. Provide default values on every non-required field. A form that arrives pre-filled is a form operators can reason about.
Validate in the schema. Use Draft 07 validators (minimum, maximum, pattern, enum) so the platform rejects invalid input before it leaves the form. Deferring validation to runtime forces operators to discover errors after deployment.
Group with sections and the advanced area. Put the two or three fields operators touch most often first. Move everything else under x-advanced or below a later x-section-title. Do not present ten fields at the same level of emphasis.
Mark every port. Any field whose value is a network port must carry "x-is-port": true. Skipping this leaves the platform unable to surface the port in deployment manifests.
Treat extensions as semantic, not visual. The platform owns the rendering. Express intent (x-section-title, x-advanced, x-is-port) and let the renderer evolve.

Schema-Driven Architecture​

Top-level manifest​

category values​

Configuration schema​

Schema wrapper​

Supported schema shapes​

Extension reference​

Layout extensions​

UX extensions​

x-widget values​

Dynamic-data extensions​

Operational metadata extensions​

Dashboard configuration​

Authoring guidance​