# =============================================================================
# Metadata Template
# =============================================================================
#
# Business and governance metadata for your data contract.
# All sections are optional unless noted. Use standalone or under "metadata:"
# in a full contract YAML.
#
# Sections (in order):
#   1. Identity    – title, version, status, type, description
#   2. Audit      – created_at, updated_at, created_by, updated_by
#   3. Ownership  – single object (business_owners, bu_sme, it_*, support_lead, primary)
#   4. Domain     – domain / domains
#   5. Lineage    – single object (pulls_from, pushes_to, system_sources)
#   6. Runtime    – storage_locations, serve, environments (where/how data is stored and served)
#   7. Lifecycle  – state_machine_name, state_field (for FSM-bound entities)
#   8. Data       – data_quality, governance_rules, changelog
#
# =============================================================================

# -----------------------------------------------------------------------------
# 1. Identity
# -----------------------------------------------------------------------------
title: my_entity              # Required for DB; pattern: ^[a-z0-9_]+$
version: "1.0.0"
status: active                # active | deprecated | draft
type: object                  # e.g. object, domain_entity
description: Description of what this data represents

# -----------------------------------------------------------------------------
# 2. Audit
# -----------------------------------------------------------------------------
created_at: "2025-01-01T00:00:00Z"
updated_at: "2025-01-01T00:00:00Z"
created_by: your_username
updated_by: your_username

# -----------------------------------------------------------------------------
# 3. Ownership
# -----------------------------------------------------------------------------
# All ownership and stakeholder roles in one section. Lists are owner IDs
# (join tables to owners). Primary owner fields are optional.
ownership:
  business_owners:
    - team-name
    - owner-email@company.com
  bu_sme: []
  it_application_owners: []
  it_sme: []
  support_lead: []
  # Primary owner (optional)
  contract_owners: 
    - data-science-team
    - data-engineering-team

  additional_info: {}

# -----------------------------------------------------------------------------
# 4. Domain
# -----------------------------------------------------------------------------
domain: domain_name
# domains: [domain1, domain2]

# -----------------------------------------------------------------------------
# 5. Lineage
# -----------------------------------------------------------------------------
# Upstream/downstream and system sources in one section.
lineage:
  pulls_from:
    - source_system_1
    - source_system_2
  pushes_to:
    - destination_system_1
  system_sources:
    - origin_system

# -----------------------------------------------------------------------------
# 6. Runtime (storage, serve, environments)
# -----------------------------------------------------------------------------
# Where and how this data is stored and served. Optional.
# - storage_locations: join table to storage_locations (names or {name, usage_type})
# - serve: API endpoint and params (stored in payload; may be mirrored to governance_rules)
# - environments: list of environment names (join table to environments)
runtime:
  storage_locations: []
  # Example: [ { name: my-s3-bucket-path, usage_type: primary }, { name: replica-table, usage_type: replica } ]
  serve:
    api:
      type: GET
      endpoint: /v1/my-entity
      rate_limit: "120/min"
      cache_ttl: 3600
      params:
        - name: id
          in: query
          required: false
          description: Filter by ID
          schema: { type: string }
  environments: []
  # Example: [development, staging, production]

# -----------------------------------------------------------------------------
# 7. Lifecycle (FSM binding for domain entities, e.g. PyStator)
# -----------------------------------------------------------------------------
# Optional. When present, this entity type is governed by a state machine.
# Align with your FSM engine (e.g. PyStator): machine name/version, which
# field holds the entity id for API calls, and which field holds current state.
# Stored in governance_rules.lifecycle when persisting to DB if not at root.
lifecycle:
  # Required. Must match FSM meta.machine_name (e.g. PyStator trading_machines).
  state_machine_name: order_lifecycle
  # Optional. FSM machine version (e.g. "1.0.0"); if omitted, engine uses latest.
  machine_version: "1.0.0"
  # Field on the entity record that holds current FSM state. Schema enum should
  # match the FSM state names (e.g. OPEN, FILLED, CANCELED). Default: status.
  state_field: status
  # Field on the entity record used as entity_id in FSM APIs (e.g. order_id,
  # run_id). Used when calling e.g. POST /entities/{entity_id}/events.
  entity_id_field: order_id

# -----------------------------------------------------------------------------
# 8. Data quality, governance, changelog
# -----------------------------------------------------------------------------
data_quality:
  accuracy: 0.0
  monitoring_enabled: false
  sla: null
  total_records: 0
  last_updated: "2025-01-01T00:00:00Z"

governance_rules:
  data_retention:
    days: 365
    reason: Standard retention policy
  pii_fields:
    fields: []
  sensitivity: internal    # internal | confidential | restricted | public
  access_control:
    read:
      - data-team
      - analytics-team
    write:
      - data-team

changelog:
  - version: "1.0.0"
    date: "2025-01-01T00:00:00Z"
    author: your_username
    type: initial
    changes:
      - Initial contract creation
