Skip to content

Schema Reference

The workflow engine validates all workflow definitions against a JSON Schema. This page provides a curated guide to the most important schema types with annotated examples. For the complete, auto-generated reference, see the full schema docs.

Validating Workflows

VS Code

Install the YAML extension by Red Hat, then add schema association to your workspace .vscode/settings.json:

Option A -- Static schema (works offline, from the repo):

{
  "yaml.schemas": {
    "./schema/RootWorkflow.schema.json": "*.workflow.yaml"
  }
}

Option B -- Dynamic schema (from a running engine, always up-to-date):

{
  "yaml.schemas": {
    "http://localhost:3030/schema": "*.workflow.yaml"
  }
}

Both options give you autocompletion, inline validation, and hover documentation for all workflow YAML fields. Option B ensures you always validate against the exact schema version the engine is running.

JetBrains IDEs (IntelliJ, PyCharm, WebStorm)

  1. Open Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings
  2. Click + to add a new mapping
  3. Configure:
    • Name: Neops Workflow
    • Schema file or URL: http://localhost:3030/schema (or browse to schema/RootWorkflow.schema.json for offline use)
    • Schema version: JSON Schema version 7
  4. Add a file path pattern: *.workflow.yaml
  5. Click OK

You now get autocompletion and validation for all *.workflow.yaml files.

Command Line

npx ajv validate -s schema/RootWorkflow.schema.json -d my-workflow.workflow.yaml \
  --spec=draft7 -c ajv-formats --strict=false

CI Pipeline

The project includes a Makefile target that validates all example workflows:

make validate-examples

RootWorkflow

The top-level schema for a workflow definition.

Required fields: label, name, package, majorVersion, minorVersion, patchVersion, seedEntity, steps, type

$schema: "http://localhost:3030/schema"   # optional: IDE validation hint
label: my_workflow              # ^\\w+$ pattern
name: my_workflow               # 1-100 characters
package: wf.example.neops.io
majorVersion: 1
minorVersion: 0
patchVersion: 0
seedEntity: device              # device | interface | group | global | client
type: workflow                  # always "workflow"
hideForExecution: false         # optional: hide from execution triggers (default: false)
steps:                          # at least 1 step
  - ...
Optional field Description
$schema URL or path to the JSON Schema. Ignored by the engine, used by IDEs for validation
hideForExecution If true, the workflow definition does not appear in execution trigger lists

ParametrizedFunctionBlock

A step that executes a registered function block.

Required fields: type, label, functionBlock

type: functionBlock
label: ping                     # ^\\w+$ pattern
functionBlock: "fb.neops.io/ping:1.0.0"   # package/name:version pattern
runOn: device                   # optional: entity type
parameters:                     # optional: JMESPath-interpolated
  host: "{{ context.device.ip }}"
rawParameters:                  # optional: literal (not interpolated)
  template: "hostname {{ hostname }}"
condition:                      # optional: skip if false
  type: jmes
  jmes: "{{ context.device.connection_state == 'OK' }}"
assert:                         # optional: fail if any is false
  - type: jmes
    jmes: "{{ context.device.ip != null }}"
retryConfig:                    # optional
  maxRetries: 3
  delay: 10
repeatConfig:                   # optional
  repeats: 5
  delay: 60
continueOnError: false          # optional (default: false)
delay: 0                        # optional: seconds (0-600)
description: "Ping device"     # optional (max 1000 chars)

WorkflowAsStep

An embedded (inline) sub-workflow.

Required fields: type, label, name, steps

type: workflow
label: pre_checks
name: pre_checks
steps:
  - type: functionBlock
    label: ping
    functionBlock: "fb.neops.io/ping:1.0.0"
config:                         # optional
  executionStrategy:
    parallel: true

WorkflowReference

A reference to another workflow definition.

Required fields: type, label, workflow, strategy

type: workflowReference
label: backup
workflow: "wf.neops.io/config_backup:1.0.0"
strategy: embed                 # embed | dispatch
parameters:
  backup_type: "running"

EntityAcquireType

Four acquire types for pulling entities into the execution context:

# Elastic query
- type: elastic
  entity: device
  query: "platform.shortName: ios"
  assertNotEmpty: true
  limit: 100

# Expansion from seed entity
- type: expansion
  entity: interface
  expandFromSeedEntity: true

# Filter entities already in context
- type: context
  entity: interface
  filter: "state == 'UP'"

# Reference from another step
- type: reference
  entity: device
  label: discovery_step

RetryConfiguration

retryConfig:
  maxRetries: 3      # required: 1-100
  delay: 10          # optional: seconds (0-600)
  condition:         # optional: only retry if true
    type: jmes
    jmes: "{{ ... }}"

CronConfiguration

cron:
  - title: "Daily Backup"             # required
    description: "Back up all routers" # required
    query: "platform.shortName: ios"   # required: ES query
    enabled: true                      # required
    concurrency: false                 # required
    crontab:                           # required
      second: "0"
      minute: "0"
      hour: "2"
      dayOfMonth: "*"
      month: "*"
      dayOfWeek: "1-5"
      timezone: "Europe/Zurich"
    parameters:                        # optional
      backup_type: "full"