ZDDC/zddc/internal/handler/default-rsk.form.yaml

# Default row schema for a Risk Register entry, served by
# zddc-server when no operator-supplied form.yaml exists at
# archive/<party>/rsk/.
#
# The risk register is structurally different from MDL: the RSK
# TABLE is itself a tracked deliverable (with its own tracking
# number — same shape as an MDL deliverable, type locked to RSK by
# the cascade), and each row in the table is a CHILD of that
# deliverable identified by a per-row sequence (`row`). The row's
# filename = <table-tracking>-<row>.yaml, composed by the server
# from the components below.
#
# Why the table-tracking components live on every row: the row .yaml
# is self-describing — you can pick up any single file and identify
# both the deliverable it contributes to AND its position within
# that deliverable. Multiple RSK tables (different table-tracking
# numbers) can coexist as siblings in the same rsk/ folder; the
# scope-fields shared by their rows are what groups them.
#
# Likelihood and impact use the standard 1-5 ordinal scales;
# severity is also 1-25 (typically L*I) and stored on each row so
# operators can override it when the simple product doesn't capture
# the actual risk profile.
#
# Audit fields are server-managed and read-only (clients must not
# submit values).
#
# To customize: drop your own form.yaml into archive/<party>/rsk/
# (the same directory as table.yaml). Tighten constraints with
# `enum:`, `pattern:`, etc. Add fields and they'll appear in the
# row-edit form; add a matching column to table.yaml to surface
# the field in the table view too.

title: Risk
description: One identified risk. The first eight fields together identify the parent risk-register deliverable; `row` is this entry's position within it. Likelihood and impact use 1-5 ordinals; severity is stored separately so it can be overridden when L*I underrepresents the residual exposure.

schema:
  type: object
  # `type` is intentionally absent from required: — the cascade's
  # field_defaults inject type=RSK after schema validation, and the
  # form renderer surfaces it as a locked readOnly field.
  # originator is omitted from required: it's folder-bound — the server
  # derives it from the party-folder name (folder_fields) and the form
  # renders it read-only.
  required: [project, discipline, sequence, title]
  additionalProperties: false
  properties:
    # --- Table-tracking components: identify which RSK deliverable
    # this row belongs to. Together with `row`, they compose the
    # row's filename via the cascade's filename_format.
    originator:
      type: string
      title: Originator
      description: Bound to the party-folder name — the folder is the source of truth for the originator code. Server-set and read-only; you don't edit it here.
      readOnly: true
    # phase:                          # project-wide; sits between originator and project
    #   type: string
    #   title: Phase
    #   description: Project phase code (ECI, EPC, ...).
    #   minLength: 1
    project:
      type: string
      title: Project
      description: Project identifier, or your corporate placeholder for non-project deliverables.
      minLength: 1
    # area:                           # project-wide; sits between project and discipline
    #   type: string
    #   title: Area
    #   description: Area / budget code.
    #   minLength: 1
    discipline:
      type: string
      title: Discipline
      description: Engineering or functional group code (EL, ME, CV, PM, ...).
      minLength: 1
    type:
      type: string
      title: Document type
      description: Locked to RSK by the cascade's field_defaults; the form renders this read-only and the server returns 422 if a different value is submitted.
      enum: [RSK]
    sequence:
      type: string
      title: Sequence
      description: Zero-padded integer identifying this risk register among the originator's deliverables.
      minLength: 1
    suffix:
      type: string
      title: Suffix
      description: Optional structural-part suffix on the parent register (A, 01, ...). Just the letters/digits — the leading dash is added by the cascade's filename_format.

    # --- Row sequence within the table. Server-assigned on
    # POST-create; preserved as-is on PUT-update.
    row:
      type: string
      title: Row
      description: Zero-padded sequence within this risk register (001, 002, ...). Server-assigned on add; do not edit.
      minLength: 1
      readOnly: true

    # --- Risk-level data.
    title:
      type: string
      title: Risk
      minLength: 1
    category:
      type: string
      title: Category
      description: Free-form grouping (schedule, cost, technical, regulatory, ...).
    package:
      type: string
      title: Package
      description: The SSR package this risk belongs to. The table view sources
        the column's dropdown from the project's ssr/ registry
        (table.yaml column options_source).
    description:
      type: string
      title: Description
    likelihood:
      type: integer
      title: Likelihood
      description: 1 (rare) to 5 (almost certain).
      minimum: 1
      maximum: 5
    impact:
      type: integer
      title: Impact
      description: 1 (negligible) to 5 (catastrophic).
      minimum: 1
      maximum: 5
    severity:
      type: integer
      title: Severity
      description: Residual risk score. Typically likelihood * impact (1-25), but operators can override.
      minimum: 1
      maximum: 25
    mitigation:
      type: string
      title: Mitigation
      description: Plan for reducing this risk's likelihood or impact.
    owner:
      type: string
      title: Owner
      description: Email or party name responsible for tracking this risk.
    status:
      type: string
      title: Status
      enum: [open, mitigated, accepted, closed]
    dueDate:
      type: string
      title: Due date
      format: date
    notes:
      type: string
      title: Notes

    # --- Audit fields (server-managed; read-only).
    created_at:
      type: string
      title: Created
      format: date-time
      readOnly: true
    created_by:
      type: string
      title: Created by
      format: email
      readOnly: true
    updated_at:
      type: string
      title: Updated
      format: date-time
      readOnly: true
    updated_by:
      type: string
      title: Updated by
      format: email
      readOnly: true
    revision:
      type: integer
      title: Revision
      minimum: 1
      readOnly: true
    previous_sha:
      type: string
      title: Previous SHA
      description: SHA-256 (first 8 hex chars) of the prior revision's bytes.
      readOnly: true
ui:
  description:
    ui:widget: textarea
  mitigation:
    ui:widget: textarea
  notes:
    ui:widget: textarea