blog post for an update on the spec #1244
Conversation
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1244 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 10 10
Lines 373 373
Branches 94 94
=========================================
Hits 373 373 ☔ View full report in Codecov by Sentry. |
|
My post doesn't appear in the preview. Is that because I'm in the future? (It's 10:46 PM on 5 Jan here, and I've put 5 Jan as the publish date.) |
|
yes , i think this is definitely beacuse of the time difference . Just for info . is it working in the local ? if it's a major issue i would like to work on it |
|
Haha... I still have 2024. The post is there. |
|
Haha ... Just a typo in the publish date . whole night i wasted researching why this happened without checking the publish date |
|
|
||
| In short, to preserve future compatibility, we need to ensure that schemas can't contain extra properties which may one day be proposed as legitimate keywords. This means that extra data in schemas can no longer be acceptable. To accommodate our users' need to include meta-data and other values in their schemas, the specification will define a convention or namespace for property names that are to be ignored, and we guarantee that no future proposed keyword may follow this convention in order to keep the namespace protected. | ||
|
|
||
| As it stands today, the convention is that your property name should start with `x-`. If you like, you can read about alternative ideas and how we decided on this approach in [the ADR](https://github.com/json-schema-org/json-schema-spec/blob/main/adr/2023-04-sva-prefix.md). |
There was a problem hiding this comment.
🫶 - Linking to the ADR specifically.
|
|
||
| In a [previous post](./json-schema-joins-the-openjsf), we announced that we were leaving the IETF. At the time, the intent was to join the OpenJS Foundation, however for multiple reasons, the onboarding process was not able to be completed. As such, currently we are independent. In the future, we may again seek to join a foundation (we may even try OpenJS again), but for now, independence seems to be the best place for us. | ||
|
|
||
| When we last published a specification, we were still part of the IETF, and we used their [Internet-Draft Publication Process](https://authors.ietf.org/en/rfc-publication-process). This meant that our documents were required to retain the "draft" moniker, even though we considered them fully fledged and ready for use in production systems. Publishing independently, we're no longer bound by this requirement, however it does mean that we can no longer rely on the IETF document publishing infrastructure. We have to build our own. |
There was a problem hiding this comment.
we were still part of the IETF
I think this is misleading. We have never been part of IETF. We were never part of a working group. We published our drafts independently.
|
|
||
| However, this approach puts a large burden on tooling maintainers who want to support multiple versions of the specification, which is basically all of them. They'd have to support many different behaviors, sometimes for the same keyword. | ||
|
|
||
| The perfect example of this is Draft 2019-09's `$recursiveRef` & `$recursiveAnchor`. The idea was solid and had a lot going for it. In 2019 when we were working on it, everything seemed right, or as close as we could get it, so we added it to the specification. A few of us who had implementations also added it as an optional feature to let our users try it out. But after it was released, we realized the definition wasn't very complete, many users were confused as to how it should work, and we identified several ways that we could make it better. Those improvements became `$dynamicRef` & `$dynamicAnchor` in Draft 2020-12. Even though the "recursive" keywords weren't part of the latest specification, many implementations wanted to support Draft 2020-12 while continuing to support Draft 2019-09. Furthermore, schemas which contained the "recursive" keywords couldn't be processed under the Draft 2020-12 rules, which takes us back to the backward compatibiility problem. |
There was a problem hiding this comment.
It probably doesn't matter, but I remember a couple parts of this story a little differently.
In 2019 when we were working on it, everything seemed right, or as close as we could get it, so we added it to the specification.
My recollection was that we released it knowing that it was an experiment and may change or not work out. But, I might be conflating that with the vocabulary system that was definitely released with the expectation that it was an experiment.
A few of us who had implementations also added it as an optional feature to let our users try it out.
Recursive references were never an optional feature. The meta-schemas used them, so you couldn't have a 2019-09 implementation without it. Do you mean you made it an optional feature before 2019-09 was released?
There was a problem hiding this comment.
I think there was a certain level of known experimentation for $recursive*.
Do you mean you made it an optional feature before 2019-09 was released?
This, yes. I had supported it as experimental before the release.
|
|
||
| Additionally, but not breaking: | ||
|
|
||
| - The recommended output format introduced in Draft 2019-09 has been extracted to its own specification. This was driven by the fact that different output formats can be more beneficial to different consumers. This particular format was designed for machine consumers rather than humans. We decided it should have its own specification so that other output specifications could be written to target other audiences. |
There was a problem hiding this comment.
That was never the motivation for me. The motivation was to allow the output format to be versioned independently of the spec. Implementations generally implement multiple versions of the specification, but probably only implement one version of the output format. If they do implement multiple versions they probably don't pin those versions to the dialect of the schema being evaluated. I implement the output format from 2019-09 and use that format for all dialects. The output format version is often different than the spec version, so it doesn't make sense to version them together. It's more useful for it to be a separate specification that can be used independent of dialect. Tools that use the output format should be able to specify what version(s) of the output format they support and it shouldn't matter was the dialect of the schema that produced that result.
There was a problem hiding this comment.
The motivation was to allow the output format to be versioned independently of the spec
This was part of it, too. I can add that in. For me, it was @karenetheridge's comments on having different output formats for different audiences, so that's what I remember most.
|
@jdesrosiers I've updated. Please have a look. |
What kind of change does this PR introduce?
blog post
Issue Number:
Summary
Does this PR introduce a breaking change?
no.