Identify vocabularies, update meta-schemas #714
Conversation
|
I suspect CI will continue to fail with segfaults in xml2rfc ¯\_(ツ)_/¯ |
|
Now also fixes #641 |
jsonschema-core.xml
Outdated
| </t> | ||
| <t> | ||
| The current URI for the corresponding meta-schema is: | ||
| <eref target="https://json-schema.org/draft-08/applicator"/>. | ||
| <eref target="https://json-schema.org/draft/2019-03/meta/applicator"/>. |
There was a problem hiding this comment.
Maybe not in this PR, but should we have language identifying this vocab/meta arrangement as a suggested pattern?
There was a problem hiding this comment.
Possibly- definitely not in this PR but it's an interesting idea. Might be better in a best practices section on the site or understanding JSON Schema? Not sure- feel free to file it as an issue on the spec repo if you want.
|
@handrews would you say that the sub-meta-schemas (e.g. core.json, format.json, etc.) would be a valid source for a machine-readable list of valid keywords defined by the vocabulary? I know we were trying to come up with a distinct vocabulary format, but I think this will do well. |
Includes verbiage on the likelihood of updated meta-schemas with later dates. The hyper-schema output format has not yet been updated to conform to the recent annotion/error output work.
This is mostly about the self-describing keywords near the top, but also settled on moving "$defs" to the end to avoid obscuring the high-level structure of the schema.
It's at least theoretically possible but is harder than it sounds. In a flat specification where it's immediately clear what properties are allowed on the schema object, it's easy. But once you start combining things, then in order to find all of the keywords you have to understand what other keywords are in-place applicators. Which means that if there are extension vocabulary keywords being used in the meta-schema to describe your extension, then you get into a chicken and egg problem of not being able to tell which objects in the meta-schema are describing the schema objects, and which are not. I'm pretty sure that it's about 1000 times easier to define a straightforward approach than it is to overload meta-schemas. Meta-schemas are designed to tell you whether a schema is valid to use or not. They are not designed to tell you how the schema works. Let's leave them with a single responsibility rather than complicating the concept. |
| <t> | ||
| Meta-schemas that do not use "$vocabulary" SHOULD be considered to | ||
| require this vocabulary as if its URI were present with a value of true, | ||
| although see the Implementation Requirements below for details. |
There was a problem hiding this comment.
also see
(another occurrence below)
There was a problem hiding this comment.
@dlax I did actually mean "although" here, because the Implementation Requirements explains the weird optional nature of format, which is an exception to how the other vocabularies (except content*, which is the other "although") behave.
So I see this as a contrast to be called out ("although") rather than an affirmation or extension of the normal situation ("also"). Does that make sense?
There was a problem hiding this comment.
@handrews, yes, it makes sense. Thanks for clarifying!
There was a problem hiding this comment.
@Relequestual sure! It was already "resolved" from my point of view :)
|
@handrews, I don't think it's too difficult. The meta-schemas provide the list of keywords they define in the top-level |
|
@gregsdennis the current meta-schemas happen to work that way. There is no guarantee that all meta-schemas will work that way, nor should meta-schemas be restricted to defining keywords in a single level of This is a very complex topic, and a PR for a much simpler step is not the place to debate it. You are welcome to file an issue, but I'm not putting any more vocabulary things in this draft. I don't think relying on the meta-schema this way is the right way to go and I want to leave the options open based on feedback. |
Should always be hyphen. Also, admit that this is not going to be done this month either :-/
|
@gregsdennis aside from the stuff I asked be given separate issues, are you OK with this PR? |
|
I have no issues. Just thinking out loud. |
|
🤙 |
|
All looks good. Comment: Does the meta/meta-data schema not "annotations"? If so, couldn't it be "meta/annotations-schema"? Suggestion: Can each schema include a very breif one scentence using Otherwise, as I said, all looks good! |
|
@Relequestual at one point I had things named assertion and annotation but those are keyword classifications that are much broader than either vocabulary. So I used the name from the appropriate section of the document. I do have applicators named that way, but I couldn't come up with anything better, and applicators are more of a specialty thing in extensions while assertions and annotations are very broad categories with lots of expected new keywords. I'm going to go ahead and merge this- we can do the descriptions separately, and if you feel really strongly about the annotation naming thing we can follow up on that. |
gregsdennis
added
clarification
Fixes #612 and #697 (Edit: and now fixes #641 )
Includes verbiage on the likelihood of updated meta-schemas
with later dates.
The hyper-schema output format has not yet been updated to
conform to the recent annotion/error output work.
I ended up calling the meta-data keywords URIs "meta-data" because "meta/meta" was ridiculous, but "meta/meta-data" is tolerable.