Create a JSON Schema Glossary Page or Site

[Julian]

It'd be nice if we had a glossary of terms -- a page, in not very technical jargon, which explains common terminology used by us in conversation, and which could be linked to by other pages or people in order to answer questions like "what is a vocabulary" in a succinct way.

Here are two examples of glossaries I've contributed to or used heavily which may be decent examples of the concept:

• The Python glossary
• The Lean glossary

EDIT: The page has been published at https://json-schema.org/learn/glossary.html

To help, just grab any of the entries below which don't already exist on the page, and share that you're working on them!

---

List of Terms to Define

• dialect Add glossary entries for dialect and vocabulary. json-schema-org.github.io#484
• instance Add glossary entries for schema and instance. json-schema-org.github.io#462
• vocabulary Add glossary entries for dialect and vocabulary. json-schema-org.github.io#484
• schema Add glossary entries for schema and instance. json-schema-org.github.io#462
• meta-schema Add glossary entries for keyword and meta-schema. json-schema-org.github.io#469
• keyword Add glossary entries for keyword and meta-schema. json-schema-org.github.io#469
• hyper-schema Add what is JSON Hyper Schema to the Glossary #156
• draft Add a Glossary page with 2 initial entries. json-schema-org.github.io#461
• subschema Add a glossary entry for subschema. json-schema-org.github.io#520
• JSON Add a glossary entry for JSON. json-schema-org.github.io#521
• annotation (In progress)
• validation (In progress)
• anchor (In progress)
• annotation (keyword)
• applicator (keyword)
  • in-place applicator
  • child applicator
• assertion (keyword)
• JSON pointer (In progress)
• validation result (In progress)
• ref (In progress)
• resource / schema resource (In progress)
• compound schema resource (In progress)
• relative JSON pointer

[notEthan]

• inplace application
• child application
• subschema
• resource/schema resource
• anchor

maybe out of scope? maybe include as links

• JSON
• JSON pointer

[jviotti]

This is a fantastic idea @Julian and @notEthan. In general, I think we need more reference-like documentation that complements the specification to help people use JSON Schema and related technology, such as JSON Pointer, etc. A glossary sounds like a perfect start.

[gregsdennis]

I like the idea of the glossary, but what would this give us that the "definitions" section of the spec doesn't?

[Julian]

Right now we only really have a few things in that section, so there's definitely a lot more (obviously things all defined scattered lower in the spec).

But the main thing I think is to target it to a non-implementer -- the vast majority of our users I suspect would be very intimidated by the spec document and haven't read it, they're just consumers of JSON Schema. The spec's a technical document -- kind of like how we have the Understanding JSON Schema tutorial for the same reason.

[Julian]

@notEthan added yours to the list! Thanks.

[Relequestual]

I'm all for this!
Do you have a suggestion on how to approach and break up this work? =]

[Julian]

^^ there's an initial PR just adding the page with an intro and 2 entries to get us started.

I think once someone reviews / merges that, we then simply each start grabbing stuff from the list -- probably if you grab an entry, mark it in the issue description here so others know you're working on it, and then add your PR number when you send one (which GH will then cross off when the PR is merged).