platform_research_finding contract v3

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.demiton.io/registers/platform_research_finding/v3.json",
  "title": "platform_research_finding contract v3",
  "type": "object",
  "required": [
    "confidence",
    "disease_key",
    "exposure_basis",
    "exposure_kind",
    "exposure_unit",
    "exposure_value",
    "label",
    "metric_key",
    "source_org",
    "source_title",
    "source_url"
  ],
  "properties": {
    "label": {
      "type": "string",
      "description": "how the finding is named on the surface, in the source's own terms - 'Mean total rework cost (115 Australian civil projects)'",
      "x-demiton-requiredness": "required"
    },
    "caveat": {
      "type": "string",
      "description": "the author's own plain-English limit on the figure, where the research pass gave one - 'Based on respondents' estimates, not records'; 'Size of the pot, not a loss'",
      "x-demiton-requiredness": "optional"
    },
    "currency": {
      "type": "currency",
      "description": "ISO 4217 currency of a `per_*` figure (AUD, USD, NZD); null for ratios and `none`. The surface prints the amount in this currency, never as a bare dollar sign",
      "x-demiton-requiredness": "optional"
    },
    "confidence": {
      "type": "string",
      "description": "the evidence grade, by the published rubric in github.com/demitonapp/disease-economics METHOD.md Section 4: `low` (read second-hand, unverifiable, or a model or estimate), `moderate` (read at source but one organisation's data, people's own estimates, or a sampling problem the caveat names), `high` (read at source and none of those). Carried so the surface can rank its evidence honestly instead of presenting a secondary citation as a measurement",
      "x-demiton-requiredness": "required"
    },
    "industries": {
      "type": "array",
      "description": "ISIC Rev.4 divisions the evidence covers (`F42` civil engineering, `F` construction, `ALL`, `unknown`); the union of the finding's sources. Carried for display and future matching; not yet part of the rule",
      "items": {
        "type": "string"
      },
      "x-demiton-requiredness": "optional"
    },
    "metric_key": {
      "type": "string",
      "description": "the finding's stable identifier within its disease, e.g. `rework_total_civil_survey`. The seed's idempotency partner: re-running the seed updates the same row, and a genuinely new finding gets a new key",
      "x-demiton-requiredness": "required"
    },
    "price_year": {
      "type": "integer",
      "description": "the year a `per_*` amount is priced in; null otherwise",
      "x-demiton-requiredness": "optional"
    },
    "source_org": {
      "type": "string",
      "description": "the publishing organisation or author of record",
      "x-demiton-requiredness": "required"
    },
    "source_url": {
      "type": "string",
      "description": "a resolvable link to the source",
      "x-demiton-requiredness": "required"
    },
    "denominator": {
      "type": "string",
      "description": "what a `ratio_of_other` figure is a share OF: `budget_at_decision`, `budget_at_announcement`, `construction_cost`, `amount_claimed`, `arbitration_cost`, `total_injury_cost` (the vocabulary of github.com/demitonapp/disease-economics schema/finding.schema.json). Null for every other unit",
      "x-demiton-requiredness": "optional"
    },
    "disease_key": {
      "type": "string",
      "description": "which of the five margin diseases this finding prices - the key in `vocab/diseases.json` (`rework`, `overrun`, `forfeited_entitlements`, `disputes`, `non_compliance`)",
      "x-demiton-requiredness": "required"
    },
    "sample_note": {
      "type": "string",
      "description": "sample size, geography, sector and method - what bounds the figure. Null where the source did not disclose it",
      "x-demiton-requiredness": "optional"
    },
    "source_year": {
      "type": "integer",
      "description": "the year of the source, for a vintage check - a 2001 benchmark and a 2025 one are not the same evidence",
      "x-demiton-requiredness": "optional"
    },
    "source_title": {
      "type": "string",
      "description": "the paper, report or dataset title",
      "x-demiton-requiredness": "required"
    },
    "exposure_kind": {
      "type": "string",
      "description": "who bears the money: `contractor_loss` (the source measured money the contractor loses), `money_at_stake` (it measured how much is in play, not what is lost), `owner_side` (the client pays), or `societal` (workers and the community). Only contractor_loss and money_at_stake may reach the headline ledger",
      "x-demiton-requiredness": "required"
    },
    "exposure_unit": {
      "type": "string",
      "description": "how the figure may be projected: `ratio_of_contract` (multiplies a contract value), `ratio_of_other` (a share of something else, named by `denominator`; never multiplied), `per_wet_day`, `per_incident`, `per_year_industry`, or `none` when no published figure exists. Multiplying a per-day or per-incident figure, or a share of an arbitration bill, by a contract value is nonsense, so the unit is declared rather than assumed",
      "x-demiton-requiredness": "required"
    },
    "jurisdictions": {
      "type": "array",
      "description": "Where the evidence is from: ISO 3166 codes (`AU`, `AU-QLD`), `GLOBAL` (no limit claimed) or `unknown`; the union of the finding's sources. The exposure service applies a figure to a project only when this holds the project's place, its country, or GLOBAL",
      "items": {
        "type": "string"
      },
      "x-demiton-requiredness": "optional"
    },
    "exposure_basis": {
      "type": "string",
      "description": "what the figure is a percentage OF, in words - 'of original contract value'. Stored because the same disease yields 3-5% of one basis and 10% of another, and a bare number without its basis is the most common way a benchmark misleads",
      "x-demiton-requiredness": "required"
    },
    "exposure_value": {
      "type": "number",
      "description": "the published figure in the source's own unit. A share of contract value is stored as a decimal fraction (10% is 0.10); a per-day or per-incident figure is stored in whole dollars. 0 when the source published no such figure",
      "x-demiton-requiredness": "required",
      "x-demiton-unit": "decimal fraction for ratio_of_contract; AUD for per_wet_day and per_incident"
    },
    "source_location": {
      "type": "string",
      "description": "where in the document to look - 'abstract', 'p.5', 'table 23'. Null when the source did not permit it",
      "x-demiton-requiredness": "optional"
    },
    "source_secondary": {
      "type": "boolean",
      "description": "true when the figure was read only through someone else's citation rather than at the primary document",
      "x-demiton-requiredness": "optional"
    }
  },
  "x-demiton-register-type": "platform_research_finding",
  "x-demiton-contract-version": "3.0.1",
  "x-demiton-store": "platform",
  "x-demiton-axes": [],
  "x-demiton-measures": [
    {
      "key": "ratio_of_contract",
      "accumulation": "instantaneous",
      "dtype": "decimal",
      "unit": "dimensionless"
    }
  ],
  "x-demiton-provenance": {
    "standards": []
  },
  "description": "The Platform research finding register contract, version 3. JSON Schema (draft 2020-12); x-demiton-* keywords carry Demiton's own meaning and standard validators ignore them.",
  "x-demiton-contract-url": "https://docs.demiton.io/registers/platform_research_finding/",
  "x-demiton-register-catalog": "https://docs.demiton.io/concepts/register-catalog"
}