id: https://nde.nl/ontology/hc/classes/AddressComponent
name: AddressComponent
title: AddressComponent

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  vcard: http://www.w3.org/2006/vcard/ns#
  locn: http://www.w3.org/ns/locn#

imports:
- linkml:types
- ../slots/has_or_had_type
- ../slots/long_name
- ../slots/short_name
- ./ComponentType
- ./ComponentTypes
default_range: string

classes:
  AddressComponent:
    class_uri: hc:AddressComponent
    description: |
      A single component of a structured address.

      **PURPOSE**:

      AddressComponent represents one discrete element of an address, such as 
      the street number, street name, city, region, or country. This enables:
      - Parsing addresses from various sources into standardized components
      - Normalizing address data from different formats/APIs
      - Supporting multilingual address representations (long_name vs short_name)

      **COMPONENT STRUCTURE**:

      Each AddressComponent has:
      - `long_name`: Full form of the value (e.g., "Netherlands", "Noord-Holland")
      - `short_name`: Abbreviated form (e.g., "NL", "NH") - may equal long_name
      - `has_or_had_type`: Semantic type(s) via ComponentType (e.g., Country, Locality)

      **STANDARD COMPONENT TYPES**:

      | Type | Description | Example long_name | Example short_name |
      |------|-------------|-------------------|-------------------|
      | `street_number` | House/building number | "1", "221B" | same |
      | `route` | Street/road name | "Museumstraat" | same |
      | `locality` | City/town/village | "Amsterdam" | same |
      | `postal_code` | ZIP/postal code | "1071 XX" | same |
      | `subregion` | County/district | "Amsterdam" | same |
      | `region` | State/province | "Noord-Holland" | "NH" |
      | `country` | Country | "Netherlands" | "NL" |
      | `premise` | Building/complex name | "Rijksmuseum" | same |
      | `subpremise` | Unit/floor/suite | "Floor 3" | "3" |

      **RELATIONSHIP TO Address CLASS**:

      AddressComponent is used for:
      1. **Parsing workflows**: Breaking down raw address strings into components
      2. **Normalization**: Standardizing addresses from different sources
      3. **Intermediate representation**: Before constructing a full Address object

      The Address class provides the final, ontology-aligned representation with 
      dedicated slots (street_name, locality, region, country_name, etc.).

      ```
      Raw Address Data (any source)
          │
          └── parse → AddressComponent[]  # Intermediate representation
                          │
                          └── normalize → Address  # vCard/LOCN aligned
      ```

      **USAGE EXAMPLES**:

      ```yaml
      # Street number component (MIGRATED 2026-01-22: Rule 53)
      - long_name: "1"
        short_name: "1"
        has_or_had_type: [StreetNumber]

      # Province with abbreviation
      - long_name: "Noord-Holland"
        short_name: "NH"
        has_or_had_type: [Region]

      # Country with ISO code
      - long_name: "Netherlands"
        short_name: "NL"
        has_or_had_type: [Country]
      ```

      **SOURCE-AGNOSTIC DESIGN**:

      This class is designed to work with addresses from ANY source:
      - Website scraping
      - Registry data (ISIL, KvK, etc.)
      - API responses (when normalized)
      - Manual data entry
      - OCR/document extraction

      API-specific raw data formats are handled by Endpoint classes.

    close_mappings:
      - locn:AddressRepresentation
    related_mappings:
      - schema:PostalAddress
      - vcard:Address

    slots:
      - long_name
      - short_name
      # REMOVED 2026-01-22: component_type - migrated to has_or_had_type + ComponentType (Rule 53)
      - has_or_had_type

    attributes:
      types:
        range: string
        multivalued: true
        inlined_as_list: true
        description: Address component types (alias for component_type for backward compatibility with Google Maps API format)

    slot_usage:
      long_name:
        range: string
        required: false
        examples:
          - value: "Netherlands"
          - value: "Noord-Holland"
          - value: "Museumstraat"
      short_name:
        range: string
        required: false
        examples:
          - value: "NL"
          - value: "NH"
          - value: "Museumstraat"
      # MIGRATED 2026-01-22: component_type → has_or_had_type + ComponentType (Rule 53)
      has_or_had_type:
        range: ComponentType
        multivalued: true
        inlined_as_list: true
        required: false
        examples:
          - value: StreetNumber
          - value: Locality
          - value: Region
          - value: Country
    comments:
      - Source-agnostic representation of address components
      - Use for parsing/normalization workflows before constructing Address objects
      - Component types follow common geographic hierarchy conventions
      - Multiple types allowed for components that serve multiple roles

    see_also:
      - https://nde.nl/ontology/hc/classes/Address
      - https://www.w3.org/ns/locn#Address

    examples:
      # MIGRATED 2026-01-22: component_type → has_or_had_type + ComponentType (Rule 53)
      - value:
          long_name: "1"
          short_name: "1"
          has_or_had_type: [StreetNumber]
      - value:
          long_name: "Museumstraat"
          short_name: "Museumstraat"
          has_or_had_type: [Route]
      - value:
          long_name: "Amsterdam"
          short_name: "Amsterdam"
          has_or_had_type: [Locality]
      - value:
          long_name: "Noord-Holland"
          short_name: "NH"
          has_or_had_type: [Region]
      - value:
          long_name: "Netherlands"
          short_name: "NL"
          has_or_had_type: [Country]
      - value:
          long_name: "1071 XX"
          short_name: "1071 XX"
          has_or_had_type: [PostalCode]
    annotations:
      specificity_score: 0.35
      specificity_rationale: "Generic address parsing component. Broadly applicable across all address sources and custodian types."
      custodian_types: '["*"]'
      custodian_types_rationale: "Any custodian with address data may use address components during parsing/normalization."