{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://schemas.meta-aiml.org/v3.0.0/components/address_format.json",
  "@type": [
    "Thing",
    "ComponentSchema"
  ],
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Address Format Component",
  "description": "Reusable address format for physical locations",
  "type": "object",
  "$defs": {
    "PostalAddress": {
      "type": "object",
      "title": "Postal Address",
      "description": "Complete postal address with all components",
      "properties": {
        "streetAddress": {
          "type": "string",
          "description": "Street address line (number and street name)"
        },
        "streetAddressAdditional": {
          "type": "string",
          "description": "Additional street info (suite, apartment, etc)"
        },
        "addressLocality": {
          "type": "string",
          "description": "City or locality"
        },
        "addressRegion": {
          "type": "string",
          "description": "State, province, or region"
        },
        "postalCode": {
          "type": "string",
          "description": "ZIP code or postal code"
        },
        "addressCountry": {
          "type": "string",
          "description": "Country (ISO 3166-1 alpha-2)"
        }
      },
      "required": [
        "addressCountry"
      ]
    },
    "GeoCoordinates": {
      "type": "object",
      "title": "Geographic Coordinates",
      "description": "Latitude and longitude",
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "accuracy": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "latitude",
        "longitude"
      ]
    },
    "Place": {
      "type": "object",
      "title": "Place",
      "description": "Complete place with address and coordinates",
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "$ref": "#/$defs/PostalAddress"
        },
        "geoCoordinates": {
          "$ref": "#/$defs/GeoCoordinates"
        },
        "directions": {
          "type": "string"
        }
      }
    }
  },
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "phase_1",
    "status": "draft",
    "lastValidated": "2026-02-19",
    "validator": "META-AIML QA"
  },
  "semanticAnnotations": {
    "type": "object",
    "description": "Notes on address format usage across META-AIML v3.",
    "properties": {
      "scope": {
        "type": "string",
        "const": "This component defines reusable address/geo schemas referenced by PhysicalEntity (required) and EventEntity (for physical venues). DigitalEntity does not use this component unless it also has a physical office."
      },
      "isoAlignment": {
        "type": "string",
        "const": "addressCountry uses ISO 3166-1 alpha-2 (2-letter). addressRegion uses ISO 3166-2 (state/province code where applicable)."
      }
    }
  },
  "governanceMetadata": {
    "type": "object",
    "properties": {
      "componentVersion": {
        "type": "string",
        "const": "3.0.0"
      },
      "stabilityLevel": {
        "type": "string",
        "const": "stable"
      },
      "usageGuidelines": {
        "type": "array",
        "const": [
          "streetAddress, addressLocality, and addressCountry are required minimum fields.",
          "geoCoordinates (latitude/longitude) should always accompany address for map integration.",
          "Use ISO 3166-1 alpha-2 for addressCountry (e.g., 'US', 'DE', 'GB').",
          "postalCode format varies by country — validate client-side, not in schema."
        ]
      }
    }
  },
  "examples": {
    "type": "array",
    "examples": [
      {
        "scenario": "US restaurant address",
        "address": {
          "streetAddress": "123 Main Street",
          "addressLocality": "Los Angeles",
          "addressRegion": "CA",
          "postalCode": "90210",
          "addressCountry": "US"
        },
        "geoCoordinates": {
          "latitude": 34.0522,
          "longitude": -118.2437
        }
      },
      {
        "scenario": "European business address",
        "address": {
          "streetAddress": "Unter den Linden 1",
          "addressLocality": "Berlin",
          "addressRegion": "BE",
          "postalCode": "10117",
          "addressCountry": "DE"
        },
        "geoCoordinates": {
          "latitude": 52.5166,
          "longitude": 13.3889
        }
      },
      {
        "scenario": "Multi-location retail chain (distributed PhysicalEntity)",
        "note": "Each location is a separate schema instance with its own address and geoCoordinates.",
        "address": {
          "streetAddress": "500 Oxford Street",
          "addressLocality": "London",
          "addressRegion": "ENG",
          "postalCode": "W1C 2AP",
          "addressCountry": "GB"
        },
        "geoCoordinates": {
          "latitude": 51.5141,
          "longitude": -0.1459
        },
        "additionalFields": {
          "storeNumber": "LON-001",
          "timezone": "Europe/London"
        }
      }
    ]
  },
  "usageNotes": {
    "type": "object",
    "description": "Additional implementation notes for address data in META-AIML v3.",
    "properties": {
      "physicalEntityRequirement": {
        "type": "string",
        "const": "PhysicalEntity ontological mode REQUIRES address and geoCoordinates in modules.location. These fields are structurally mandatory, not optional."
      },
      "privacyConsiderations": {
        "type": "string",
        "const": "Only include the business/public address in entity schemas. Never include private home addresses or employee personal addresses."
      },
      "geocodingRecommendation": {
        "type": "string",
        "const": "geoCoordinates should be verified via geocoding API (Google Maps, OpenStreetMap Nominatim) to ensure accuracy. Precision to 4 decimal places is sufficient for business locations."
      }
    }
  },
  "$id": "https://schemas.meta-aiml.org/v3.0.0/components/address_format.json"
}