executable interface to openapi document validation

[karenetheridge]

Create a shell-executable wrapper that loads an openapi document from json or yaml and provides information about the data therein.

• validation: if the document is invalid, clearly state what the errors are
• information: (assuming the document is valid), dump information like:
  • number of paths, webhooks, other high level objects
  • number of operations under paths, webhooks
  • linting items, that are not strictly "wrong" but might lead to issues at runtime:
    • any unresolved $refs (that point to external documents): identify the uri(s) of these external refs
    • $refs that point to the wrong entity type
    • missing path parameter definitions
    • ...

Also we can do some static analysis to try to predict some runtime issues, e.g. unresolved $refs that would point to this internal document (therefore they obviously can never resolve).

[karenetheridge]

duped by #89:

openapi-inspect <document>

• instantiate a JSMDO object from the document, as OM does.
• dump any validation errors that occurred
• --silent mode: return 0 for no errors, -1 for errors.
• --verbose mode: also return some data about the document:
  • number of path-items
  • number of operations
  • number of tags?
  • number of references that go outside the document (and list the document names of each - i.e. all the URIs without fragment)

[karenetheridge]

Right now validation can be done using the existing JSON Schema evaluator, e.g.:

json-schema-eval --schema schema.json --data openapi-document.yaml

..where schema.json is the contents of (at the time of this writing): https://spec.openapis.org/oas/3.1/schema/2025-08-31

...but a better wrapper should be provided that doesn't require providing the default OAD schema.

[karenetheridge]

This is largely available now (minus some features described above) as of version 0.110.