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
default_range: string
classes:
  AddressComponent:
    class_uri: hc:AddressComponent
    description: "A single component of a structured address.\n\n**PURPOSE**:\n\n\
      AddressComponent represents one discrete element of an address, such as \nthe\
      \ street number, street name, city, region, or country. This enables:\n- Parsing\
      \ addresses from various sources into standardized components\n- Normalizing\
      \ address data from different formats/APIs\n- Supporting multilingual address\
      \ representations (long_name vs short_name)\n\n**COMPONENT STRUCTURE**:\n\n\
      Each AddressComponent has:\n- `long_name`: Full form of the value (e.g., \"\
      Netherlands\", \"Noord-Holland\")\n- `short_name`: Abbreviated form (e.g., \"\
      NL\", \"NH\") - may equal long_name\n- `has_or_had_type`: Semantic type(s) via\
      \ ComponentType (e.g., Country, Locality)\n\n**STANDARD COMPONENT TYPES**:\n\
      \n| Type | Description | Example long_name | Example short_name |\n|------|-------------|-------------------|-------------------|\n\
      | `street_number` | House/building number | \"1\", \"221B\" | same |\n| `route`\
      \ | Street/road name | \"Museumstraat\" | same |\n| `locality` | City/town/village\
      \ | \"Amsterdam\" | same |\n| `postal_code` | ZIP/postal code | \"1071 XX\"\
      \ | same |\n| `subregion` | County/district | \"Amsterdam\" | same |\n| `region`\
      \ | State/province | \"Noord-Holland\" | \"NH\" |\n| `country` | Country | \"\
      Netherlands\" | \"NL\" |\n| `premise` | Building/complex name | \"Rijksmuseum\"\
      \ | same |\n| `subpremise` | Unit/floor/suite | \"Floor 3\" | \"3\" |\n\n**RELATIONSHIP\
      \ TO Address CLASS**:\n\nAddressComponent is used for:\n1. **Parsing workflows**:\
      \ Breaking down raw address strings into components\n2. **Normalization**: Standardizing\
      \ addresses from different sources\n3. **Intermediate representation**: Before\
      \ constructing a full Address object\n\nThe Address class provides the final,\
      \ ontology-aligned representation with \ndedicated slots (street_name, locality,\
      \ region, country_name, etc.).\n\n```\nRaw Address Data (any source)\n    │\n\
      \    └── parse → AddressComponent[]  # Intermediate representation\n       \
      \             │\n                    └── normalize → Address  # vCard/LOCN aligned\n\
      ```\n\n**USAGE EXAMPLES**:\n\n```yaml\n# Street number component (MIGRATED 2026-01-22:\
      \ Rule 53)\n- long_name: \"1\"\n  short_name: \"1\"\n  has_or_had_type: [StreetNumber]\n\
      \n# Province with abbreviation\n- long_name: \"Noord-Holland\"\n  short_name:\
      \ \"NH\"\n  has_or_had_type: [Region]\n\n# Country with ISO code\n- long_name:\
      \ \"Netherlands\"\n  short_name: \"NL\"\n  has_or_had_type: [Country]\n```\n\
      \n**SOURCE-AGNOSTIC DESIGN**:\n\nThis class is designed to work with addresses\
      \ from ANY source:\n- Website scraping\n- Registry data (ISIL, KvK, etc.)\n\
      - API responses (when normalized)\n- Manual data entry\n- OCR/document extraction\n\
      \nAPI-specific raw data formats are handled by Endpoint classes.\n"
    close_mappings:
    - locn:AddressRepresentation
    related_mappings:
    - schema:PostalAddress
    - vcard:Address
    slots:
    - long_name
    - short_name
    - has_or_had_type
    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
      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:
    - 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.