glam/schemas/20251121/linkml/modules/classes/BirthDate.yaml

id: https://nde.nl/ontology/hc/class/BirthDate
name: birth_date_class
title: Birth Date Class
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  crm: http://www.cidoc-crm.org/cidoc-crm/
  time: http://www.w3.org/2006/time#
  pico: https://personsincontext.org/model#
  dcterms: http://purl.org/dc/terms/
  xsd: http://www.w3.org/2001/XMLSchema#
imports:
  - linkml:types
  - ../metadata
  - ../slots/20260202_matang/has_reference
  - ../slots/20260202_matang/has_score
  - ../slots/20260202_matang/new/inference_provenance
  - ../slots/20260202_matang/new/is_inferred
  - ../slots/20260202_matang/generated_by
  - ../slots/20260202_matang/new/temporal_extent
default_prefix: hc
classes:
  BirthDate:
    class_uri: schema:Date
    description: "Structured representation of a person's birth date with support for uncertainty, incomplete dates, and provenance tracking.\n**PURPOSE**:\nBirthDate replaces simple string birth_date slots to provide: - EDTF (Extended Date/Time Format) support for uncertain/incomplete dates - Provenance tracking for inferred dates (Rule 45) - Confidence scoring - Source preservation (original format from documents)\n**EDTF NOTATION** (Rule 44):\n| Pattern | Meaning | Example | |---------|---------|---------| | `YYYY` | Year only | `1970` | | `YYYY-MM` | Year and month | `1970-08` | | `YYYY-MM-DD` | Full date | `1970-08-15` | | `YYYX` | Decade | `197X` (1970s) | | `YYXX` | Century | `19XX` (1900s) | | `YYYY~` | Approximate | `1985~` (circa 1985) | | `YYYY?` | Uncertain | `1985?` (possibly 1985) | | `XXXX` | Unknown | Must have search provenance |\n**INFERRED DATA** (Rule 45):\nWhen birth date is inferred (e.g., from earliest education date): - Store in `inferred_birth_date` with full inference\
      \ chain - Set `is_inferred: true` - Document inference method and sources\n**ONTOLOGY ALIGNMENT**:\n| Ontology | Mapping | Usage | |----------|---------|-------| | **Schema.org** | `schema:Date` | Primary class | | **CIDOC-CRM** | `crm:E52_Time-Span` | Temporal extent | | **PiCo** | Birth date observation | Source fidelity | | **TIME** | `time:Instant` | Point in time |\n**EXAMPLE**:\n```yaml has_date_of_birth:\n  temporal_extent:\n    has_notation: \"1970-08-15\"\n    begin_of_the_begin: \"1970-08-15T00:00:00Z\"\n    end_of_the_end: \"1970-08-15T23:59:59Z\"\n  is_inferred: false\n```"
    exact_mappings:
    - schema:Date
    close_mappings:
    - crm:E52_Time-Span
    - time:Instant
    related_mappings:
    - pico:PersonObservation
    slots:
    - has_reference
    - is_inferred
    - inference_provenance
    - generated_by
    - has_score
    - temporal_extent
    slot_usage:
      has_reference:
        range: Reference
        required: false
        inlined: true
        multivalued: true
        description: 'Source reference for the birth date information. MIGRATED 2026-01-22: Replaces birth_source_text with structured Reference. Reference.citation_text preserves original verbatim source text.'
        examples:
        - value:
            source_type: parish_register
        - value:
            source_type: biography
      is_inferred:
        range: boolean
        required: false
        ifabsent: 'false'
      inference_provenance:
#         range: string
        required: false
        examples:
        - value: '{"method": "earliest_education_heuristic", "inference_chain": [...]}'
      generated_by:
        range: GenerationEvent
        required: false
        inlined: true
        description: 'Generation event containing confidence score for birth date determination. MIGRATED 2026-01-19: Replaces confidence slot with structured pattern.'
        examples:
        - value:
            has_score:
              has_score: 0.95
              has_method: document_extraction
        - value:
            has_score:
              has_score: 0.5
              has_method: education_inference
              has_description: Inferred from education start year
      temporal_extent:
        range: TimeSpan
        required: true
        inlined: true
        description: 'CIDOC-CRM TimeSpan representation with EDTF notation preservation. MIGRATED 2026-01-22: Replaces birth_edtf and birth_iso_date per slot_fixes.yaml feedback.

          **STRUCTURE**: - has_notation: Original EDTF string (e.g., "1970-08-15", "197X", "1970~") - begin_of_the_begin: Earliest possible start (ISO 8601) - end_of_the_end: Latest possible end (ISO 8601)

          **EXAMPLES**:

          Full date "1970-08-15": - has_notation: "1970-08-15" - begin_of_the_begin: "1970-08-15T00:00:00Z" - end_of_the_end: "1970-08-15T23:59:59Z"

          Decade "197X": - has_notation: "197X" - begin_of_the_begin: "1970-01-01T00:00:00Z" - end_of_the_end: "1979-12-31T23:59:59Z"'
        examples:
        - value:
            has_notation: '1970-08-15'
            begin_of_the_begin: '1970-08-15T00:00:00Z'
            end_of_the_end: '1970-08-15T23:59:59Z'
        - value:
            has_notation: 197X
            begin_of_the_begin: '1970-01-01T00:00:00Z'
            end_of_the_end: '1979-12-31T23:59:59Z'
        - value:
            has_notation: 1970~
            begin_of_the_begin: '1968-01-01T00:00:00Z'
            end_of_the_end: '1972-12-31T23:59:59Z'
    comments:
    - "MIGRATED 2026-01-22: birth_edtf, birth_iso_date \u2192 temporal_extent.has_notation"
    - TimeSpan provides CIDOC-CRM E52 temporal bounds with EDTF notation preservation
    - Inference provenance required when is_inferred=true (Rule 45)
    - "Source text preserved via has_reference \u2192 Reference"
    see_also:
    - https://www.loc.gov/standards/datetime/
    - https://schema.org/birthDate
    examples:
    - value:
        temporal_extent:
          has_notation: '1970-08-15'
          begin_of_the_begin: '1970-08-15T00:00:00Z'
          end_of_the_end: '1970-08-15T23:59:59Z'
        is_inferred: false
        generated_by:
          has_score:
            has_score: 0.95
            has_method: birth_certificate_extraction
    - value:
        temporal_extent:
          has_notation: 197X
          begin_of_the_begin: '1970-01-01T00:00:00Z'
          end_of_the_end: '1979-12-31T23:59:59Z'
        is_inferred: true
        inference_provenance: '{"method": "earliest_education_heuristic", "source_field": "education[0].start_year"}'
        generated_by:
          has_score:
            has_score: 0.4
            has_method: education_inference
    - value:
        temporal_extent:
          has_notation: '1823'
          begin_of_the_begin: '1823-01-01T00:00:00Z'
          end_of_the_end: '1823-12-31T23:59:59Z'
        has_reference:
        - citation_text: born in the year of our Lord 1823
          source_type: parish_register
        is_inferred: false
        generated_by:
          has_score:
            has_score: 0.75
            has_method: document_extraction
    annotations:
      specificity_score: 0.45
      specificity_rationale: Birth dates are relevant for person research across all heritage sectors.
      custodian_types: "['*']"
enums:
  BirthDateConfidenceEnum:
    description: Confidence levels for birth date values.
    permissible_values:
      HIGH:
      MEDIUM:
      LOW:
      VERY_LOW: