glam/frontend/public/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/specificity_annotation
  - ../slots/template_specificity
  - ./SpecificityAnnotation
  - ./TemplateSpecificityScores
  - ../slots/confidence
  - ../slots/birth_edtf
  - ../slots/birth_iso_date
  - ../slots/birth_source_text
  - ../slots/inference_provenance
  - ../slots/is_inferred
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.
      
      **PURPOSE**:
      
      BirthDate 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)
      
      **EDTF NOTATION** (Rule 44):
      
      | 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 |
      
      **INFERRED DATA** (Rule 45):
      
      When 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
      
      **ONTOLOGY ALIGNMENT**:
      
      | 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 |
      
      **EXAMPLE**:
      
      ```yaml
      has_or_had_date_of_birth:
        birth_edtf: "1970-08-15"
        birth_iso_date: "1970-08-15"
        is_inferred: false
        confidence: high
      ```      
    exact_mappings:
      - schema:Date
    close_mappings:
      - crm:E52_Time-Span
      - time:Instant
    related_mappings:
      - pico:PersonObservation
    slots:
      - birth_edtf
      - birth_iso_date
      - birth_source_text
      - is_inferred
      - inference_provenance
      - confidence
      - specificity_annotation
      - template_specificity
    slot_usage:
      birth_edtf:
        range: string
        required: true
        description: >-
          Birth date in EDTF notation (Extended Date/Time Format).
          Supports incomplete dates, uncertainty, and approximation.          
        examples:
          - value: "1970-08-15"
            description: Full date known
          - value: "1970-08"
            description: Year and month known
          - value: "1970"
            description: Only year known
          - value: "197X"
            description: Decade known (1970s)
          - value: "1970~"
            description: Approximate (circa 1970)
          - value: "XXXX"
            description: Unknown (requires search provenance)
      birth_iso_date:
        range: date
        required: false
        description: >-
          Birth date as ISO 8601 date (YYYY-MM-DD) when full date is known.
          Optional - use birth_edtf for partial/uncertain dates.          
        examples:
          - value: "1970-08-15"
      birth_source_text:
        range: string
        required: false
        description: >-
          Original date text from source document, preserved verbatim.
          Useful for archival/historical sources with non-standard notation.          
        examples:
          - value: "born in the year of our Lord 1823"
          - value: "ca. 1750"
          - value: "late 18th century"
      is_inferred:
        range: boolean
        required: false
        ifabsent: "false"
        description: >-
          Whether this birth date was inferred (vs. directly extracted).
          If true, inference_provenance MUST be provided per Rule 45.          
      inference_provenance:
        range: string
        required: false
        description: >-
          JSON string documenting inference chain per Rule 45.
          Required when is_inferred is true.          
        examples:
          - value: '{"method": "earliest_education_heuristic", "inference_chain": [...]}'
      confidence:
        range: BirthDateConfidenceEnum
        required: false
        description: >-
          Confidence level in the birth date value.          
    comments:
      - "Replaces simple birth_date string slot (Rule 53)"
      - "EDTF notation enables uncertain/incomplete date representation"
      - "Inference provenance required when is_inferred=true (Rule 45)"
      - "Source text preservation supports archival/historical research"
    see_also:
      - https://www.loc.gov/standards/datetime/
      - https://schema.org/birthDate
    examples:
      - value:
          birth_edtf: "1970-08-15"
          birth_iso_date: "1970-08-15"
          is_inferred: false
          confidence: HIGH
        description: Full date known with high confidence
      - value:
          birth_edtf: "197X"
          is_inferred: true
          inference_provenance: '{"method": "earliest_education_heuristic", "source_field": "education[0].start_year"}'
          confidence: LOW
        description: Decade inferred from education start year
      - value:
          birth_edtf: "1823"
          birth_source_text: "born in the year of our Lord 1823"
          is_inferred: false
          confidence: MEDIUM
        description: Year extracted from historical document
    annotations:
      specificity_score: 0.45
      specificity_rationale: >-
        Birth dates are relevant for person research across all heritage sectors.        

slots:
  birth_edtf:
    description: Birth date in EDTF notation.
    range: string
    slot_uri: dcterms:date
  birth_iso_date:
    description: Birth date as ISO 8601 date when full date is known.
    range: date
    slot_uri: schema:birthDate
  birth_source_text:
    description: Original date text from source document.
    range: string
    slot_uri: hc:sourceText
  is_inferred:
    description: Whether this date was inferred.
    range: boolean
    slot_uri: hc:isInferred
  inference_provenance:
    description: JSON documenting inference chain.
    range: string
    slot_uri: hc:inferenceProvenance
  confidence:
    description: Confidence level in the date value.
    range: string
    slot_uri: hc:confidence

enums:
  BirthDateConfidenceEnum:
    description: Confidence levels for birth date values.
    permissible_values:
      HIGH:
        description: Full date from authoritative source (e.g., birth certificate)
      MEDIUM:
        description: Date from reliable source (e.g., official biography)
      LOW:
        description: Date inferred or from uncertain source
      VERY_LOW:
        description: Decade/century estimated from indirect evidence