schema-gap-analysis

name	schema-gap-analysis
description	Lightweight linkml-validate-based check for CultureMech schema/data drift, classified along three axes (schema / instances / process). For the comprehensive audit (also scans pipeline/writers, emits TSV reports + re-runnable harness), use `audit-schema-gaps` instead.
category	quality
requires_database	false
requires_internet	false
version	2.1.0

Schema gap analysis (CultureMech)

The conceptual framework — why three axes, error-class heuristics, common anti-patterns — lives once at the cross-Mech version in claw: https://github.com/CultureBotAI/culturebotai-claw/blob/main/.claude/skills/schema-gap-analysis/skill.md

This file is the CultureMech-specific operational version. Every command below runs as-is.

When to use this skill vs. audit-schema-gaps

• schema-gap-analysis (this skill): quick linkml-validate pass + error histogram + three-axis classification. ~5–10 min start to finish. Good for "did my recent commit break something?" or onboarding.
• audit-schema-gaps (CultureMech's deeper skill): also scans src//scripts/ for writer/pipeline drift, produces five reports under reports/, emits a re-runnable scripts/validate_strict.py harness. ~30 min. Run when you suspect systemic drift or before a major release.

Same three-axis framework underneath; the deep version just covers more surface.

Setup

CultureMech uses uv-managed .venv/:

# linkml-validate ships in .venv; smoke test:
.venv/bin/linkml-validate --help

# If you get `AttributeError: Format has no attribute 'JSON'` — pin runtime:
.venv/bin/python -m pip install "linkml-runtime>=1.9,<1.10"

Procedure

1. Validate the canonical merged set

find data/merge_yaml/merged_2026 -name "*.yaml" -print0 \
  | xargs -0 .venv/bin/linkml-validate \
      -s src/culturemech/schema/culturemech.yaml \
      -C MediaRecipe \
      2>&1 | tee /tmp/cm_validate.out > /dev/null
grep -c "^\[ERROR\]" /tmp/cm_validate.out

2. (Optional) Validate the raw normalized layer

find data/normalized_yaml -name "*.yaml" -print0 \
  | xargs -0 .venv/bin/linkml-validate \
      -s src/culturemech/schema/culturemech.yaml \
      -C MediaRecipe \
      2>&1 | tee /tmp/cm_normalized_validate.out > /dev/null
grep -c "^\[ERROR\]" /tmp/cm_normalized_validate.out

3. Histogram the errors

grep -oE "Additional properties are not allowed \('[^']+'" /tmp/cm_validate.out \
  | sort | uniq -c | sort -rn

grep -oE "'[^']+' is a required property" /tmp/cm_validate.out \
  | sort | uniq -c | sort -rn

grep -oE "does not match '[^']+'" /tmp/cm_validate.out \
  | sort | uniq -c | sort -rn

grep -oE "is not a '[^']+'" /tmp/cm_validate.out \
  | sort | uniq -c | sort -rn

4. Cross-check generator drift (Axis 3)

# Naive datetimes
grep -rnE 'datetime\.now\(\)\.isoformat\b' \
  src/ scripts/ --include='*.py' | grep -v "timezone"

# yaml.dump that drops collection metadata (CultureMech keys: media/recipes)
grep -rnE 'yaml\.dump\(\s*\{\s*["\047](media|recipes)["\047]\s*:' \
  src/ scripts/ --include='*.py'

# Smoking-gun greps for known classes (see history table below)
grep -rn '"date":\|\bcuration_history\b.*[^a-z]date\b' \
  src/ scripts/ --include='*.py' | head -10
grep -rn '"instruction":' src/ scripts/ --include='*.py' | head -10
grep -rn '"reference_id":' src/ scripts/ --include='*.py' | head -10

5. Re-validate after fixes

find data/merge_yaml/merged_2026 -name "*.yaml" -print0 \
  | xargs -0 .venv/bin/linkml-validate \
      -s src/culturemech/schema/culturemech.yaml \
      -C MediaRecipe \
      2>&1 | grep -c "^\[ERROR\]"
# target: 0

CultureMech-specific gap classes (current state, 2026-05-17 pass)

Count	Error	Axis	Fix
1,195	Additional properties are not allowed ('date') + 'timestamp' is a required property in curation_history[]	Process	Rename emit: date → timestamp. Use datetime.now(timezone.utc).isoformat(). Then migrate the 1,195 records.
126	Additional properties are not allowed ('instruction') + 'description' + 'action' required in preparation_steps[]	Process	Rename emit: instruction → description. Ensure action is populated (likely MIX/ADJUST_PH/AUTOCLAVE enum default).
119	'concentration' is a required property in ingredients[]	Schema or instance — needs inspection	If solid-medium ingredients legitimately lack concentration, relax schema to recommended. If a writer drops it, fix the writer.
28	Additional properties are not allowed ('reference_id') + 'reference' is a required property in references[]	Process	Rename emit: reference_id → reference.

Total: 2,943 errors across 4,289 records (2026-05-17). Same data, deeper audit is in reports/ (run /audit-schema-gaps for that).

Pointers

• Schema: src/culturemech/schema/culturemech.yaml
• Custom validator (tolerant): src/culturemech/validation/validator.py
• Renderer (writes to pages/, not validated YAML): src/culturemech/render_media_pages.py
• Deeper audit skill: .claude/skills/audit-schema-gaps/SKILL.md
• Cross-Mech framework + new-Mech bootstrap template: claw/.claude/skills/schema-gap-analysis