# =============================================================================
# Semantic Annotation Template
# =============================================================================
#
# Maps physical fields in a data contract to concepts defined in the Ontology
# Registry (ontologies.yaml). This file describes what each field *means*;
# the registry describes what each concept *is*.
#
# Use standalone or under "ontology:" in a full contract YAML. Parsed by
# pycharter.wiki.ontology.parser and validated by the Wiki ontology API.
#
# Sections:
#   1. version – Annotation version (optional but recommended).
#   2. fields  – Map of schema field name → annotation.
#
# Per-field annotation keys:
#   - concept       – Concept id from ontologies.yaml (required).
#   - tags          – Additional field-level tags (optional, supplements
#                     any tags already defined on the concept).
#   - owner         – Team or person owning this field (optional).
#   - lineage       – { derived_from?, source_system? } (optional).
#   - relationships – List of { target, type } to other fields (optional).
#
# Relationship types: references | derived_from | same_as | related_to
#   - references   : Foreign key or reference to another entity.
#   - derived_from : Field is computed from another field.
#   - same_as      : Fields represent the same concept.
#   - related_to   : General relationship.
#
# =============================================================================

version: "1.0.0"

fields:
  # ---------------------------------------------------------------------------
  # Identity / key fields
  # ---------------------------------------------------------------------------
  id:
    concept: EntityIdentifier
    tags: [identifier, primary_key]
    owner: data-engineering

  customer_id:
    concept: AccountIdentifier
    tags: [identifier, foreign_key]
    relationships:
      - target: customers.id
        type: references

  # ---------------------------------------------------------------------------
  # Descriptive fields
  # ---------------------------------------------------------------------------
  name:
    concept: EntityName

  email:
    concept: EmailAddress
    tags: [pii, contact]

  status:
    concept: LifecycleStatus

  # ---------------------------------------------------------------------------
  # Numeric / temporal fields with lineage
  # ---------------------------------------------------------------------------
  amount:
    concept: MonetaryAmount
    lineage:
      derived_from: raw_amount
      source_system: billing_service

  created_at:
    concept: CreationTimestamp
    lineage:
      source_system: application_server

  updated_at:
    concept: LastUpdateTimestamp
    lineage:
      derived_from: created_at
      source_system: application_server

  # ---------------------------------------------------------------------------
  # Nested or computed fields with relationships
  # ---------------------------------------------------------------------------
  full_name:
    concept: FullName
    relationships:
      - target: first_name
        type: derived_from
      - target: last_name
        type: derived_from

  # ---------------------------------------------------------------------------
  # Minimal example (only concept required for parsing)
  # ---------------------------------------------------------------------------
  notes:
    concept: FreeTextNote
