Skip to content

Return Studio

Configuration engine

Tier: Configure · Requirement module: Return Template Builder · Status: 🟡 Designed

Purpose

The supervisor defines what it collects. Return Studio holds every return template — sections, fields, formulas, validation rules, attachment requirements, reviewer checklists, due-date policy, thresholds, and scoring weights — as versioned configuration with effective dates.

This is the engine that makes the first law true. If Return Studio is expressive enough, no return needs code.

Scope

Capability Status Notes
Field library 🟡 Reusable field definitions with type, unit, and validation defaults
Section groups 🟡 Ordered sections; the UI renders them as the panels in a return
Formula fields 🟡 derived fields computed by Assay; firms cannot enter them
Validation rules 🟡 Each rule carries a mandatory citation
Reference tables ⬜ Lookups — licence categories, minimum capital by category, holiday calendars
Attachment rules 🟡 Required vs optional, accepted formats, size limits
Reviewer checklist ✅ Checklist items and the outcome set, per template
Versioning 🟡 Immutable versions; a published version is never edited
Effective dates 🟡 The version in force for a period validates that period
Penalty parameters ⬜ Inputs to a penalty recommendation, never an automatic charge
Scoring weights 🟡 Driver weights consumed by Prism

Template anatomy

A template version is the schema for every submission filed against it.

{
  "templateCode": "R02",
  "templateVersion": "2.4",
  "title": "Capital Adequacy Computation Return",
  "frequency": "QUARTERLY",
  "appliesTo": ["SMI_CATEGORY_1", "SMI_CATEGORY_2"],
  "effectiveFrom": "2026-01-01",
  "dueDatePolicy": {
    "noticeDays": 45,
    "calendar": "ZW_PUBLIC_HOLIDAYS",
    "adjustment": "NEXT_WORKING_DAY"
  },
  "sections": [
    {
      "id": "capital",
      "title": "Capital adequacy computation",
      "fields": [
        {
          "id": "R02-X06",
          "label": "Required minimum capital",
          "type": "CURRENCY",
          "mode": "input",
          "source": "REFERENCE",
          "reference": "MIN_CAPITAL_BY_CATEGORY"
        },
        {
          "id": "R02-X07",
          "label": "Capital surplus / (deficit)",
          "type": "CURRENCY",
          "mode": "derived",
          "formula": "R02-X03 - R02-X05 - R02-X06"
        }
      ]
    }
  ],
  "rules": [
    {
      "id": "V07",
      "expression": "R02-X08 >= 1.0",
      "severity": "FAIL",
      "message": "Early warning ratio is below the 1.00 floor",
      "citation": "Directive on Capital Adequacy for Securities Market Intermediaries"
    }
  ],
  "checklist": ["COMPLETENESS", "CONSISTENCY", "THRESHOLDS", "EVIDENCE", "OUTCOME"],
  "outcomes": ["APPROVE", "REJECT", "CLARIFY", "RISK_FLAG", "ENFORCE"]
}

Field identifiers follow the requirement's own convention: Rnn-Fnn for common fields and Rnn-Xnn for return-specific figures. The R02 spec shows a full field set.

Owns

  • Template definitions and their immutable versions
  • Field library and reference tables
  • Validation rule definitions with citations
  • Due-date policy and working-day calendars
  • Checklist and outcome configuration
  • Risk model weights and thresholds

Does not own

  • Submitted values — Strata
  • Rule execution — Assay compiles rules to DMN and runs them
  • Obligation instances — Cadence materialises them from templates and licences
  • Who may file — Registry

Open questions

  • Editing published versions. Currently forbidden. A typo in a rule message therefore requires a new version, which pollutes version history. Considering a patch concept limited to non-semantic fields, with the constraint that any change to an expression, threshold, or field set must be a new version.
  • Rule expression language. DMN FEEL is the default answer. Whether supervisors author FEEL directly or through a builder UI that emits it is an open design question, and the answer determines how much of the no-code promise is real.