id: https://nde.nl/ontology/hc/class/Address
name: address_class
title: Address Class
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  vcard: http://www.w3.org/2006/vcard/ns#
  schema: http://schema.org/
  locn: http://www.w3.org/ns/locn#
  gleif_base: https://www.gleif.org/ontology/Base/
  org: http://www.w3.org/ns/org#
  dcterms: http://purl.org/dc/terms/
  skos: http://www.w3.org/2004/02/skos/core#
imports:
  - ./ReconstructionActivity
  - ./AddressType
  - ./HouseNumber
  - linkml:types
  - ../slots/in_country
  - ../slots/has_label
  - ../slots/has_section
  - ../slots/has_type
  - ../slots/derive_from # was: was_derived_from
  - ../slots/generated_by  # was: was_generated_by
  - ../slots/located_in
  - ../slots/has_latitude
  - ../slots/has_locality
  - ../slots/has_longitude
  - ../slots/has_postal_code
  - ../slots/has_geographic_subdivision
# default_range: string
classes:
  Address:
    class_uri: vcard:Address
    description: |
      Physical or postal address for heritage custodians and related entities.
      **ONTOLOGY ALIGNMENT**:
      This class aligns with multiple established address ontologies:
      | Ontology | Class | Notes |
      |----------|-------|-------|
      | **vCard** | `vcard:Address` | RFC6350 ADR property components |
      | **Schema.org** | `schema:PostalAddress` | Web semantics |
      | **LOCN** | `locn:Address` | EU Location Core Vocabulary |
      | **GLEIF** | `gleif_base:PhysicalAddress` | Legal entity addresses |
      **COMPONENT STRUCTURE**:
      An address consists of hierarchical components:
      ```
      Address
      ├── has_section (e.g., "1", "221B", "25-27")
      ├── has_label  (street name as Label, e.g., "Museumstraat")
      ├── postal_code       (e.g., "1071 XX")
      ├── locality          (e.g., "Amsterdam")
      ├── region            (e.g., "Noord-Holland", "NL-NH")
      ├── country_name      (e.g., "Netherlands", "NL")
      └── has_label  (formatted address as Label)
      ```
      NOTE: street_name slot migrated to has_label + Label (2026-01-17, Rule 53/56)
      NOTE: street_address slot removed - was redundant string; use house_number + has_label (2026-01-17, Rule 53/56)
      **ADDRESS TYPES FOR HERITAGE CUSTODIANS**:
      | Type | Use Case |
      |------|----------|
      | `HEADQUARTERS` | Main organizational address |
      | `LEGAL` | Registered legal/business address |
      | `VISITING` | Public visitor entrance |
      | `MAILING` | Correspondence/postal address |
      | `STORAGE` | Depot, warehouse, off-site storage |
      | `BRANCH` | Branch office location |
      **USAGE EXAMPLES**:
      ```yaml
      # Simple address with formatted string
      has_address:
        - address_formatted: "Museumstraat 1, 1071 XX Amsterdam, Netherlands"
          address_type: HEADQUARTERS
      # Structured address with components
      has_address:
        - has_label:
            - has_label: "Museumstraat"
              language: "nl"
          has_section:
            - has_value: "1"
          postal_code: "1071 XX"
          locality: "Amsterdam"
          region: "Noord-Holland"
          country_name: "NL"
          address_type: HEADQUARTERS
          latitude: 52.3600
          longitude: 4.8852
          geonames_id: 2759794
      ```
      **RELATIONSHIP TO OTHER CLASSES**:
      - `AuxiliaryPlace`: Uses Address for structured address data
      - `CustodianPlace`: May reference Address for place location
      - `ContactPoint`: Uses Address for contact location
      - `Settlement`/`Subregion`/`Country`: Hierarchical geographic entities
      **PROVENANCE**:
      Address data may be extracted from various sources (websites, Google Maps, 
      registries). Track provenance with:
      - `was_derived_from`: Link to source observation
      - `generated_by`: Link to extraction activity
    exact_mappings:
      - vcard:Address
    close_mappings:
      - schema:PostalAddress
      - locn:Address
      - gleif_base:PhysicalAddress
    related_mappings:
      - org:siteAddress
      - schema:address
    slots:
      # Street-level components
      - has_section
      # REMOVED: street_name - migrated to has_label + Label (2026-01-17, Rule 53/56)
      # REMOVED: street_address - redundant string slot; use house_number + has_label (2026-01-17, Rule 53/56)
      # Postal components
      - has_postal_code
      # Locality/geographic hierarchy
      - has_locality
      # REMOVED: city - migrated to located_in + City (2026-01-18, Rule 53)
      - located_in
      - has_geographic_subdivision
      - in_country
      # Formatted representation (MIGRATED: address_formatted → has_label)
      - has_label
      # Classification (MIGRATED: address_type → has_type)
      - has_type
      # Geographic coordinates (for geocoded addresses)
      - has_latitude
      - has_longitude
      # Provenance
      - derive_from  # was: was_derived_from - migrated per Rule 53
      - generated_by  # was: was_generated_by - migrated per Rule 53
    slot_usage:
      has_section:
        range: HouseNumber
        required: false
        examples:
        - value:
            has_value: "1"
        - value:
            has_value: "221B"
      # REMOVED: street_name slot_usage - migrated to has_label + Label (2026-01-17, Rule 53/56)
      # Street names should now use Label class with language tagging via has_label
      # REMOVED: street_address slot_usage - redundant string slot removed (2026-01-17, Rule 53/56)
      # Use house_number + has_label (street name as Label) instead of combined string
      has_postal_code:
#         range: string
        required: false
        examples:
          - value: "1071 XX"
      has_locality:
#         range: string
        required: false
        examples:
          - value: "Amsterdam"
      # REMOVED: city slot_usage - migrated to located_in + City (2026-01-18, Rule 53)
      # city:
      #   range: string
      #   required: false
      #   description: Alternative slot for locality (schema:addressLocality)
      located_in:
#         range: string
        required: false
        inlined: false # Fixed invalid inline for primitive type
        examples:
          - value:
              settlement_name: "Amsterdam"
              country: "NL"
      has_geographic_subdivision:
#         range: string
        required: false
        examples:
          - value: "Noord-Holland"
          - value: "NL-NH"
      in_country:
#         range: string
        required: false
        examples:
          - value: "Netherlands"
          - value: "NL"
      # REMOVED 2026-01-22: address_formatted - migrated to has_label + Label (Rule 53, Feedback F1)
      # Formatted address strings now use has_label slot_usage below
      # REMOVED: address_type slot_usage - migrated to has_type (2026-01-17, Rule 53/56)
      has_label:  # was: address_formatted + street_name - migrated per Rule 53 (2026-01-17, 2026-01-22)
#         range: string
        multivalued: true
        inlined: false # Fixed invalid inline for primitive type
        inlined_as_list: false # Fixed invalid inline for primitive type
        required: false
        examples:
          - value:
              - has_label: "Museumstraat"
                language: "nl"
              - has_label: "Museumstraat 1, 1071 XX Amsterdam, Netherlands"
                language: "nl"
      has_type:  # was: address_type - migrated per Rule 53/56 (2026-01-17)
        range: AddressType
        required: false
        multivalued: false
        examples:
          - value: HeadquartersAddress
      has_latitude:
        range: float
        required: false
        examples:
          - value: 52.3600
      has_longitude:
        range: float
        required: false
        examples:
          - value: 4.8852
          - value: 2759794
      derived_from:  # was: was_derived_from - migrated per Rule 53
#         range: string # CustodianObservation
        multivalued: true
        required: false
      generated_by:  # was: was_generated_by - migrated per Rule 53
        range: ReconstructionActivity
        required: false
    comments:
      - vCard Address is the primary ontology class (RFC6350 standard)
      - Use structured components when available, address_formatted as fallback
      - Multiple addresses supported via has_address slot (multivalued, Rule 39 compliant)
      - address_type distinguishes headquarters, legal, visiting, mailing, storage
      - Coordinates (lat/lon) optional but recommended for visualization/mapping
    see_also:
      - https://www.w3.org/TR/vcard-rdf/#d4e936
      - https://schema.org/PostalAddress
      - https://www.w3.org/ns/locn#Address
      - https://www.gleif.org/ontology/Base/PhysicalAddress
    examples:
      - value:
          has_section:
            - has_value: "1"
          has_label:
            - has_label: "Museumstraat"
              language: "nl"
            - has_label: "Museumstraat 1, 1071 XX Amsterdam, Netherlands"
              language: "nl"
          # REMOVED: street_address - migrated to house_number + has_label (2026-01-17, Rule 53/56)
          postal_code: "1071 XX"
          locality: "Amsterdam"
          region: "Noord-Holland"
          country_name: "NL"
          latitude: 52.3600
          longitude: 4.8852
      - value:
          has_section:
            - has_value: "40"
          # REMOVED: street_address - migrated to house_number + has_label (2026-01-17, Rule 53/56)
          postal_code: "2011 RX"
          locality: "Haarlem"
          country_name: "NL"
      - value:
          has_label:
            - has_label: "1600 Pennsylvania Avenue NW, Washington, DC 20500, USA"
              language: "en"
          locality: "Washington"
          region: "DC"
          country_name: "US"
      - value:
          has_label:
            - has_label: "Euterpelaan"
              language: "nl"
            - has_label: "Euterpelaan 25, 3824 BK Amersfoort, Netherlands"
              language: "nl"
          has_section:
            - has_value: "25"
          postal_code: "3824 BK"
          locality: "Amersfoort"
          region: "Utrecht"
          country_name: "NL"
    annotations:
      specificity_score: 0.25
      specificity_rationale: "Address is broadly applicable to all heritage custodian types and many other entities. Universal across domains."
      custodian_types: '["*"]'
      custodian_types_rationale: "All heritage custodians have physical addresses - museums, archives, libraries, etc."