workflow.schema.yml

# JSON Schema (Draft 2020-12) for workflow.yml, written in YAML.
#
# Structural constraints are enforced here; referential integrity
# (successor IDs must exist, terminal states must have no successors,
# $ref targets must resolve to real states/fields or declared globals,
# global models must exist in api/models.py) is checked in
# tests/test_workflow.py.

$schema: "https://json-schema.org/draft/2020-12/schema"
title: Glaze Workflow
type: object
required: [version, states]
additionalProperties: false

properties:
  version:
    type: string
    description: Semantic version of this workflow definition.
    pattern: '^\d+\.\d+\.\d+$'

  globals:
    type: object
    description: |
      Named domain types from api/models.py available as foreign-key references
      in fields via the @<global>.<field> syntax.
      api/models.py remains the source of truth — tests verify that every declared
      global and its fields match the corresponding Django model exactly.
    propertyNames:
      pattern: "^[a-z][a-z0-9_]*$"
    additionalProperties:
      $ref: "#/$defs/global_def"

  states:
    type: array
    description: Ordered list of workflow states (lifecycle order).
    minItems: 2
    items:
      $ref: "#/$defs/state"

  process_summary:
    $ref: "#/$defs/state_summary"

$defs:
  # ---------------------------------------------------------------------------
  # Globals
  # Fields within a global may be inline or global refs (not state refs,
  # since globals have no position in the state graph).
  # ---------------------------------------------------------------------------

  global_def:
    type: object
    required: [model, fields]
    additionalProperties: false
    properties:
      model:
        type: string
        description: Django model class name (PascalCase) in api/models.py.
        pattern: "^[A-Z][a-zA-Z0-9]*$"
      description:
        type: string
        description: Human-readable description of this domain type.
      public:
        type: boolean
        description: |
          Whether this global type supports a shared public library managed by admins.
          Public objects are visible to all users and have no owner (null user).
          Models for globals with public: true must allow a nullable user field.
        default: false
      private:
        type: boolean
        description: |
          Whether this global type supports user-private instances.
          Private objects are owned by a specific user and invisible to others.
        default: true
      factory:
        type: boolean
        description: |
          Whether the model factory should generate a Django model class for this
          global. Defaults to true. Set to false for "reference-only" globals whose
          model is hand-written elsewhere (e.g. the core Piece model, which is
          registered in globals only so that fields DSL refs like
          "@piece.name" can be validated, but whose model class is not a GlobalModel
          subclass and must not be auto-generated).
        default: true
      favoritable:
        type: boolean
        description: |
          Whether this global type supports per-user favorites. When true,
          authenticated users can mark individual entries as favorites via
          POST/DELETE /api/globals/<global_name>/<pk>/favorite/.
        default: false
      taggable:
        type: boolean
        description: |
          Whether instances of this global type can be tagged with entries from
          the shared Tag global. When true, the backend generates an ordered
          per-object join model (for example `PieceTag` for `piece`) and
          exposes tag editing/filtering behavior for that object type.
        default: false
      plural:
        type: string
        description: |
          Explicit plural form of the global name, used for FK related_name
          attributes (e.g. "glaze_types" for "glaze_type").
          When omitted, the plural is derived automatically by _pluralize_snake:
          names ending in 'y' become 'ies'; all others get an 's' suffix.
          Override this key when the automatic rule produces the wrong result
          (e.g. compound words, irregular plurals, or names ending in a silent 'e').
        pattern: "^[a-z][a-z0-9_]*$"
      compose_from:
        type: object
        description: |
          Declares ordered M2M composition relationships for this global type.
          Each key is an M2M field name on the model; each value identifies the
          global type that each element in the M2M relation references.
          Used by the frontend to render an ordered composition picker (e.g. for
          GlazeCombination, which composes an ordered list of GlazeTypes).
          Referential integrity (field exists on model, global exists in globals)
          is enforced in tests/test_workflow.py.
        propertyNames:
          pattern: "^[a-z][a-z0-9_]*$"
        additionalProperties:
          type: object
          required: [global]
          additionalProperties: false
          properties:
            global:
              type: string
              pattern: "^[a-z][a-z0-9_]*$"
              description: The global type name that each element in this M2M field references.
            ordered:
              type: boolean
              description: |
                Whether the elements of this M2M relationship have a forced sort order
                enforced by the through model (e.g. via an `order` field and drag-to-reorder
                in the admin). When true, the UI and admin must preserve insertion order
                and the combination identity depends on element ordering. Default: false.
            filter_label:
              type: string
              description: |
                Human-readable label used in pickers that expose this compose_from
                relationship as a multi-select filter. If omitted, the field name is
                converted to title case (e.g. "glaze_types" → "Glaze Types").
            through_model:
              type: string
              pattern: "^[A-Z][A-Za-z0-9]*$"
              description: |
                The PascalCase name of the Django through model class for this M2M
                relationship. If omitted, the factory defaults to
                `<CompositeModelName>Through`. Set this explicitly when the through
                model already exists in migrations and its name must be preserved.
            through_fields:
              type: object
              description: |
                Fields declared on the through (join) model for this M2M relationship.
                Each key is a field name on the through model; each value is an inline
                field definition or a global ref, using the same DSL as fields.
                Referential integrity (through field exists on model, global refs valid)
                is enforced in tests/test_workflow.py.
              propertyNames:
                pattern: "^[a-z][a-z0-9_]*$"
              additionalProperties:
                $ref: "#/$defs/global_field_def"
      fields:
        type: object
        description: |
          Subset of the model's fields exposed to the field DSL.
          Each key is the model field name (snake_case); each value is an
          inline field definition or a global ref.
          State refs are not permitted here — globals have no ancestry.
          Tests verify that every declared field exists on the Django model.
        minProperties: 1
        propertyNames:
          pattern: "^[a-z][a-z0-9_]*$"
        additionalProperties:
          $ref: "#/$defs/global_field_def"

  # ---------------------------------------------------------------------------
  # State
  # ---------------------------------------------------------------------------

  state:
    type: object
    required: [id, visible, friendly_name, past_friendly_name, description]
    additionalProperties: false
    properties:
      id:
        type: string
        description: Snake-case identifier, unique across all states.
        pattern: "^[a-z][a-z0-9_]*$"
      visible:
        type: boolean
        description: Whether this state is shown in the default UI.
      friendly_name:
        type: string
        description: |
          Human-friendly label for this state used when the state is current or
          upcoming (e.g. "Glazing"). Required so every visible state label is
          authored explicitly in workflow.yml rather than synthesized from the ID.
      past_friendly_name:
        type: string
        description: |
          Human-friendly label for this state used when it appears in history
          (e.g. "Glazed"). Required so the past tense label is authored explicitly
          in workflow.yml rather than synthesized from the state ID.
      description:
        type: string
        description: |
          Required short description of the state's current meaning, written for
          humans. Clients may use this text for tooltips, helper copy, or other
          contextual explanations of the workflow step.
      terminal:
        type: boolean
        description: If true, no outgoing transitions are allowed.
      successors:
        type: array
        description: State IDs that may follow this state.
        items:
          type: string
          pattern: "^[a-z][a-z0-9_]*$"
        uniqueItems: true
      fields:
        type: object
        description: |
          State-specific fields declared using the Glaze field DSL.
          Each key is the field name (snake_case); each value is an inline
          field, a state ref, or a global ref.
        propertyNames:
          pattern: "^[a-z][a-z0-9_]*$"
        additionalProperties:
          $ref: "#/$defs/field_def"

  # ---------------------------------------------------------------------------
  # Field DSL
  #
  # field_def      — used in state fields; all three forms allowed.
  # global_field_def — used in global fields; inline and global refs only
  #                    (state refs don't apply outside the state graph).
  # ---------------------------------------------------------------------------

  field_def:
    oneOf:
      - $ref: "#/$defs/inline_field"
      - $ref: "#/$defs/state_ref_field"
      - $ref: "#/$defs/global_ref_field"
      - $ref: "#/$defs/calculated_field"

  global_field_def:
    oneOf:
      - $ref: "#/$defs/inline_field"
      - $ref: "#/$defs/global_ref_field"

  calculated_field:
    type: object
    required: [compute]
    additionalProperties: false
    description: |
      A read-only field whose value is computed from other fields in the
      piece's history using a recursive AST.
    properties:
      compute:
        $ref: "#/$defs/ast_node"
      description:
        type: string
        description: Human-readable description of the calculated field.
      label:
        type: string
        description: Human-readable label for the field in UIs.
      unit:
        type: string
        description: Optional unit suffix for the computed value (e.g. "lbs", "in").
      decimals:
        type: integer
        description: Number of decimal places to round the result to.
        minimum: 0
        maximum: 6
      display_as:
        type: string
        description: |
          Optional display format for numeric fields.
          Currently supported: "percent" — value is multiplied by 100 and
          displayed with a % suffix.
        enum: [percent]
    if:
      properties:
        display_as: { const: percent }
    then:
      properties:
        compute:
          $ref: "#/$defs/numeric_node"

  ast_node:
    oneOf:
      - $ref: "#/$defs/numeric_node"
      - $ref: "#/$defs/string_node"

  numeric_node:
    oneOf:
      - type: object
        required: [constant]
        additionalProperties: false
        properties:
          constant: { type: number }
      - allOf:
          - $ref: "#/$defs/ast_field_node"
          - properties:
              return_type: { enum: [number, integer] }
      - $ref: "#/$defs/numeric_op_node"

  string_node:
    oneOf:
      - type: object
        required: [constant]
        additionalProperties: false
        properties:
          constant: { type: string }
      - allOf:
          - $ref: "#/$defs/ast_field_node"
          - properties:
              return_type: { const: string }

  numeric_op_node:
    oneOf:
      - $ref: "#/$defs/sum_op"
      - $ref: "#/$defs/product_op"
      - $ref: "#/$defs/difference_op"
      - $ref: "#/$defs/ratio_op"

  sum_op:
    type: object
    required: [op, args]
    additionalProperties: false
    properties:
      op: { const: sum }
      args:
        type: array
        minItems: 2
        items: { $ref: "#/$defs/numeric_node" }

  product_op:
    type: object
    required: [op, args]
    additionalProperties: false
    properties:
      op: { const: product }
      args:
        type: array
        minItems: 2
        items: { $ref: "#/$defs/numeric_node" }

  difference_op:
    type: object
    required: [op, args]
    additionalProperties: false
    properties:
      op: { const: difference }
      args:
        type: array
        minItems: 2
        maxItems: 2
        items: { $ref: "#/$defs/numeric_node" }

  ratio_op:
    type: object
    required: [op, args]
    additionalProperties: false
    properties:
      op: { const: ratio }
      args:
        type: array
        minItems: 2
        maxItems: 2
        items: { $ref: "#/$defs/numeric_node" }

  ast_field_node:
    type: object
    required: [field, return_type]
    additionalProperties: false
    properties:
      field:
        type: string
        description: |
          Reference to a field on a state in the form: <state_id>.<field_name>
        pattern: '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'
      return_type:
        type: string
        enum: [string, number, integer, boolean, array, object, image]

  state_summary:
    type: object
    required: [sections]
    additionalProperties: false
    description: |
      Read-only summary fields to display when this state is current. Summary
      items read or compute values from previous workflow states; they do not
      declare persisted fields on the host state.
    properties:
      sections:
        type: array
        minItems: 1
        items:
          type: object
          required: [title, fields]
          additionalProperties: false
          properties:
            title:
              type: string
            fields:
              type: array
              minItems: 1
              items:
                $ref: "#/$defs/summary_item"

  summary_item:
    type: object
    additionalProperties: false
    properties:
      label:
        type: string
      description:
        type: string
      value:
        $ref: "#/$defs/state_field_ref"
      text:
        type: string
      compute:
        $ref: "#/$defs/summary_compute"
      when:
        $ref: "#/$defs/summary_when"
    oneOf:
      - required: [value]
      - required: [text]
      - required: [compute]

  summary_when:
    type: object
    additionalProperties: false
    oneOf:
      - required: [state_exists]
      - required: [state_missing]
    properties:
      state_exists:
        type: string
        pattern: "^[a-z][a-z0-9_]*$"
      state_missing:
        type: string
        pattern: "^[a-z][a-z0-9_]*$"

  summary_compute:
    type: object
    additionalProperties: false
    properties:
      op:
        type: string
        enum: [product, difference, sum, ratio]
      operands:
        type: array
        minItems: 2
        items:
          $ref: "#/$defs/state_field_ref"
      left:
        $ref: "#/$defs/state_field_ref"
      right:
        $ref: "#/$defs/state_field_ref"
      numerator:
        $ref: "#/$defs/state_field_ref"
      denominator:
        $ref: "#/$defs/state_field_ref"
      unit:
        type: string
      decimals:
        type: integer
        minimum: 0
        maximum: 6
    oneOf:
      - required: [op, operands]
        properties:
          op:
            enum: [product, sum]
        not:
          anyOf:
            - required: [left]
            - required: [right]
            - required: [numerator]
            - required: [denominator]
      - required: [op, left, right]
        properties:
          op:
            const: difference
        not:
          anyOf:
            - required: [operands]
            - required: [numerator]
            - required: [denominator]
      - required: [op, numerator, denominator]
        properties:
          op:
            const: ratio
        not:
          anyOf:
            - required: [operands]
            - required: [left]
            - required: [right]

  state_field_ref:
    type: string
    pattern: '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'

  inline_field:
    type: object
    required: [type]
    additionalProperties: false
    properties:
      type:
        type: string
        description: JSON Schema primitive type for this field.
        enum: [string, number, integer, boolean, array, object, image]
      description:
        type: string
        description: Human-readable description of the field.
      required:
        type: boolean
        description: Whether this field must be provided when recording this state.
        default: false
      enum:
        type: array
        description: |
          Restricts the field to a fixed set of values.
          Only valid when type is "string" — enforced in tests/test_workflow.py.
        minItems: 1
        items: {}
        uniqueItems: true
      filterable:
        type: boolean
        description: |
          Whether this field can be used as a filter criterion in list views.
          Intended for boolean fields; consumers use get_filterable_fields() /
          getFilterableFields() to discover which fields to expose as filter controls.
        default: false
      use_as_thumbnail:
        type: boolean
        description: |
          Marks this field as the thumbnail image for entries of this global type.
          Must only appear on fields with type: image. At most one field per global
          may carry this flag — enforced in tests/test_workflow.py.
        default: false
      max_length:
        type: integer
        description: |
          Maximum character length for string and image fields. When present,
          overrides the factory default (255 for non-description strings).
          Only meaningful when type is "string" or "image"; ignored otherwise.
        minimum: 1
      format:
        type: string
        description: |
          Optional semantic format constraint for string fields.
          Currently supported value: "hex_color" — restricts the field to a
          valid CSS hex color code (#RGB, #RRGGBB, #RGBA, or #RRGGBBAA).
          Only valid when type is "string" — enforced in tests/test_workflow.py.
        enum: [hex_color]
      label:
        type: string
        description: |
          Human-readable label for the field in UIs. Used to render human
          readable controls without hardcoding labels in components.
          If not provided, the field name is converted to title case and used as a label.
          E.g. "firing_temperature" → "Firing Temperature".
      display_as:
        type: string
        description: |
          Optional display format for numeric fields.
          Currently supported: "percent" — value is multiplied by 100 and
          displayed with a % suffix.
        enum: [percent]
    if:
      required: [display_as]
      properties:
        display_as: { const: percent }
    then:
      properties:
        type: { enum: [number, integer] }

  state_ref_field:
    type: object
    required: [$ref]
    additionalProperties: false
    description: Carries a field forward from a reachable ancestor state.
    properties:
      $ref:
        type: string
        description: |
          Reference to a field declared on another (ancestor) state, in the form:
            <state_id>.<field_name>
          Referential validity (state exists, field exists on it, state is a
          reachable ancestor) is enforced in tests/test_workflow.py.
        pattern: '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'
      description:
        type: string
        description: Optional override of the referenced field's description.
      required:
        type: boolean
        description: Optional override of the referenced field's required flag.
      label:
        type: string
        description: |
          Optional override of the referenced field's UI label. If omitted,
          consumers fall back to the referenced field's label or the field name
          converted to title case.
      display_as:
        type: string
        description: Optional override of the display format.
        enum: [percent]

  global_ref_field:
    type: object
    required: [$ref]
    additionalProperties: false
    description: Foreign-key reference to a field on a global domain type.
    properties:
      $ref:
        type: string
        description: |
          Reference to a field declared in the top-level `globals` section, in the form:
            @<global_name>.<field_name>
          The @ prefix distinguishes global refs from state refs.
          Referential validity (global exists, field exists on it, model exists
          in api/models.py) is enforced in tests/test_workflow.py.
        pattern: '^@[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'
      description:
        type: string
        description: Optional override of the referenced field's description.
      required:
        type: boolean
        description: Optional override of the referenced field's required flag.
      label:
        type: string
        description: |
          Optional override of the referenced field's UI label. If omitted,
          consumers fall back to the referenced field's label or the field name
          converted to title case.
      can_create:
        type: boolean
        description: |
          Whether the UI is allowed to create a new instance of the referenced
          global type when recording this state (e.g. create a new Location
          inline rather than selecting an existing one).
          Default: false.
        default: false
      filterable:
        type: boolean
        description: |
          Whether this FK field should be exposed as a single-select filter in
          pickers for the global that declares it. The referenced global's entries
          are fetched as autocomplete options; the selected id is passed as a query
          param named <field_name>_id. Default: false.
        default: false