sv-witnesses
sv-witnesses copied to clipboard
Combined schema for YAML witnesses
Changes
- Replace
loop_invariant
schema with a combined schema that also specifiesloop_invariant_certificate
. - Add descriptions to schema.
- Extract reusable
$defs
in schema to simplify new entry type specification (c.f. https://github.com/sosy-lab/sv-witnesses/pull/59#discussion_r894263041). - Remove hand-written descriptions from README.
- Add GitHub Actions workflow for automatically generating and deploying HTML documentation from schema. Result in my fork: https://sim642.github.io/sv-witnesses/yaml/.
TODO
- [x] Review/complete descriptions which need to be generic (not
loop_invariant
specific) in$defs
. - [x] Fix format inconsistencies between README and schema.
- [ ] Specify
location_invariant
from #59? - [x] Add long descriptions to schema.
- [x] Change workflow branch before merge.
There are tools that can convert JSON schemas to human-readable HTML/Markdown documentation, e.g. https://github.com/coveooss/json-schema-for-humans. So here's a radical idea: ditch the fine-grained specifications in YAML README and only maintain the schema as the authoritative source. Markdown documentation could be generated from it (instead of manually having to keep the two in sync) and more interactive HTML documentation could be generated (and automatically published to this repository's GitHub Pages). Thoughts?