json-schema-spec icon indicating copy to clipboard operation
json-schema-spec copied to clipboard

Add some paragraphs to Overview to put some context to "vocabulary"

Open awwright opened this issue 2 years ago • 4 comments

The Overview is the first section of the document that describes how JSON Schema accomplishes the goals laid out in the abstract and the introduction.

Currently, it jumps to talking about vocabularies and keywords before the definition can be meaningful to readers. This PR adds some context to that, and provides a good primer for the essential mechanics of how schemas are read, at a more "architectural" level.

awwright avatar Jun 14 '22 22:06 awwright

Note: before we merge anything to draft-next we need to sync it up with the latest changes to main/master.

karenetheridge avatar Jun 14 '22 22:06 karenetheridge

The draft-next branch has been merged and is now closed. The merge target for this PR has been changed to main. Here are the recommended steps to get your branch reabsed properly.

  1. Make sure your remote for the json-schema-org/json-schema-spec repo is up-to-date. (Example: git fetch upstream).
  2. Rebase your commits onto main. (Example: git rebase --onto upstream/main abcd123~1 (replace abcd123 with the commit hash of the first commit in your PR)).
  3. Force push the rebased branch to your fork. (Example: git push --force origin my-branch).

jdesrosiers avatar Jul 08 '22 15:07 jdesrosiers

That's exactly what I'm looking for. In most cases I'm not sure what language would improve on the issues you identified, maybe you can suggest something?

awwright avatar Jul 08 '22 20:07 awwright

That's exactly what I'm looking for. In most cases I'm not sure what language would improve on the issues you identified, maybe you can suggest something?

Sorry, just saw this one too, and I assume it's in response to one of my comments above, will try to suggest something!

Julian avatar Jul 12 '22 06:07 Julian

I trimmed this down a bit. This meshes nicely with #1365 and should go in first, and it sets up for some changes that will likely be made in that issue.

awwright avatar Dec 15 '22 07:12 awwright