Specify draft via $schema in JSON schema #153
Conversation
dhimmel
changed the title
|
Can you point to some documentation that this is the proper way to indicate the draft version?
While indicating the draft version would obviously be a good thing, we might want to make sure we also apply this change in the release branches, instead of just in master, which we use for development. |
Disclaimer, I'm not an expert on JSON Schemas (the CSL one is the first I've ever used). This is how I saw it done in several schemas as well as the jsonschema python parser. Also this is what the official draft 3 meta schema uses. Here's the documentation of
Regarding
I think you mean release tags (not branches), as I don't see any release branches in this repo. I would think it's best not to change a release once it's been released, but to release a new patch number as per semantic versioning. For example, our changes could go into release 1.0.2 or perhaps 1.1.0 (if they warrant a minor release). |
Ah, right (we do have branches at https://github.com/citation-style-language/documentation for the various CSL releases). We might want to re-license the original CSL 0.8.1, 1.0, and 1.0.1 schemas, though, instead of just future releases, so we might want to create branches at the current tags (and retag the tips of those branches). |
Cherry-picks first two commits from citation-style-language#153
|
I'd recommend a branch for each MAJOR.MINOR combination that is still receiving new PATCH releases. I wouldn't change a tag to refer to a different commit once it has been published, as that could be destructive to some users who expect a certain release to never change. So for example, you would create a At this point, I'm not sure how critical this is, as it can always be done later. |
|
Thanks! (we have an open issue for upgrading these schemas to draft 4, by the way, although it looks like JSON schema is currently already at draft 7; #127)
Well, historically we never patched older versions of the schema. I would only retag here to change the schema license of the older releases. (for the "documentation" repo we often have commits after a release to fix typos, formatting (we moved to Read the Docs after the most recent CSL release), and broken links. |
|
The schema isn't even valid In other words.... ThisLines 132 to 137 in 15c3185 Should be this"collection-editor": {
"type": "array",
"items": {
"$ref": "#/items/properties/author/items"
}
}And thisLines 255 to 257 in 15c3185 Should be this"container": {
"$ref": "#/items/properties/accessed"
}Here's the valid JSON schema for
|
Hmm I wonder if this is what caused python-jsonschema/jsonschema#447.
Does draft 7 support this form of non-absolute reference path? P.S. I don't want to delve too deep into upgrading the draft version in this issue, since that is off topic (not that this shouldn't be discussed, just not here).
What to open a pull request with the fixes? I'm not a maintainer of this repo, which is not very actively maintained, but some simple PRs seem to get accepted. Therefore, we've been maintaining a fork which we use in Manubot. We would certainly be happy to cherry-pick this commit, if you create it! |
|
We'd be more than happy to work with you to clean up this schema and upgrade it to the latest draft, via whatever path makes more sense (first fixing the outstanding issues in the current v3 draft, and then upgrade to v7, or vice versa). Ideally we also would have Travis-CI verify that the schemas validate and properly describe the test suite CSL JSON snippets at https://github.com/citation-style-language/test-suite (which are embedded in the tests, and, since we only validated the snippets against these JSON schemas when we first wrote the schemas, some are likely to have a few validation errors in them). |
Yes, it is for sure.
Not sure (I'm certainly not a JSON schema pro by any stretch of the imagination) but I do know that each iteration of the schema version seemed to pepper in more ergonomic features from just glancing at the highlights.
Cool. Happy to band together on this as time allows.
Yeah, that sounds like a sorely needed feature of the test suite for sure. Also happy to band together on that as well once we can get this fleshed out. |
|
@rmzelle can you go through and either merge or close the open PRs before I start on this? Want to make sure that if we do update the schemas, the most updated and accurate info is included. |
|
Any outstanding... I see there's PRs back into 2015 even. Is it worth keeping those open? |
|
Several relate to the actual design of the CSL language, and those are certainly relevant and will be addressed once we get some momentum for the next CSL release. Most of these should be issues instead of pull requests, since the eventual implementation will likely differ significantly from what the requestors are asking for, but we can leave them as is. And you're most concerned with PRs in the schema repo, right? |
|
Yep.. Just want to make sure the current existing JSON schema is correct before diving in too far. |
|
@dhimmel See here: https://json-schema.org/understanding-json-schema/structuring.html#using-id-with-ref Specifically:
|
The goal is to allow validators to detect which draft to use, without having to hardcode it in downstream applications. For example, I want my application to use the latest CSL Items schema and to continue working even if this repository upgrades to a newer schema draft.