elastic / elastic/package-spec

Document (and increase) JSON Schema compatibility

Open
#100 4 comments 0 reactions 0 assignees View on GitHub
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`**
Screen Shot 2020-12-21 at 1 50 11 PM

**Property name typo**
Screen Shot 2020-12-21 at 1 50 25 PM

**missing required fields**
Screen Shot 2020-12-21 at 1 50 37 PM

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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.