Import hyper-schema spec and meta-schemas from json-schema-spec #17
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
RFC 5988bis lists the link relation type as one of the three required aspects of a link. Since we do not need to support the deprecated "rev" mechanisms for specifying relation types, we can make "rel" required. This will encourage hyper-schema authors to think more about choosing relation types.
Using URIs for custom relation types is often a little intimidating, and frequently ignored. Provide some guidance on some simple approaches to make it easier for hyper-schema authors to use this now-required field correctly.
This is a companion to "anchorPointer", as they use the same mechanism for adjusting locations within the instance. While "anchorPointer" adjusts the context, "hrefPointers" adjust how template variables are resolved. "hrefPointers" replaces and is much more functional than the preprocessing rules that were removed in draft wright-01. Those rules only allowed adjusting to use the sub-instance as a whole intead of individual properties or elements. "hrefPointers" supports that as well as using data from any containg or sub-instance.
Also note limitations of the hrefPointer system.
This example simplifies the concepts by getting rid of the confusing variable-length URIs and just acknowledging that the parent URI for the root node does not make any sense. This sort of situation is addressed elsewhere in the spec, so add an xref to it. The reworked example uses two links: one to illustrate standard resolution (not appearing in "hrefPointers") alongside of an "hrefPointers" adjustment using an absolute pointer, and then another illustratig both absolute and relative pointers.
Specify the actual object and property types, and drop the description as we no longer keep those in the meta-schema.
This will need a bit more work after "anchor" is merged in, as the improved wording about what the default context is is all in that other PR. But the key points are well enough developed for review. In the interst of getting the main points out for review, I referenced the long-expired Relative JSON Pointer I-D. Maybe that's OK since this is not even a working group document yet, or we can talk about how to either move the relevant parts in, or re-submit that I-D ourselves as well. This goes along with "hrefPointers", which adjusts template variable resolution in the same way that this keyword adjusts context location.
Now that "anchor" has been merged, there are a few points where its text and that of the "anchorPointer" proposal needed adjusting to fit with each other properly.
Also align the wording around JSON Pointers and Relative JSON Pointers with the wording in the "hrefPointers" specification.
We just removed all descriptions in 5ee0bc2; that one slipped in when PR #383 got rebased (and merged).
Drop "description" of targetHints in links.json
Add "anchorPointer" for in-instance contexts
This addresses the request half of #296, and is a companion keyword to "targetHints" (#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
Change "media": {"type": "..."} to "contentMediaType": "..."
Fix "media" in submission example.
Add "hrefPointers" for adjusting resolution
Add "headerSchema"
Make "rel" required.
This addresses issue #409. "submissionEncType" is actually a media type, not an encoding, so name it accordingly. Rename "mediaType" to "targetMediaType" to make it unambiguous and fit with "target" and "targetHints".
RFC 6906 is the "profile" link relation; RFC 6901 is JSON Pointer.
Fix JSON Pointer RFC (6901, not 6906).
Use the true vs false values of vocabulary declaration to indicate whether a schema author requires assertion behavior (such as because a keyword such as "oneOf" depends on such validation functioning correctly). Use a false value in the standard core+validation vocabulary, reflecting the historical lack of requirement for this keyword to be implemented. Define annotation behavior when the vocabulary is declared with false, to facilitate the recommended best practice of performing semantic validation in your application. While not the typical false vocabulary behavior, this seems like the best way to reframe the historically unpredictable behavior.
Since we're now very strongly discouraging fragments in $id, let's not use them in $schema either. It works either way, but I like the consistency. Stylistically, referring to "#" internally makes sense, while using an absolute-URI per RFC 3986 (no fragment) makes sense externally.
typo review
Split $anchor out of $id, define canonical vs shadowed URI behavior
Hopefully for real we will publish this month.
Update meta-schema dates, minor changelog typo
Validation was updated a while ago, and relative json pointer is being updated in another PR that is currently open.
Update years on core and hyperschema
Replace $recursiveAnchor: true with $dynamicAnchor: "meta" and update $recursiveRef to $dynamicRef accordingly.
Leaving them as 2019-09 for now as we'll update that all at once.
Fix 988 - Inconsistencies with schema uri and empty fragment URIs
Split "unevaluatedItems" and "unevaluatedProperties" into their own vocabulary.
Plan is to later migrate hyper-schema to its own repo
…m to an archive folder.
This imports the history of hyper-schema, and only hyper-schema, from the json-schema-spec repository.
They were archived in the json-schema-spec repo, but no longer need to be. They had to be moved as an archive directory to also preserve the un-archived commit history. For whatever reason, the output schema wasn't archived so it is not part of this commit.
jdesrosiers
approved these changes
Oct 27, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
11 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This partially addresses issue json-schema-org/json-schema-spec#838, along with PR json-schema-org/json-schema-spec#1326
Note: I have no immediate plans for active work on Hyper-Schema, although I definitely have ideas on what it could look like now. I just keep trying to find it and getting frustrated because it's neither in the top level of the json-schema-spec repo nor is it in this repo (it's in the "archive" directory of json-schema-spec, which I can never remember).
This is the result of doing:
(line wrapped for clarity)
then importing the trimmed repo and renaming the files out of the archive directory and back to their original locations. I also pulled over the hyper-schema release tags (which aren't visible in the PR — I'll push them separately after merging as you can't do it through GitHub).
There are no changes to the contents compared to what's currently in the json-schema-spec repo. I will add the build system and any updates needed for it to build after we're sure this import is correct. I don't expect to do further work on it at this time, it just seems like it would be nice to leave things build-able.