elastic / elastic/package-spec
Document (and increase) JSON Schema compatibility
- Dominant language
- Go
- Stars
- 20
- Forks
- 93
- Avg merge
- 15h 10m
- Merged PRs (30d)
- 12
Description
## Document the JSON Schema compatibility
There are mentions in [the README](https://github.com/elastic/package-spec#specification-format) and [code comments](https://github.com/elastic/package-spec/blob/ec2b9a5c0801936102ca91b030d3cc94ea844c73/versions/1/manifest.spec.yml#L5) about JSON Schema compatibility but I didn't see any information about particular schema version(s).
After looking around a bit , I found
* `examples` keyword, which [was introduced in `Draft-06`](https://json-schema.org/draft-06/json-schema-release-notes.html#additions-and-backwards-compatible-changes)
* `contentMediaType` keyword, which [was introduced in `Draft-07`](https://json-schema.org/draft-07/json-schema-release-notes.html#keywords)
* no uses of features like `id` vs `$id` which are [backwards-incompatible with `Draft-04`](https://json-schema.org/draft-06/json-schema-release-notes.html#backwards-incompatible-changes)
* no uses any [`2019-09` features](https://json-schema.org/draft/2019-09/release-notes.html) like `$defs` or `$vocabulary`
Based on that, it seems it's functionally at `Draft-07`. Which leads to the next part.
## Increase the JSON Schema compatibility
When I was working on https://github.com/elastic/package-spec/issues/96 it was difficult to use existing JSON Schema tooling because of it being _just_ different enough. e.g. the top-level `spec` property, `file` and `folder` values for `type`, etc.
I believe we can write the spec for our `*spec.yml` files in JSON Schema and get back into the JSON Schema tooling ecosystem.
e.g. something like `spec.schema.yml` is a JSON Schema which defines what a `spec.yaml` file may look like. I took a [quick-and-dirty pass at this](https://gist.github.com/jfsiii/d8076c147e8337cf3c193042ed1c5f86)
Based on that, we can validate that
* the schema is valid `Draft-07` https://www.jsonschemavalidator.net/s/uyODryKJ
* a given `spec.yaml` does validate against the `spec.spec.yml` schema: https://www.jsonschemavalidator.net/s/su8brQMk
screenshots showing issues it prevents
**Can't use `contentMediaType` for a `folder`**

**Property name typo**

**missing required fields**

I didn't get to trying this with `manifest.spec.yaml` files but it seems reasonable or worth exploring.
What do others think?
Contributor guide
Assessment
This issue has not been assessed yet.