Merge output schema into single file and check into git by jack-berg · Pull Request #425 · open-telemetry/opentelemetry-configuration (original) (raw)

Possibly solves #422. I alluded to this in a comment here.

There are a variety of advantages to publishing a single single JSON schema file and checking it into git:

• Maintaining source schema in YAML has its advantages, but one big disadvantage is that it obfuscates how changes actually manifest in the resolved JSON schema. Like schema-docs.md, this helps make the impact of changes obvious.
• It can be annoying to configure JSON schema tooling to be able to properly resolve $refs across files. With everything in one file, configuring tooling couldn't be easier.
• Without the compiled JSON schema committed to git, its more difficult to test out changes in an implementation. I need to update my implementation to point to a ref, download opentelemetry-configuration at the ref, run make compile-schema, and have my implementation point to ./schema_out. Much easier if every ref has the fully compiled schema checked into source code in a single file.
• Makes publishing easier because we don't need to compile / zip / attach the schema to the release. Its always available at the ref.

It makes schema changes a bit noisier in terms of diff, but If we can tolerate keeping schema-md.doc checked into git, we can tolerate this.