Add schema resolution and comparison tools

[smrgeoinfo]

Summary

• tools/resolve_schema.py — Recursively resolves all $ref references from modular YAML/JSON source schemas into a single fully-inlined, self-contained JSON Schema. Handles relative paths, fragments, cross-file fragments, and bblocks:// URI cross-building-block references (via bblocks-config.yaml identifier-prefix).
• tools/compare_schemas.py — Compares schema.yaml source files against companion JSON schemas for each building block, reporting structural inconsistencies (missing properties, type mismatches, constraint differences, description drift). Skips expected $ref path differences.
• tools/README.md — Usage documentation with examples, option reference tables, and comparison with bblocks-postprocess.

Motivation

The bblocks-postprocess Docker tool generates annotated schemas in build/annotated/, but these still contain $ref references to remote URLs. There is currently no standard way for building block authors to produce a fully-resolved, self-contained JSON Schema suitable for local validation, tooling integration, or inspection. These tools fill that gap as lightweight standalone Python scripts.

Key features

• Works with both flat (_sources/myBlock/) and nested (_sources/category/myBlock/) directory layouts
• Auto-discovers building blocks via bblock.json presence
• Resolves bblocks:// cross-building-block references locally (including #/$defs/ fragment pointers)
• Auto-detects _sources/ directory relative to script location or CWD
• Only dependency: pyyaml

Testing

Tested against:

• opengeospatial/bblocks — 12 building blocks indexed, all local bblocks:// refs resolved (including $defs fragment refs like bblocks://ogc.ogc-utils.iri-or-curie#/$defs/MultipleOrObjectOrNull)
• bblock-template itself — resolves mySchema and myFeature example building blocks
• A production repo with 101 building blocks — compare_schemas.py checks 100 YAML/JSON pairs, all consistent

Test plan

• Run python tools/resolve_schema.py --bblock mySchema from the template repo root
• Run python tools/compare_schemas.py from the template repo root
• Clone opengeospatial/bblocks and run python tools/resolve_schema.py --bblock feature --sources-dir registereditems
• Verify bblocks:// refs resolve correctly (e.g., topology references iri-or-curie)

🤖 Generated with Claude Code