The Work Zone Data Exchange (WZDx) Specification aims to make harmonized work zone data provided by infrastructure owners and operators (IOOs) available for third party use, making travel on public roads safer and more efficient through ubiquitous access to data on work zone activity.
Creative Commons Zero v1.0 Universal
92
stars
62
forks
source link
There should be a way to have a link to a static spec #371
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.
Summary
Right now, all the specs have hardcoded references to the
mainbranch, for example:https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.2/WorkZoneFeed.jsonI 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.jsonThen instead of changing stuff in
schemas/4.2, add a directory likeschemas/nextor something, and in that use links to themainbranch so there is a unified "development" schema.Then every release commit is to copy the
schemas/nexttoschemas/4.3(or whatever) and replace the URLs.Relative $refs
Instead of hardcoding a full URL, just have relative references in the
$reffields, like"$ref": "./FeedInfo.json"See example here: https://github.com/mtfurlan/wzdx/blob/test/relative/schemas/4.2/WorkZoneFeed.jsonThis 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
$iddisagrees 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