Extract specification snippets as standalone JSON files (latest) #110
Conversation
|
Nice @sbesson !
My first impression is that this is a really idea. Better to have to think about existing examples when making changes than to forget about them! I'll look more carefully next week |
latest/schemas/strict_image.schema
Outdated
| "$id": "https://ngff.openmicroscopy.org/0.4/schemas/strict_image.schema", | ||
| "allOf": [ | ||
| { | ||
| "$ref": "https://ngff.openmicroscopy.org/0.4/schemas/image.schema" |
There was a problem hiding this comment.
Do these IDs get updated directly to /0.5/ at this point? (don't need to use /latest/, right?)
NB: I notice that https://ngff.openmicroscopy.org/0.4/schemas/image.schema is 404, so this schemas won't work without the custom resolver used in the tests.
There was a problem hiding this comment.
No you are correct, I didn't do the update work as I was waiting to get a consensus about the value of adding these scneas.
A few comments:
- definitely need to replace
0.4. I would not use0.5as that would communicate a released schema and that has the potential of creating confusion.latestwould be an option or maybe something that explicitly says this is a development schema e.g.0.5dev? - the individual
versionelements in the JSON snippets/examples will likely need to be updated to follow the same convention - the release process will need to be amended to include these steps
|
Pushed another commit using |
|
|
|
https://api.csswg.org/bikeshed/?url=https://raw.githubusercontent.com/sbesson/ngff/json_snippets_latest/latest/index.bs continues to look good. There are still a few to the header will lead to replacement. This unfortunately does not work for the |
|
Created a text macro to manage the replacements (all the other usages of 0.4 are legit and refer either to the stable version and/or to the version history). Also replaced the versions in the JSON snippets manually. My intent once this is merged is to extract all included code blocks into standalone JSON files so that we can validate them via JSON schemas and include them in the spec. |
| } | ||
| ], | ||
| "coordinateTransformations": [{ | ||
| // the time unit (0.1 milliseconds), which is the same for each scale level |
There was a problem hiding this comment.
Are these comments valid JSON? Do they cause any issues? (I see they are the same as this under 0.4/)
There was a problem hiding this comment.
from #98 (comment)
a new Document conventions section is added to the specification which ... clarifies the explanation scope of the comments in the JSON snippets
|
Any objections to moving forward with this? |
|
GFI 👍 |
|
looks good to me |
…test Extract specification snippets as standalone JSON files (latest) SHA: caa7e8e Reason: push, by @joshmoore Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Follow-up of #98, this ports the additions made to the 0.4 specification i.e. the extraction of the JSON snippets and new DOcuments conventions paragraph to the
latestspecification.Additionally, 0765b4d and ff936b8 proposes to add the rest of the validation infrastructure i.e. the JSON schemas and the validation tests run as part of the CI to the
latestsubfolder.From my perspective, the secondary benefit of adding this infrastructure is to make the JSON examples and schemas truly first-class citizens of upcoming NGFF proposals made against
latest. The primary downside is that it might introduce some friction for instance if multiple features are under development. Interesting to hear what people who proposed the next set of breaking changes of the specification feel about this approach especially @bogovicj (#94) and @joshmoore (#104).