There should be a way to have a link to a static spec

[mtfurlan]

Summary

Right now, all the specs have hardcoded references to the main branch, for example: https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.2/WorkZoneFeed.json

I want some way to link to a static and unchanging version of a spec.

Motivation

This causes issues if someone wants a static link to a specific spec.

For example, when this commit happened, my CI started saying that I broke my toolchain because the thing bundling the openapi spec that includes a WZDx WorkZoneFeed generated different output.

Proposed change options

hardcode tags in

Instead of having the spec link to the main branch, link to a release tag, for example: https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/v4.2/schemas/4.2/WorkZoneFeed.json

Then instead of changing stuff in schemas/4.2, add a directory like schemas/next or something, and in that use links to the main branch so there is a unified "development" schema.

Then every release commit is to copy the schemas/next to schemas/4.3(or whatever) and replace the URLs.

Relative $refs

Instead of hardcoding a full URL, just have relative references in the $ref fields, like "$ref": "./FeedInfo.json"
See example here: https://github.com/mtfurlan/wzdx/blob/test/relative/schemas/4.2/WorkZoneFeed.json

This means you can reference a spec by branch or commit or tag or whatever, and it should work out fine (at least the redocly-cli can bundle it)

I'm not sure what happens if $id disagrees with where it was fetched from, so I took it out for the test in my fork.

Looking over the latest JSON schema RFC, I'm not sure this is a great approach because

The root schema of a JSON Schema document SHOULD contain an "$id" keyword