Proposed JSON Spec and Tools

[ericlucit]

Warning - This is a massive change.

The overall "why" is a machine readable source of this data. So 3rd parties can easily pull in changes when this spec updates.

Objective The objective of this change is to introduce

• A json source of truth
• A better method for organizing versioned spec files
• A tool for generating the human readable markup .md files from the json source

Changes

• Most files in the root directory of the repo have moved into sub-directories.
• Versions of the spec live in versioned sub-directories specification/1.0/, specification/1.1/, etc.
• The most current version of the spec lives in specification/specification.json

Tools

• This change introduces a build tool (Requires docker and probably...wsl although it might work from a windows shell)

Process Changes Future spec pull requests should be made to the specification/x.y/specification.json file - Changes made to older files, or the primary spec, should be rejected

The README Note that the README has been updated with instructions on using the build tool.

[ericlucit]

TLDR

Any 3rd party client that wants to injest the specification can just fetch :

https://raw.githubusercontent.com/openooh/venue-taxonomy/main/specification/specification.json

And if you want a specific version of the spec?

https://raw.githubusercontent.com/openooh/venue-taxonomy/main/specification/1.1/specification.json

[kaveet]

@ericlucit thanks for your work here. Do you see room in your proposal to include the use of draft branches, tagging, and releases in the repo? I find that version-tagged releases would be a better fit than maintaining versioned directories for every release.

https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

The consumer would then just need to pull:

https://github.com/openooh/venue-taxonomy/releases/latest/download/specification.json

or:

https://github.com/openooh/venue-taxonomy/releases/v1.1.0/download/specification.json

Perhaps too GitHub-specific?

[ericlucit]

@ericlucit thanks for your work here. Do you see room in your proposal to include the use of draft branches, tagging, and releases in the repo? I find that version-tagged releases would be a better fit than maintaining versioned directories for every release.

https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

The consumer would then just need to pull:

https://github.com/openooh/venue-taxonomy/releases/latest/download/specification.json

or:

https://github.com/openooh/venue-taxonomy/releases/v1.1.0/download/specification.json

Perhaps too GitHub-specific?

I agree! - This would simplify the build tool as well as it wouldn't necessarily have to be aware of the version as long as work was being done in branches...