Margin watch learning

Margin watch learning is one of Demiton's published registers for Australian civil construction. Lessons and observability gaps Margin Watch has found on a project, awaiting review. Demiton keeps it current from the systems a contractor already runs and publishes the record's shape as a versioned JSON Schema, so the same question works whichever system produced the record.

Part of Projects in the register catalog.

Register ID

margin_watch_learningUse this name to ask for the register. The API calls it a shelf ID.

Each record is

A stateThe current value of something, replaced when it changes.

Status

DeclaredDefined, and fills when a source produces its first record.

Data

OrganisationPrivate to each organisation's own workspace.

Version

v1 (1.1.1)Current version.

Download JSON SchemaSee an example record

Connectors

Connected today

Demiton keeps this register current from these systems now.

No system fills this register yet.

On the roadmap

Systems in the planned connector rollout that can fill this register. Partial means the system holds only some of its fields.

None planned yet.

Fields

22 fields: 14 required, 8 optional.

Required

Every record carries these fields.

summaryText

One-line human summary for content search and list display.

Example: Emerald Street margin drifted -1.8pts in July on plant id…

promotion_gateText

Record-level candidate-only marker.

Example: candidate_only_human_signoff_required

lesson_candidatesList

Candidate lessons awaiting human promotion; empty array is valid.

subject_entity_idWhole number

The project the learning is about; the semantic fact's subject and its supersede key.

Example: 8101

lesson_candidates[].causeText

Attributed cause, one of the five code-defined values in, :86-131

Example: unrecovered_variation

observability_gaps_rankedList

Data gaps that made a cycle unattributable, ranked; empty array valid.

lesson_candidates[].statementText

The candidate lesson, stated as cause + drift + period + project.

Example: Unrecovered variation work reduced margin by 1.8 points o…

observability_gaps_ranked[].gapText

The named missing data (e.g. no diaries for a month)

Example: no site diaries recorded for June

lesson_candidates[].promotion_gateText

Explicit "candidate only, human sign-off required" marker.

Example: candidate_only_human_signoff_required

observability_gaps_ranked[].monthsList

The months in which that gap occurred.

lesson_candidates[].provenance.monthText

Claim-cycle month the drift is measured in.

Example: 2026-07

lesson_candidates[].provenance.evidenceText

The observed signal behind the cause (e.g. a diary-flag count)

Example: 6 diary variation signals in 2026-07 vs 3 approved variat…

lesson_candidates[].provenance.drift_ptsNumberUnit: margin points

Signed margin movement that cycle.

Example: -1.8

observability_gaps_ranked[].margin_points_obscuredNumberUnit: margin points

Total absolute drift the gap obscures.

Example: 2.1

Optional

Present when the source system records them.

job_noText

Producer's snapshot of the job number (duplicates the subject spine's canonical key)

Example: BWG-2025-001

currencycurrency

The currency of every monetary amount on this record, an ISO 4217 alpha-3 code as the source states it. A record with no currency has no usable amount.

legal_entityText

Context coordinate declared OPTIONAL.

Example: Bridgeworks Group Pty Ltd

project_nameText

Producer's snapshot of the project/client label (duplicates the entity label)

Example: Emerald Street Rejuvenation

financial_periodText

Context coordinate declared OPTIONAL.

Example: 2026-07

margin_to_date_pctNumberUnit: percent

Margin to date at attribution time.

Example: 11.2

tendered_margin_pctNumberUnit: percent

Tendered margin at attribution time.

Example: 13

lesson_candidates[].provenance.drift_dollarsNumber

Points scaled by contract value; null when no contract value.

Filed against

Records are indexed along these dimensions, so they can be asked for by any of them.

• Financial periodcontext for the record, from When known
• Legal entitycontext for the record, from When known

Example record

A sample from Bridgeworks Group, Demiton's demonstration company. The values are illustrative; the shape is exactly what the contract describes.

margin_watch_learning.example.json

{
  "financial_period": "2026-07",
  "job_no": "BWG-2025-001",
  "legal_entity": "Bridgeworks Group Pty Ltd",
  "lesson_candidates": [
    {
      "cause": "unrecovered_variation",
      "promotion_gate": "candidate_only_human_signoff_required",
      "provenance": {
        "drift_pts": -1.8,
        "evidence": "6 diary variation signals in 2026-07 vs 3 approved variations on record",
        "month": "2026-07"
      },
      "statement": "Unrecovered variation work reduced margin by 1.8 points on Emerald Street in July 2026."
    }
  ],
  "margin_to_date_pct": 11.2,
  "observability_gaps_ranked": [
    {
      "gap": "no site diaries recorded for June",
      "margin_points_obscured": 2.1,
      "months": [
        "2026-06"
      ]
    }
  ],
  "project_name": "Emerald Street Rejuvenation",
  "promotion_gate": "candidate_only_human_signoff_required",
  "subject_entity_id": 8101,
  "summary": "Emerald Street margin drifted -1.8pts in July on plant idle and unrecovered variation work.",
  "tendered_margin_pct": 13
}

Use this contract

The contract is a standard JSON Schema (draft 2020-12) document, so any JSON Schema validator can check a record against it. Keywords starting with x-demiton- add Demiton's own meaning, such as units and requiredness, and validators ignore them.

Schema URL

https://docs.demiton.io/registers/margin_watch_learning/v1.json

Show the full JSON Schema

Loading the schema…