Skip to content
Sources: data/reference/json/ccb_json_object_types.json tools/json_api/contract-inventory.schema.json tools/json_api/generate_contracts.py tools/json_api/test_generate_contracts.py src/init.cpp src/generic_factory.h tests/json_load_test.cpp doc/JSON/JSON_INHERITANCE.md doc/JSON/JSON_STYLE.md commit c663ceb2c1bd api-contract

JSON validation and evidence levels

Different checks prove different facts. Do not report “parses” as “fully loads,” and do not use lexical occurrence counts as evidence that a field is required.

  1. Run the repository JSON formatter to prove canonical project formatting.
  2. Regenerate contract inventories and run their Schema, count, source-location, and example-pointer tests.
  3. Run json-check. The current chkjson checks object/array syntax and a top-level string type under data/json; it is not a full semantic invocation of every loader.
  4. Build the test program. Test startup loads core/test data; then run focused Catch2 tests for the type.
  5. For an external mod, load it in a real CCB executable and test world; record version, dependencies, and logs.

Run these from the CCB source root:

# validation: json-contract
python3 tools/json_api/generate_contracts.py --check
python3 -m unittest discover -s tools/json_api -p 'test_*.py'
# validation: json-load
make -j2 json-check

Evidence levels

Marker What it proves What it does not prove
mandatory / optional Explicit field-read evidence in a loader Every conditional and cross-field constraint
partial A subset of the contract is classified That omitted fields are safe or optional
unclassified No publishable source classification yet That the field does not exist
lexical_only Matching text exists in data or legacy prose A minimal valid example, requiredness, or equal semantics
schema: none No general validator-backed Schema is recorded That the loader performs no validation

The generator reads only tracked paths returned by git ls-files and pins coverage at 190/275/306. Count changes must accompany registry/parser changes and a generated diff. Never edit the generated inventories or generated reference pages by hand.