sv-witnesses icon indicating copy to clipboard operation
sv-witnesses copied to clipboard

Combined schema for YAML witnesses

Open sim642 opened this issue 2 years ago • 6 comments

Changes

  1. Replace loop_invariant schema with a combined schema that also specifies loop_invariant_certificate.
  2. Add descriptions to schema.
  3. Extract reusable $defs in schema to simplify new entry type specification (c.f. https://github.com/sosy-lab/sv-witnesses/pull/59#discussion_r894263041).
  4. Remove hand-written descriptions from README.
  5. 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?

sim642 avatar Jun 13 '22 17:06 sim642