Appendix C: JSON Schema Reference

This appendix documents the JSON model format used by petri-pilot for code generation. The schema defines what a valid Petri net model looks like — places, transitions, arcs, and the higher-level structures (roles, views, navigation, admin, event sourcing, simulation) that drive application generation.

The full JSON Schema is published at github.com/pflow-xyz/petri-pilot/schema/petri-model.schema.json.

Top-Level Structure

A model is a JSON object with four required fields and several optional ones:

{
  "name": "order-processing",
  "version": "1.0.0",
  "description": "Order fulfillment workflow",
  "places": [...],
  "transitions": [...],
  "arcs": [...],
  "constraints": [...],
  "roles": [...],
  "access": [...],
  "views": [...],
  "navigation": {...},
  "admin": {...},
  "eventSourcing": {...},
  "simulation": {...}
}

Places

A place holds state — either token counts (classic Petri net) or structured data.

{
  "id": "order_received",
  "description": "Order has been received but not yet validated",
  "initial": 1,
  "kind": "token",
  "type": "string",
  "initial_value": null,
  "exported": false,
  "persisted": false
}

Data Types

For kind: "data" places, the type field specifies the data type:

Transitions

A transition is an action that fires when enabled. Each transition becomes an HTTP endpoint in the generated application.

{
  "id": "validate_order",
  "description": "Validate the order details",
  "guard": "amount > 0",
  "event_type": "OrderValidated",
  "http_method": "POST",
  "http_path": "/api/validate",
  "bindings": {
    "amount": "body.amount"
  }
}

Guard Syntax

Guards are boolean expressions evaluated against the current state:

Arcs

An arc connects a place to a transition (input) or a transition to a place (output).

{
  "from": "balances",
  "to": "transfer",
  "weight": 1,
  "keys": ["from"],
  "value": "amount"
}

Constraints

An invariant that must always hold.

{
  "id": "conservation",
  "expr": "received + validated + shipped + completed == 1"
}

Roles

Named roles for access control, with inheritance.

{
  "id": "admin",
  "name": "Administrator",
  "description": "Full access to all operations",
  "inherits": ["manager"]
}

Access Rules

Maps transitions to allowed roles.

{
  "transition": "approve_order",
  "roles": ["manager", "admin"],
  "guard": "user.department == 'finance'"
}

Views

UI view definitions for forms, tables, and detail pages.

{
  "id": "order_detail",
  "name": "Order Details",
  "kind": "detail",
  "description": "Shows order information",
  "groups": [...],
  "actions": ["approve", "reject"]
}

View Groups

{
  "id": "customer_info",
  "name": "Customer Information",
  "fields": [...]
}

View Fields

{
  "binding": "customer_email",
  "label": "Email Address",
  "type": "email",
  "required": true,
  "readonly": false,
  "placeholder": "customer@example.com"
}

Field types: text, number, email, date, datetime, select, checkbox, textarea, password, hidden.

Navigation

Navigation menu configuration. Generates /api/navigation endpoint.

{
  "brand": "Order Tracker",
  "items": [
    {
      "label": "Orders",
      "path": "/orders",
      "icon": "box",
      "roles": []
    },
    {
      "label": "Admin",
      "path": "/admin",
      "icon": "gear",
      "roles": ["admin"]
    }
  ]
}

Admin

Admin dashboard configuration. Generates /admin/* endpoints.

{
  "enabled": true,
  "path": "/admin",
  "roles": ["admin"],
  "features": ["list", "detail", "history", "transitions"]
}

Features: list (instance listing), detail (instance detail page), history (event history), transitions (manual transition firing).

Event Sourcing

Snapshot and retention configuration.

{
  "snapshots": {
    "enabled": true,
    "frequency": 100
  },
  "retention": {
    "events": "90d",
    "snapshots": "1y"
  }
}

Retention durations use the pattern ^\d+[dwmy]$ — number followed by d (days), w (weeks), m (months), or y (years).

Simulation

ODE simulation configuration for AI move evaluation.

{
  "objective": "win_x - win_o",
  "players": {
    "x": {
      "maximizes": true,
      "turnPlace": "turn_x",
      "transitions": ["move_x_0", "move_x_1"]
    },
    "o": {
      "maximizes": false,
      "turnPlace": "turn_o",
      "transitions": ["move_o_0", "move_o_1"]
    }
  },
  "solver": {
    "tspan": [0, 10],
    "dt": 0.01,
    "rates": {
      "move_x_0": 1.0,
      "move_o_0": 1.0
    }
  }
}

Objective Functions

The objective field uses guard DSL syntax extended with aggregate functions:

Solver Configuration

Minimal Example

The smallest valid model:

{
  "name": "toggle",
  "places": [
    {"id": "off", "initial": 1},
    {"id": "on"}
  ],
  "transitions": [
    {"id": "switch"}
  ],
  "arcs": [
    {"from": "off", "to": "switch"},
    {"from": "switch", "to": "on"}
  ]
}

This defines a one-shot toggle: a token starts in off, the switch transition fires, and the token moves to on. Three fields, two places, one transition, two arcs — the simplest possible Petri net application.