{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/metadapi/main/json-schema/metadapi-zipcode-schema.json",
  "title": "Zip Code",
  "description": "Zip Code Data Model",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/metadapi-zipcode-openapi.json#/components/schemas/Zipcode",
  "type": "object",
  "properties": {
    "zipCode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5,
      "description": "5 Digit Zip Code. Zone Improvement Plan."
    },
    "uspsMainCityKey": {
      "type": "string",
      "minLength": 1,
      "description": "USPS City / Town key identifier for the main city of the zip code."
    },
    "uspsMainCityName": {
      "type": "string",
      "minLength": 1,
      "description": "USPS City / Town Name for the main city of the zip code. USPS Upper Case Format."
    },
    "titleCaseCityName": {
      "type": "string",
      "minLength": 1,
      "description": "USPS City / Town Name for the main city of the zip code. Title Case Format."
    },
    "zipClassificationCode": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Code provided by USPS for the type of Zip Code it represents.  P = PO Box Zip, U = Unique Zip, M = APO/FPO Military Zip , null (not provided by USPS),N = Non-Unique Zip."
    },
    "zipClassificationDesc": {
      "type": "string",
      "minLength": 1,
      "description": "Description of the zip classification code.   P = PO Box Zip, U = Unique Zip, M = APO/FPO Military Zip , null (not provided by USPS), = Non-Unique Zip."
    },
    "uspsFacilityCode": {
      "type": "string",
      "minLength": 1,
      "description": "Facility code provided by the USPS. B=Branch, C=Community Post Office, N = Non-Postal Community Name, former postal facility or place name, P= Post Office, S=Station, U = Urbanization"
    },
    "uspsFacilityName": {
      "type": "string",
      "minLength": 1,
      "description": "USPS Facility Name  B=Branch, C=Community Post Office, N = Non-Postal Community Name, former postal facility or place name, P= Post Office, S=Station, U = Urbanization"
    },
    "uspsCityMailingInd": {
      "type": "boolean",
      "description": "City names with the City State Mailing Name indicator flag set to True are considered part of a complete and standardized address; city names with the flag set to false  file should not be used in a complete and standardized address."
    },
    "uspsDeliveryCode": {
      "type": "string",
      "minLength": 1,
      "description": "Determines if the zip code city has Carrier Routes."
    },
    "uspsDeliveryDesc": {
      "type": "string",
      "minLength": 1,
      "description": "Determines if the zip code city has Carrier Routes."
    },
    "uspsCarrierRouteSortCode": {
      "type": "string",
      "minLength": 1,
      "description": "Code for the available carrier route."
    },
    "uspsCarrierRouteRateSortDesc": {
      "type": "string",
      "minLength": 1,
      "description": "Description for the carrier route code."
    },
    "uniqueZipNameInd": {
      "type": "boolean",
      "description": "True = Unique Zip Code Name. False the zip code name is not unique."
    },
    "uspsFinanceNumber": {
      "type": "string",
      "minLength": 1,
      "description": "USPS Provided Finance Number. This code is assigned to postal service facilities."
    },
    "stateCode": {
      "type": "string",
      "minLength": 1,
      "description": "Standard 2 character state code."
    },
    "stateName": {
      "type": "string",
      "minLength": 1,
      "description": "State Name"
    },
    "stateFipsCode": {
      "type": "string",
      "minLength": 1,
      "description": "Federal Information Processing Standards 2 digit assigned code."
    },
    "stateAbbr": {
      "type": "string",
      "minLength": 1,
      "description": "Abbreviation for state name."
    },
    "countyFipsCode": {
      "type": "string",
      "minLength": 1,
      "description": "FIPS code assigned to the county of the main city of the zip code."
    },
    "uspsCountyName": {
      "type": "string",
      "minLength": 1,
      "description": "Name of the county of the main city for the zip code."
    },
    "titleCaseCountyName": {
      "type": "string",
      "minLength": 1,
      "description": "Main County Name in Title Case"
    },
    "latitude": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code Latitude"
    },
    "longitude": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code Longitude"
    },
    "landAreaMi2": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code Land area in Square Miles"
    },
    "waterAreaMi2": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code Water Area in Square Miles"
    },
    "landAreaKm2": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code Land Area in square kilometers."
    },
    "waterAreaKm2": {
      "type": [
        "number",
        "null"
      ],
      "description": "Zip Code water area in Square kilometers."
    },
    "divisionCode": {
      "type": "string",
      "minLength": 1,
      "description": "Division Code. Part of the geographical hierarchy of the US provided by the united states census."
    },
    "divisionName": {
      "type": "string",
      "minLength": 1,
      "description": "Division Name. Part of the geographical hierarchy of the US provided by the united states census."
    },
    "regionCode": {
      "type": "string",
      "minLength": 1,
      "description": "Region Code. Part of the geographical hierarchy of the US provided by the united states census."
    },
    "regionName": {
      "type": "string",
      "minLength": 1,
      "description": "Region Name. Part of the geographical hierarchy of the US provided by the united states census."
    },
    "msaCode": {
      "type": "string",
      "minLength": 1,
      "description": "5 digit MSA (Metropolitan Statistical Area) code."
    },
    "msaName": {
      "type": "string",
      "minLength": 1,
      "description": "Name of the defined MSA code."
    },
    "cityAliases": {
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "description": "Array that contains all the city aliases for the given zip code.",
      "items": {
        "type": "object",
        "properties": {
          "uspsCityKey": {
            "type": "string",
            "minLength": 1,
            "description": "USPS City / Town key identifier city of the zip code."
          },
          "uspsCityName": {
            "type": "string",
            "minLength": 1,
            "description": "USPS City / Town Name for the zip code. All uppercase."
          },
          "titleCaseCityName": {
            "type": "string",
            "minLength": 1,
            "description": "USPS City / Town Name for the zip code."
          },
          "uspsCityAbbr": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Main city abbreviation provided by USPS. Null if not provided. Uppercase."
          },
          "uspsCityMailingInd": {
            "type": "boolean",
            "description": "City names with the City State Mailing Name indicator flag set to True are considered part of a complete and standardized address; city names with the flag set to false  file should not be used in a complete and standardized address."
          },
          "uspsMainCityInd": {
            "type": "boolean",
            "description": "If true, the city name and code is the main zip code city name.  (Preferred USPS city)."
          }
        },
        "required": [
          "uspsCityKey",
          "uspsCityName",
          "titleCaseCityName",
          "uspsCityAbbr",
          "uspsCityMailingInd",
          "uspsMainCityInd"
        ]
      }
    },
    "zipCodeStatistics": {
      "type": [
        "array",
        "null"
      ],
      "uniqueItems": true,
      "minItems": 1,
      "description": "Available statistics by year of the Zip Code.",
      "items": {
        "type": "object",
        "properties": {
          "year": {
            "type": "number",
            "description": "Year for the captured statistic"
          },
          "totalPopulation": {
            "type": "number",
            "description": "Total population of the zip code"
          },
          "malePopulation": {
            "type": "number",
            "description": "Total Male population of the zip code."
          },
          "femalePopulation": {
            "type": "number",
            "description": "Total female population of the zip code."
          }
        },
        "required": [
          "year",
          "totalPopulation",
          "malePopulation",
          "femalePopulation"
        ]
      }
    }
  },
  "required": [
    "zipCode",
    "uspsMainCityKey",
    "uspsMainCityName",
    "titleCaseCityName",
    "zipClassificationCode",
    "zipClassificationDesc",
    "uspsFacilityCode",
    "uspsFacilityName",
    "uspsCityMailingInd",
    "uspsDeliveryCode",
    "uspsDeliveryDesc",
    "uspsCarrierRouteSortCode",
    "uspsCarrierRouteRateSortDesc",
    "uniqueZipNameInd",
    "uspsFinanceNumber",
    "stateCode",
    "stateName",
    "stateFipsCode",
    "stateAbbr",
    "countyFipsCode",
    "uspsCountyName",
    "titleCaseCountyName",
    "landAreaMi2",
    "waterAreaMi2",
    "landAreaKm2",
    "waterAreaKm2",
    "divisionCode",
    "divisionName",
    "regionCode",
    "regionName",
    "msaCode",
    "msaName",
    "cityAliases",
    "zipCodeStatistics"
  ]
}