{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/propraven-com/json-schema/propraven-com-zillow-context-schema.json",
  "title": "ZillowContext",
  "description": "Each metric carries its own actual geography and missing reason. canonical_id is omitted when source rights prevent parcel resolution.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/propraven-com-openapi.json#/components/schemas/ZillowContext",
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "string",
      "const": "zillow-market-v1"
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "partial",
        "unavailable"
      ]
    },
    "canonical_id": {
      "type": "string"
    },
    "requestedGeography": {
      "type": "object",
      "properties": {
        "zip5": {
          "type": [
            "string",
            "null"
          ]
        },
        "countyFips": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "cbsa": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "zip5",
        "countyFips",
        "state",
        "cbsa"
      ],
      "additionalProperties": false
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rights": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "string"
                  },
                  "evidenceUrl": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "expiresAt": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "version",
                  "evidenceUrl",
                  "expiresAt"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "metric": {
            "type": "string",
            "enum": [
              "zori",
              "zhvi",
              "inventory",
              "price_cut_share",
              "median_days_to_pending"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "unavailable"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "definition": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "enum": [
              "usd",
              "usd_per_month",
              "count",
              "fraction",
              "days"
            ]
          },
          "value": {
            "type": [
              "number",
              "null"
            ]
          },
          "period": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
              },
              {
                "type": "null"
              }
            ]
          },
          "variant": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "datasetKey": {
                    "type": "string"
                  },
                  "registryVersion": {
                    "type": "integer",
                    "exclusiveMinimum": 0
                  },
                  "universe": {
                    "type": "string"
                  },
                  "frequency": {
                    "type": "string",
                    "const": "monthly"
                  },
                  "smoothing": {
                    "type": "string",
                    "const": "smoothed"
                  },
                  "seasonalAdjustment": {
                    "type": "string",
                    "enum": [
                      "sa",
                      "not_stated"
                    ]
                  }
                },
                "required": [
                  "datasetKey",
                  "registryVersion",
                  "universe",
                  "frequency",
                  "smoothing",
                  "seasonalAdjustment"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "geography": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "providerId": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "country",
                      "msa",
                      "county",
                      "zip"
                    ]
                  }
                },
                "required": [
                  "providerId",
                  "name",
                  "type"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "mapping": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "postal_zip",
                      "county_fips",
                      "verified_crosswalk",
                      "explicit_provider_region"
                    ]
                  },
                  "version": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "fallbackReason": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "method",
                  "version",
                  "source",
                  "fallbackReason"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "snapshot": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "sha256": {
                    "type": "string"
                  },
                  "retrievedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "acceptedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "latestPeriod": {
                    "type": "string",
                    "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                  },
                  "stale": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "id",
                  "sha256",
                  "retrievedAt",
                  "acceptedAt",
                  "latestPeriod",
                  "stale"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "annualChange": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "value": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "percent",
                      "percentage_points",
                      "days"
                    ]
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "value",
                  "unit"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "monthlyChange": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "value": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "percent",
                      "percentage_points",
                      "days"
                    ]
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "value",
                  "unit"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "rentAcceleration": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "value": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "percent",
                      "percentage_points",
                      "days"
                    ]
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "value",
                  "unit"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "period": {
                  "type": "string",
                  "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                },
                "value": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "period",
                "value"
              ],
              "additionalProperties": false
            }
          },
          "sourceUrl": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          }
        },
        "required": [
          "rights",
          "metric",
          "status",
          "reason",
          "definition",
          "unit",
          "value",
          "period",
          "variant",
          "geography",
          "mapping",
          "snapshot",
          "annualChange",
          "monthlyChange",
          "rentAcceleration",
          "points",
          "sourceUrl",
          "attribution"
        ],
        "additionalProperties": false
      }
    },
    "reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "rights": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "approved",
            "unknown",
            "denied"
          ]
        },
        "use": {
          "type": "string",
          "enum": [
            "display",
            "agent",
            "export"
          ]
        },
        "evidenceUrl": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "status",
        "use",
        "evidenceUrl"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "schemaVersion",
    "status",
    "requestedGeography",
    "metrics",
    "reason",
    "rights"
  ],
  "additionalProperties": false,
  "x-schema-source": "src/lib/mcp/tools.zillow.ts#zillowContextOutput"
}