Schema definitions!
This is kind of a /dev
issue and partly /infra
.
We've defined a schema definition (using JSON Schema) for docs-books and are in the process of defining one for APIv3 (using OpenAPI)
To work out and be useful for validating docs files and/or providing documentation and client generation options for the API these docs should be hosted somewhere (ideally using something like schema.civicrm.org/v1/docs-book.json
.
We can then reference these schemas for validation of their respective files or in the case of OpenAPI to generate client implementations programmatically.
So onto the "ask". I think the ideal hosting place is to use a repo on GitLab (somewhere?) ideally with GitLab pages enabled and the domain schema.civicrm.org
connected to it. There are additional schemas that would be useful - extension info.xml files could have a schema to allow validation. Essentially any structured data file can be validated with a schema and it's a useful way to document the available options in the file.
Currently planned schemas include:
- Docs Books
- APIv3
- Extension info.xml
Pinging @bgm, @totten & @seamuslee