# AddressComponent - Generic address component class
# Source-agnostic representation of individual address parts
# Refactored: 2026-01-12 - Removed Google Maps-specific references per user guidance
# Rule 38 compliant: All slots imported from modules/slots/

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
  # Centralized slots (Rule 38 compliant)
  - ../slots/long_name
  - ../slots/short_name
  - ../slots/component_type

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
      - `component_type`: Semantic type(s) of this component (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
      - long_name: "1"
        short_name: "1"
        component_type: ["street_number"]

      # Province with abbreviation
      - long_name: "Noord-Holland"
        short_name: "NH"
        component_type: ["region"]

      # Country with ISO code
      - long_name: "Netherlands"
        short_name: "NL"
        component_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
      - component_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
        description: Full form of the address component value
        examples:
          - value: "Netherlands"
            description: Country full name
          - value: "Noord-Holland"
            description: Province full name
          - value: "Museumstraat"
            description: Street name
      short_name:
        range: string
        required: false
        description: Abbreviated or short form of the component value (may equal long_name)
        examples:
          - value: "NL"
            description: ISO 3166-1 alpha-2 country code
          - value: "NH"
            description: Province abbreviation
          - value: "Museumstraat"
            description: Same as long_name when no abbreviation exists
      component_type:
        range: string
        multivalued: true
        inlined_as_list: true
        required: false
        description: Semantic type(s) of this address component
        examples:
          - value: ["street_number"]
            description: House/building number
          - value: ["locality"]
            description: City or town
          - value: ["region"]
            description: State or province
          - value: ["country"]
            description: 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:
      - value:
          long_name: "1"
          short_name: "1"
          component_type: ["street_number"]
        description: Street number component

      - value:
          long_name: "Museumstraat"
          short_name: "Museumstraat"
          component_type: ["route"]
        description: Street name component

      - value:
          long_name: "Amsterdam"
          short_name: "Amsterdam"
          component_type: ["locality"]
        description: City component

      - value:
          long_name: "Noord-Holland"
          short_name: "NH"
          component_type: ["region"]
        description: Province component with abbreviation

      - value:
          long_name: "Netherlands"
          short_name: "NL"
          component_type: ["country"]
        description: Country component with ISO code

      - value:
          long_name: "1071 XX"
          short_name: "1071 XX"
          component_type: ["postal_code"]
        description: Dutch postal code component

    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."