{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uwmd.org/schemas/uw-market-data.schema.json",
  "title": "UW Market Data Document 1.0",
  "description": "A dated, attributable set of market observations (document profile `market-data-v1`, RFC 0022). It carries observations, not conclusions: no deal_id, no calculations, and no calc pack applies to it. Validating against this schema establishes that the observations are attributable — it establishes nothing about whether they are accurate, current, or representative.",
  "type": "object",
  "required": ["document_id", "as_of", "provider", "geo", "observations"],
  "additionalProperties": false,
  "properties": {
    "document_id": {
      "type": "string",
      "minLength": 1,
      "description": "Stable identity of this observation set, e.g. `md:phx-multifamily:2026-Q2`. Pinned by an RFC 0016 receipt's `inputs_provenance` so a computation is reproducible against exactly these observations."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Vintage of the observation set as a real calendar date. REQUIRED: an observation set with no as-of date is not attributable and MUST be refused rather than stored with the field blank. The pattern cannot reject an impossible date such as 2026-02-30 — an implementation MUST additionally verify the date exists, or it will silently roll forward to a day that never happened."
    },
    "provider": {
      "type": "string",
      "minLength": 1,
      "description": "Who published these observations. REQUIRED for the same reason as `as_of`: an unnamed source cannot be traced."
    },
    "geo": {
      "type": "string",
      "minLength": 1,
      "description": "Geography the observations describe. Matching against a deal is exact; normalizing place names is deliberately out of scope."
    },
    "asset_class": {
      "type": "string",
      "minLength": 1,
      "description": "Optional. When present, the set resolves only for deals of this asset class. Absent means it applies to any."
    },
    "deal_id": {
      "not": {},
      "description": "MUST NOT be present. A market-data document is not an underwriting record, and carrying a deal_id is the cheapest way for it to be misread as one."
    },
    "observations": {
      "type": "array",
      "minItems": 1,
      "description": "The observations. Each `field_path` must be unique — two observations for one path would make resolution depend on array order.",
      "items": {
        "type": "object",
        "required": ["field_path", "value", "unit", "basis"],
        "additionalProperties": true,
        "properties": {
          "field_path": {
            "type": "string",
            "pattern": "^([a-z][a-z0-9_]*)\\.[A-Za-z0-9_.\\[\\]]+$",
            "description": "A path a deal record could carry, as `<section>.<field>`. The section MUST be one FORMAT_SPEC Part IV registers, or an `x_` extension section (§ 4.21); this pattern checks the shape only, so an implementation MUST additionally check section membership. A market-data document MUST NOT introduce paths that do not exist in the section model."
          },
          "value": {
            "description": "The observed value. Rates are fractions, per the repo-wide convention: 0.0545 is 5.45%."
          },
          "unit": {
            "type": "string",
            "minLength": 1,
            "description": "Unit label for `value`, e.g. `fraction`, `USD`, `ratio`."
          },
          "range": {
            "type": "object",
            "required": ["low", "central", "high"],
            "additionalProperties": false,
            "description": "Optional dispersion. MUST satisfy low <= central <= high; a schema cannot express that ordering, so an implementation MUST check it.",
            "properties": {
              "low": { "type": "number" },
              "central": { "type": "number" },
              "high": { "type": "number" }
            }
          },
          "basis": {
            "type": "string",
            "minLength": 1,
            "description": "What the observation rests on — sample size, method, period. REQUIRED and non-empty: a number with no stated basis is an assertion, and this profile is for observations. Deliberately free text, because that is what providers actually publish; structuring it is noted as an open question in RFC 0022."
          },
          "confidence": {
            "enum": ["high", "medium", "low"],
            "description": "The provider's confidence, not the reader's. Promotion to an underwritten value does not raise it."
          }
        }
      }
    }
  }
}
