json-schema-spec
json-schema-spec copied to clipboard
json-schema-org
extract `propertyDependencies`
There's also a change to the 10.2.2 text that would need to happen, but if #1451 goes through, then it'll be addressed anyway.
Three of these keywords work together to implement conditional application of a subschema based on the outcome of another subschema. The fourth is a shortcut for a specific conditional case.
The fourth that it's talking about is dependentSchemas, which would make propertyDependencies the fifth, so this text would need to change, and the proposal should include that.
But again, if #1451 goes through, this is moot.
I just pushed an update filling in the missing sections as well as some refactoring. The following is a summary of the changes I made.
I'm concerned about the "proposal" terminology used through out the document. It's in the proposal stage now, but at some point it will be at a stage where it's expected that all implementations should be implementing it. It can't be promoted to stable until a large majority of actively maintained implementations support the feature. I think that prominently calling it a proposal will hinder that process. People will be less likely to implement something called a "proposal". We've seen how words like "draft" can effect people despite anything we say.
In place of using the word "proposal" the way it's being used, I've added a "Status" section to explain the status of the document. This needs to be filled and we need to agree on some of the details before that can be done.
I found that the "Overview" section ended up being quite large and that it ends up burying the primary content of the document that people are mostly interested in when viewing this document. My solution was to keep those sections as short as I could and link to appendices with more information.
I removed the "Examples" section because I thought the "Solution" section covered that sufficiently.
I made the "Limitations" section a subsection of the "Solution" section because I felt like that made sense as the limitations are a consequence of the solution.
Finally, I added a "Change Log" section.
I've merged the output extraction PR, which I think made changes to the HTML builds. This PR should overwrite those changes, but for now, they're in conflict.
@gregsdennis, it seems we have different ideas about the purpose of documents like this one. I was thinking about these primarily as spec documents, while it seems you're looking at it primarily as a proposal. I'm specifying the feature and you're making the case for why people should implement it and why it should be in the spec. That's why I was a bit surprised to see all the things in the template that you expected. I can see why we might want to include them, but I also didn't want them to drown out what I thought of as the main purpose of the document, which was specifying the feature.
To get some inspiration, I looked at what TC39 does. Unfortunately, it looks like there is no consistent template that they use. All of their proposals are different. Some look a lot like your template, while others link out to other places where the feature is more formally specified. Others are either of those. My favorite is in two distinct parts. The "proposal" document is the sales pitch as you envisioned, but it links out to a formal spec as I envisioned. What do you think about using this kind of approach of having two documents, one for the "why" and another for the "what"?
With this new ordering, to get the full context, the reader has to jump around the document.
What I was going for was to give readers the tldr summary (because it is quite long and tedious) while maintaining the order you laid out and also providing extra information as an appendix for people who wanted a deeper dive. It's possible that I didn't get that balance quite right, but certainly I don't see it as a reordering.
I understand your preference to not use that word, so if you want to use a different word, fine.
I've been thinking about this. If you're ok with the idea of having two documents, I think it makes sense to call the "why" document "proposals" and the "what" document "extensions". I think "extension" is an accurate description and is less likely to be ignored by implementer than something called "proposal". I see the "proposal" document as something a little more internal like something that only lives as a markdown file in Github, while the "extension" spec would be published on the website alongside the stable spec. Of course the status of the extension spec would be clearly marked and the proposal would be linked to.
I made the "Limitations" section a subsection of the "Solution" section...
You did not. They're both still H3, which I think is fine.
Ha. I thought I did. I don't feel strongly about this one. Just trying it out.
This is more of an ADR-like document than a spec-like document in that we've discussed the feature somewhere else (likely multiple "somewhere else"s) and made a decision on the direction of the feature. Now that decision needs to be officially documented. Additionally, as part of documenting the decision and to enact it, a proposal to change the spec needs to be included. Therefore this document serves two purposes:
- capture the decision (like an ADR: not extensive; just a summary)
- define the language for the specification
We're not trying to convince people with this document. The decision was already made to augment the specification. We're not justifying it; we're documenting it. As part of that documentation, we need to know what that augmentation looks like.
Splitting this into multiple documents carries the same problems as reordering the sections (or having some of the reasoning in an appendix, or whatever you want to say you did). It forces the reader to navigate to multiple areas to get the full story.
I've been part of multiple companies that have independently developed documents like this to capture decisions around changing processes, company best practices, and other aspects of building software, and this is consistently the format. It answers all of the reader's questions in an easy-to-consume way:
- What's the problem?
- What's the solution?
- Why did we choose this?
- What alternatives were considered?
- What are the technical details?
A less-technical reader (I expect most schema authors, but likely even some managers and product owners) can scan the first part and get an idea of what the change is (perhaps a dev is proposing that they use this experimental JSON Schema feature to solve a problem in their product). A more technical person (generally devs and implementors) can continue on to the technical bits. If you want more buy-in on the feature, then you need a wider audience. If you put the technical stuff at the front, you lose that first segment of readership.
One document: decision at the beginning, change proposal at the end.
Secondly, it should be called a proposal because that's what it is. It's separate from the specification, but it's not intended to remain separate; it's a proposal to change the specification.
We can encourage implementors to support these proposals. We can even put a section to that effect in the spec as a SHOULD.
But it is a proposal, and we shouldn't shy away from calling it that. Giving it another name isn't going to magically make implementors more likely to support it.
I like the comparison to an ADR. That's how I understood it after your initial response, but that analogy explains the purpose better than I did. I completely agree that we should have an ADR-like proposal document, although I didn't realize that's what you intended the purpose of this proposal to be at the time I wrote it up. I was writing it up as a spec document that includes some ADR-like content because I didn't expect we had a plan for that sort of thing elsewhere. You were expecting the opposite.
Let's do both. I think there's a lot of benefit in the proposal and extension being separate documents. It would make a lot of sense for the proposal document to be a proposal for JSON Schema to adopt the extension spec into the main spec. The same could be done for a third-party extension being proposed to be include in the spec. Even if we decide not to adopt the proposal, it could still exist as an independent extension spec that people can implement if they choose.
I hear your concerns about using multiple documents making it harder to consume, but I think that depends on the audience. Different audiences care about different things. For example, implementers generally don't care about ADR details like what alternatives were considered. An implementer is just there to know what to build. With everything in one document and details of what to build at the bottom, the implementer needs to scroll past a bunch of stuff they don't care about in order to get to the information they need. So, for the implementer, having a separate document in more ideal.
But it is a proposal, and we shouldn't shy away from calling it that.
I strongly disagree. It has also been argued that our releases are "drafts" and we shouldn't shy away from calling them that. However, we've clearly seen the negative effect that choice has had. That's taught me that we need to be careful about what terms we use and consider how people might interpret them. I think "extension" is equally applicable and less likely to be interpreted in a way we didn't intend.
I know we're considering this blocked for now. I'm not considering what I just pushed as the direction we've chosen. Take it as an example. We can still change direction.
I split it into two documents: an extension specification and a proposal to adopt the specification in JSON Schema. I updated the proposal document to closely match the original proposed template as requested. Other than extracting the specification part into it's own document, I made one small change. I switched the "Alternatives" and "Limitations" sections. I thought it flowed better to have "Limitations" first because the limitations were the driver of what alternatives were considered.
I'm going to close this and try again. Some of the comments here were made before we created our process and are a bit outdated.