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

• [x] dialect json-schema-org/json-schema-org.github.io#484
• [x] instance json-schema-org/json-schema-org.github.io#462
• [x] vocabulary json-schema-org/json-schema-org.github.io#484
• [x] schema json-schema-org/json-schema-org.github.io#462
• [x] meta-schema json-schema-org/json-schema-org.github.io#469
• [x] keyword json-schema-org/json-schema-org.github.io#469
• [x] hyper-schema #156
• [x] draft json-schema-org/json-schema-org.github.io#461
• [x] subschema json-schema-org/json-schema-org.github.io#520
• [x] JSON json-schema-org/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)
• [x] JSON pointer (In progress)
• [x] 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).

[bhavukkalra]

In the process of creating a drafts for annotation and validation. Will send over for review once ready

[vickywane]

@benjagm I'd love to take up anchor and ref and submit a PR for them.

[benjagm]

@benjagm I'd love to take up anchor and ref and submit a PR for them.

Thanks a lot @vickywane ! Please go ahead

[bhavukkalra]

Just created PR #668. To add the sections of annotation and annotation (keyword). I tried to club these two attributes in a single PR as these are closely related and one references the other. Tried defining the terms with what I sounded simplistic while browsing though these docs.

• https://json-schema.org/understanding-json-schema/reference/annotations
• https://json-schema.org/draft/2020-12/json-schema-core#name-annotations

[Temidayo32]

I will be submitting PR for resource / schema resource and compound schema resource.

[starlightknown]

Hi can I take up JSON pointer and validation result?

[benjagm]

I will be submitting PR for resource / schema resource and compound schema resource.

Thanks a lot. Please go ahead.

[benjagm]

Hi can I take up JSON pointer and validation result?

Thanks a lot. Please go ahead!

[github-actions[bot]]

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart:

[benjagm]

This is a long term issue. We'll keep it open.

[umarbshehu]

@benjagm I am working on relative JSON pointer.

Any information regarding this subject matter would be helpful to me.

[benjagm]

Thanks a lot for working on this @umarbshehu. My advice is to start with the available definition of JSON Pointer and do a research in the JSON Schema specification to understand the relative JSON pointer and provide your description avoiding repeating the same wording used in the spec.