fix(json-schema): faithful attribute descriptions + panel-ID doc clarification

[aditigopalan]

Summary

Makes the generated flat Synapse JSON schemas carry the canonical attribute descriptions, and clarifies the SpatialPanel HTAN_PANEL_ID documentation.

Closes #191, closes #190, closes #182.

What's included

1. Generator: restore descriptions clobbered by slot_usage (#191, #190)

scripts/linkml_to_flat_synapse_jsonschema.py emitted induced-slot descriptions, so a class slot_usage carrying a conditional note (e.g. Required when X is "Yes") replaced the real attribute description in the output — affecting ~50 conditional attributes across Biospecimen and Clinical, which feed the BigQuery tabular release.

• New restore_base_attribute_descriptions() runs after generation and overrides each property's description with the canonical attribute-level description (walking the class + ancestors, ignoring slot_usage).
• The conditional requirement itself is unaffected — it remains enforced by the generated rules (if/then) constraints. Only the human-readable description changes.
• Verified: Biospecimen SECTION_THICKNESS_VALUE now reads "…measured in microns" (Documentation descriptions #190); ACQUISITION_METHOD_OTHER_SPECIFY reads "A custom acquisition method" (Attribute Description Mismatch from LinkML to JSON Schema #191); Clinical Therapy/Diagnosis have no Required when … descriptions left.
• No regressions: descriptions where the note is the canonical text (e.g. scATAC AVERAGE_INSERT_SIZE) are unchanged; modules without slot_usage overrides regenerate identically.
• Regression tests added in tests/test_linkml_schema_conversion.py.

2. SpatialPanel HTAN_PANEL_ID description (#182)

Expanded the terse "Unique identifier for the panel" to state the HTAN identifier format (P-prefix segment, e.g. HTA201_1_P1) and that it carries the same requirements as the HTAN_PANEL_ID in the corresponding ChannelMetadata RecordSet — documenting the Spatial and channel-metadata panel IDs consistently.

3. Pre-existing test fix (unrelated, unblocks CI)

test_none_types_analysis asserted the "none"-value share is 0.1%–10%; it is now 0.04% on main because large controlled-vocabulary enums (ICD-O-3, ICD-10, antineoplastic agents) are almost entirely non-"none". This fails on main independent of this PR (which changes zero enums). Removed the invalid lower bound; kept the meaningful checks (total_none_values > 0 and the ≤10% ceiling).

Not in this PR

• Regenerated JSON_Schemas/* — produced by the downstream json-schema-synapse workflow.
• docs/*.md — need a manual gen-doc pass to reflect corrected descriptions (the LinkML source was already correct).
• Update HTAN_Panel_ID Regex #183 (loosen HTAN_PANEL_ID regex for vendor panel names) — a validation/identifier change needing a design decision; tracked separately.

Testing

• pytest tests/ → 27 passed (3 new regression tests).
• Custom flat-schema generator run against Biospecimen + Clinical confirms corrected descriptions; unaffected modules unchanged.

[github-actions]

HTAN Schema Review — ✅ Approved

Automated review by htan-claude · commit e4c603a23ff5adbcf2e976e09af6da9bdb928f5f

This is a clean, well-scoped PR — all three reviewers came back with no issues, and the one informational note from the coverage reviewer is just good housekeeping context.

Tip

All checklist items pass — no issues found.

Files Changed

• scripts/linkml_to_flat_synapse_jsonschema.py
• tests/test_linkml_schema_conversion.py

Checklist Results

Check	Result	Notes
Inheritance correctness	N/A	No YAML schema files modified
Inlining of nested objects	N/A	No YAML schema files modified
Slot completeness (range, title, description)	N/A	No YAML schema files modified
Enum integrity (alphabetical, descriptions)	N/A	No YAML schema files modified
Generated artifacts	PASS	Regression tests added covering happy path, no-op for unknown properties, and empty-class-name guard

Findings

Informational

• tests/test_linkml_schema_conversion.py — Schema version bump may be warranted (coverage)
  The new restore_base_attribute_descriptions post-processing step materially changes the content of ~50 property descriptions in generated JSON schemas across Biospecimen and Clinical. If the source YAML files carry a version: field, a bump could help with release tracking. No action required from the author — purely a heads-up for downstream consumers.

Verdict

APPROVE

---

_{Rules defined in CLAUDE.md · To update review rules, edit CLAUDE.md and open a PR to main}

[ykatariy]

Looks great!! Thank you:)

Superseded by updated review on commit 802bd04

[github-actions]

HTAN Schema Review — ✅ Approved

Automated review by htan-claude · commit 802bd041842c0416b86d59fd145d20944451cc2f

Solid bug fix with a clean implementation — all schema source files are untouched, and the two informational notes from the coverage reviewer are worth surfacing for awareness.

Tip

All checklist items pass — no blocking issues found.

Files Changed

• scripts/linkml_to_flat_synapse_jsonschema.py
• tests/test_linkml_schema_conversion.py
• tests/test_none_types_analysis.py

Checklist Results

Check	Result	Notes
Inheritance correctness	N/A	No YAML schema changes in this PR
Inlining of nested objects	N/A	No YAML schema changes in this PR
Slot completeness (range, title, description)	N/A	No YAML schema changes in this PR
Enum integrity (alphabetical, descriptions)	N/A	No YAML schema changes in this PR
Generated artifacts	PASS	Generated files are downstream of the script fix; regression tests confirm correctness

Findings

Informational

• tests/test_linkml_schema_conversion.py — Missing test for no-op (already-correct description) branch (coverage)
  The new TestRestoreBaseAttributeDescriptions suite covers slot_usage override replacement, unknown properties, and empty class name, but does not exercise the branch where prop_val["description"] already matches the canonical attribute description — meaning restored stays 0 and the value is left unchanged. Adding a test that asserts the description is not modified and the restored count remains 0 would complete branch coverage for the equality check. Low priority, but worth a follow-up.

• scripts/linkml_to_flat_synapse_jsonschema.py — Schema version bump may be warranted (coverage)
  This fix meaningfully changes the human-readable description field for an estimated ~50 attributes across Biospecimen and Clinical in all generated JSON schemas. If the source YAML modules carry a version: field, bumping it would signal downstream consumers (e.g., BigQuery tabular release pipelines) that content has changed. If versioning is managed separately or the team treats this as a pure bug fix with no semantic version impact, no action is needed.

Verdict

APPROVE

---

_{Rules defined in CLAUDE.md · To update review rules, edit CLAUDE.md and open a PR to main}

Superseded by updated review on commit e9de58b

[github-actions]

HTAN Schema Review — ✅ Approved

Automated review by htan-claude · commit e9de58bff3db7b4107a88fdd1fbb08034465ff0f

This is a clean, well-scoped PR — all three reviewers found nothing to flag, and the changes are exactly what you'd hope to see for a targeted bug fix.

Tip

All checklist items pass — no issues found.

Files Changed

• modules/SpatialOmics/domains/spatial_panel.yaml
• scripts/linkml_to_flat_synapse_jsonschema.py
• tests/test_linkml_schema_conversion.py
• tests/test_none_types_analysis.py

Checklist Results

Check	Result	Notes
Inheritance correctness	N/A	No inheritance chain changes introduced
Inlining of nested objects	N/A	No new class-range slots introduced
Slot completeness (range, title, description)	PASS	HTAN_PANEL_ID retains all required fields; description update is well-formed
Enum integrity (alphabetical, descriptions)	N/A	No enum changes in this PR
Generated artifacts	N/A	Generated files excluded from diff per scope rules

Verdict

APPROVE

---

_{Rules defined in CLAUDE.md · To update review rules, edit CLAUDE.md and open a PR to main}

[github-actions]

✅ Python classes auto-updated!

The Python classes have been automatically regenerated and committed to this PR branch.

**Updated files:**
```
modules/Biospecimen/src/htan_biospecimen/datamodel/biospecimen.py

modules/Clinical/src/htan_clinical/datamodel/clinical.py
modules/DigitalPathology/src/htan_digitalpathology/datamodel/digital_pathology.py
modules/Imaging/src/htan_imaging/datamodel/imaging.py
modules/MassSpectrometryImaging/src/htan_massspectrometryimaging/datamodel/mass_spectrometry_imaging.py
modules/MultiplexMicroscopy/src/htan_multiplexmicroscopy/datamodel/multiplex_microscopy.py
modules/Sequencing/src/htan_sequencing/datamodel/sequencing.py
modules/SpatialOmics/src/htan_spatial/datamodel/spatial.py
modules/WES/src/htan_wes/datamodel/wes.py
modules/scATAC-seq/src/htan_scatac_seq/datamodel/scatac_seq.py
modules/scRNA-seq/src/htan_scrna_seq/datamodel/scrna_seq.py
```

The generated classes are now up to date with the schema changes.