XStream

Operator parameter contracts

Every operator must provide parameters in its operator.yaml definition and published manifest.json. This language-neutral contract can be read statically for Python, Java/Scala, native commands, and custom executors. Reading it starts neither an operator nor an inference worker; types are not guessed from descriptions or example values.

Input streams are declared in inputs, parameters in parameters, and output structures by inferOutputs / infer_outputs. These are independent contracts. A parameter contract is not an output schema.

Complete example

name: weather_filter
version: '1.0'
role: transform
type: sdk
image: example/python:1
executor: python
entrypoint: weather_filter
artifact: weather_filter.py
inputs:
  source:
    representations:
    - records
    formats: []
icon:
  path: M3 5h18v14H3zM3 10h18M9 5v14
parameters:
  type: object
  properties:
    min_temperature:
      type: number
      description: Minimum retained temperature in degrees Celsius.
      default: 0
      minimum: -100
      maximum: 100
    station:
      type: string
      description: Station name to retain.
      minLength: 1
    include_quality:
      type: boolean
      description: Include the quality flag in output.
      default: true
    columns:
      type: array
      description: Output column names in the requested order.
      items:
        type: string
        minLength: 1
      minItems: 1
  required:
  - station
  additionalProperties: false
outputs:
  result:
    view: variant

A Job step supplies values, rather than the contract:

params:
  station: DEMO-001
  min_temperature: $MIN_TEMPERATURE
  include_quality: true
  columns: [timestamp, temperature]

Variable file:

MIN_TEMPERATURE: 12.5

The declared type remains number, not variable. $MIN_TEMPERATURE is a whole-value reference, and substitution preserves YAML types. Python reads a number through ctx.params['min_temperature']; Scala reads it through ctx.params.path("min_temperature").asDouble().

Supported declarations

The contract uses a restricted JSON Schema-style subset; it does not claim full JSON Schema support. Unknown keywords are rejected so that editors do not silently ignore constraints.

Keyword Purpose
type Required: string, integer, number, boolean, null, object, or array; also accepts a nonempty array of distinct types, such as [string, object]
title, description Optional display name and explanation
default Optional default value satisfying the declared type and constraints
enum Optional nonempty array of distinct values, each satisfying the type and constraints
minimum, maximum Inclusive numeric bounds
minLength, maxLength String length bounds measured in Unicode code points
items, minItems, maxItems Arrays must declare their element definition and may set length bounds
properties Required property mapping for objects, recursively using the same contract
required Required array of mandatory property names for objects; use [] when none are required
additionalProperties Explicitly required for objects: false rejects undeclared properties, true permits dynamic properties, or a nested definition restricts their value types

The root must have type: object. Nesting is limited to 16 levels. Operators without parameters must explicitly declare:

icon:
  path: "M3 5h18v14H3zM3 10h18M9 5v14"
parameters:
  type: object
  properties: {}
  required: []
  additionalProperties: false

A dynamic mapping, such as column names mapped to aggregate functions:

icon:
  path: "M3 5h18v14H3zM3 10h18M9 5v14"
parameters:
  type: object
  properties:
    aggregates:
      type: object
      properties: {}
      required: []
      additionalProperties: {type: string, enum: [AVG, SUM, MIN, MAX, COUNT]}
  required: [aggregates]
  additionalProperties: false

Publication, design, and execution

The shared Scala validator lives in xstream-operator-sdk/contract. The repository, node resolver, and designer use the same implementation, without operator-name or executor-specific branches. Third-party definitions are discoverable without editing core registries.

Operators must also provide icon; administrators assign public categories; see categories and icons for the contract and publication examples.