improve schema for scalability and maintainability

[chaithubk]

The Solution: Separation of Concerns

1️⃣ Schema stays LEAN — vitals.schema.json
2️⃣ Governance lives in manifest — vitals.schema-manifest.yml

domain: vitals
current_version: "2.1.1"
compatibility_class: PATCH

breaking_changes_from:
  "2.0.0":
    - field: creatinine
      migration: "Publishers must compute creatinine..."

✅ Explicitly documents breaking changes, migration guides, upgrade paths

3️⃣ Release notes in changelog — CHANGELOG.md

## [2.1.1] - 2026-05-10
### Compatibility
PATCH (documentation-only)

✅ Humans read this for release notes; CI validates consistency

What's New

File	Purpose
SCHEMA-VERSIONING.md	Quick reference for consumers/publishers

How Consumers Use It

# 1. Extract version from payload
version = payload['version']  # "2.1.1"

# 2. Load version-specific schema from Git tag
schema = git_show(f'v{version}:schemas/vitals/vitals.schema.json')

# 3. Validate payload
ajv.validate(payload, schema)

# 4. Check upgrade safety (if upgrading)
manifest = yaml.load(open('schemas/vitals/vitals.schema-manifest.yml'))
if manifest['breaking_changes_from']['2.0.0']:
    print("⚠️ Upgrade requires code changes")

For Multi-Domain Scalability (Future)

Each domain gets:

• schemas/domain/domain.schema.json (clean payload schema)
• schemas/domain/domain.schema-manifest.yml (governance)
• schemas/domain/DOMAIN-CHANGELOG.md (release notes)

All domains share:

• VERSION (global SemVer)
• CHANGELOG.md (unified releases)
• compatibility_guard.py (validates all domains)