json-schema-spec
json-schema-spec copied to clipboard
Split Overview into the two specific use cases
This is an alternative to #1244, and like that issue, this one should be incorporated prior to #1365. This PR makes a clearer distinction between validation uses and annotation uses that 1365 will draw on (it relies on classifying which use each keyword is being used for, since validation use is different from annotation use).
This PR moves vocabulary-related discussion deeper into the specification, and replaces Overview with a specific description of what a JSON Schema can do, especially in terms of its output.
Once its capabilities are described, the rest of the specification can describe how you write a schema that can do these things.
This replaces the Overview section, which is a little bit redundant with the above Abstract, then Introduction, sections.
CC @handrews: Could you provide your take on if this touches Vocabularies too much?
@awwright I generally like the split. I'd overall be more comfortable working out high-level organization and terminology in a few issues. I find it hard to think about terminology changes in PRs like this because they have systemic implications. Manageable-sized PRs make it hard to think about the systemic impact, and PRs that change terminology everywhere to show consistency are too large to work with in general.
Some of this also comes from recent experiences of having wording I've written questioned- the questions were understandable, but we were only able to work out what the spec really meant because there was a solid record of discussion in issues that we could research in addition to the text.
I've also had too many experiences (both as a writer and reader) where people thought they agreed on terminology, but actually had different meanings in mind. Discussions in issues, where work can focus on the concepts and fit words to those concepts once they are thoroughly understood and agreed to, gives me much more confidence. It would also help us avoid some of the terminology inconsistencies that have accumulated because the terminology was developed piecemeal instead of worked out as a system.
There's a balance between working out conceptual pieces and working out the whole system that I'm not sure how to manage, but in both cases I find working from concrete wording in PRs difficult. It makes me nervous for reasons that have little to do with the PR and a lot to do with how things have ended up misunderstood in the past.
As far as vocabularies, I see the point of moving things down. I also feel like it's important to get the concept established early (although it doesn't need as much detail as is currently present in the overview). This is another thing where working at an outline level (or slightly more detailed) would help a lot more than looking at text changes and movements.
If this looks reasonable, I'd like to move this through next.
Then I'd like to focus mostly on resolving outstanding PRs to accommodate a conversion to Markdown, but I'd also like to squeeze in #1390—this would help organize the spec to accommodate writing #1365/Discussion #329.
I do want to address some of this with the upcoming release, but I fear this particular PR may be too far gone at this point and will need to be resubmitted.
I'm going to leave this open for now as a reminder to address it.