ScoreDetailsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/crimescore-io/json-schema/crimescore-io-score-details-response-schema.json",
  "title": "ScoreDetailsResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/crimescore-io-openapi.yaml#/components/schemas/ScoreDetailsResponse",
  "oneOf": [
    {
      "$ref": "#/$defs/CoordinateScoreDetailsResponse"
    },
    {
      "$ref": "#/$defs/ZctaScoreDetailsResponse"
    }
  ],
  "$defs": {
    "ContributorObservation": {
      "type": "object",
      "required": [
        "label",
        "comparison",
        "value_display",
        "reference_display"
      ],
      "properties": {
        "label": {
          "type": "string",
          "description": "Observed condition within a grouped model factor"
        },
        "comparison": {
          "type": "string",
          "enum": [
            "below_reference",
            "near_reference",
            "above_reference"
          ]
        },
        "value_display": {
          "type": "string",
          "description": "Compact display value for the selected geography"
        },
        "reference_display": {
          "type": "string",
          "description": "Compact display value for the scoring-release reference"
        },
        "reference_label": {
          "type": "string",
          "description": "Public description of the comparison reference"
        }
      }
    },
    "CoordinateScoreDetailsResponse": {
      "type": "object",
      "required": [
        "geoid",
        "resolved",
        "component",
        "safety_score",
        "safety_grade",
        "contributors",
        "data"
      ],
      "properties": {
        "geoid": {
          "type": "string",
          "description": "Census block group FIPS code (12 digits)"
        },
        "resolved": {
          "type": "object",
          "required": [
            "lat",
            "lng",
            "state",
            "county_fips"
          ],
          "properties": {
            "lat": {
              "type": "number"
            },
            "lng": {
              "type": "number"
            },
            "state": {
              "type": "string"
            },
            "county_fips": {
              "type": "string"
            }
          }
        },
        "component": {
          "$ref": "#/$defs/ScoreComponent"
        },
        "safety_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Selected overall or component score"
        },
        "safety_grade": {
          "type": "string",
          "enum": [
            "A",
            "B",
            "C",
            "D",
            "F"
          ],
          "description": "Letter grade for the selected score/component"
        },
        "contributors": {
          "type": "array",
          "description": "Available contributor factors for the selected score/component (eligible evaluation access or paid Starter tier and higher)",
          "items": {
            "$ref": "#/$defs/TopContributor"
          }
        },
        "data": {
          "type": "object",
          "required": [
            "census_vintage",
            "model_version"
          ],
          "properties": {
            "census_vintage": {
              "type": "string",
              "description": "Identifier for the public context-data release used by this scoring release"
            },
            "model_version": {
              "type": "string"
            }
          }
        }
      }
    },
    "ScoreComponent": {
      "type": "string",
      "enum": [
        "overall",
        "violent_crime",
        "property_crime",
        "disorder",
        "frequency"
      ],
      "description": "Score component that can be explained by `/score/details`"
    },
    "TopContributor": {
      "type": "object",
      "required": [
        "label",
        "direction",
        "impact"
      ],
      "properties": {
        "label": {
          "type": "string",
          "description": "Human-readable local factor based on the observed feature value versus the release reference"
        },
        "comparison": {
          "type": "string",
          "enum": [
            "below_reference",
            "near_reference",
            "above_reference"
          ],
          "description": "Whether the observed feature value is below, near, or above the scoring-release reference"
        },
        "value_display": {
          "type": "string",
          "description": "Compact display value for the selected geography"
        },
        "reference_display": {
          "type": "string",
          "description": "Compact display value for the scoring-release reference"
        },
        "reference_label": {
          "type": "string",
          "description": "Public description of the comparison reference"
        },
        "observations": {
          "type": "array",
          "maxItems": 2,
          "description": "Valid observed conditions that clarify a grouped factor when no single member represents it",
          "items": {
            "$ref": "#/$defs/ContributorObservation"
          }
        },
        "direction": {
          "type": "string",
          "enum": [
            "lowers_safety_score",
            "raises_safety_score"
          ],
          "description": "Enum describing whether this local factor lowers or raises the safety score. Values: `lowers_safety_score`, `raises_safety_score`."
        },
        "impact": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "description": "Enum describing relative modeled impact among the returned contributors. Values: `high`, `medium`, `low`."
        }
      }
    },
    "ZctaScoreDetailsResponse": {
      "type": "object",
      "required": [
        "zcta",
        "resolved",
        "component",
        "safety_score",
        "safety_grade",
        "contributors",
        "data"
      ],
      "properties": {
        "zcta": {
          "type": "string",
          "description": "Census ZIP Code Tabulation Area code"
        },
        "resolved": {
          "type": "object",
          "required": [
            "zip"
          ],
          "properties": {
            "zip": {
              "type": "string",
              "description": "Input ZIP code resolved as a Census ZCTA"
            }
          }
        },
        "component": {
          "$ref": "#/$defs/ScoreComponent"
        },
        "safety_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Selected overall or population-weighted component score"
        },
        "safety_grade": {
          "type": "string",
          "enum": [
            "A",
            "B",
            "C",
            "D",
            "F"
          ],
          "description": "Letter grade for the selected score/component"
        },
        "contributors": {
          "type": "array",
          "description": "Weighted contributor factors for the selected ZIP code score/component (eligible evaluation access or paid Starter tier and higher)",
          "items": {
            "$ref": "#/$defs/TopContributor"
          }
        },
        "data": {
          "type": "object",
          "required": [
            "census_vintage",
            "model_version",
            "block_group_count"
          ],
          "properties": {
            "census_vintage": {
              "type": "string",
              "description": "Identifier for the public context-data release used by this scoring release"
            },
            "model_version": {
              "type": "string"
            },
            "block_group_count": {
              "type": "integer",
              "description": "Number of scored block groups used in the ZIP code estimate"
            }
          }
        }
      }
    }
  }
}