Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a JSON Schema Glossary Page or Site #266

Open
12 of 24 tasks
Julian opened this issue Jul 13, 2022 · 19 comments
Open
12 of 24 tasks

Create a JSON Schema Glossary Page or Site #266

Julian opened this issue Jul 13, 2022 · 19 comments
Labels
📝 Documentation Indicates improvements or additions to documentation. Hacktoberfest Issues accepeted Hacktoberfest'24 Status: Available No one has claimed responsibility for resolving this issue. Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically.

Comments

@Julian
Copy link
Member

Julian commented Jul 13, 2022

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:

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

@Julian Julian changed the title Create a Glossary Create a JSON Schema Glossary Page or Site Jul 13, 2022
@notEthan
Copy link

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

maybe out of scope? maybe include as links

  • JSON
  • JSON pointer

@jviotti
Copy link
Member

jviotti commented Jul 15, 2022

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
Copy link
Member

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

@Julian
Copy link
Member Author

Julian commented Jul 19, 2022

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
Copy link
Member Author

Julian commented Jul 19, 2022

@notEthan added yours to the list! Thanks.

@Relequestual
Copy link
Member

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

Julian referenced this issue in json-schema-org/json-schema-org.github.io Aug 9, 2022
Doing so should hopefully now allow farming out additional
entries.

Refs: json-schema-org/community#199.
@Julian
Copy link
Member Author

Julian commented Aug 9, 2022

^^ 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).

Julian referenced this issue in json-schema-org/json-schema-org.github.io Aug 9, 2022
Doing so should hopefully now allow farming out additional
entries.

Refs: json-schema-org/community#199.
@benjagm benjagm transferred this issue from json-schema-org/community Jan 2, 2024
@benjagm benjagm added 📝 Documentation Indicates improvements or additions to documentation. Status: Available No one has claimed responsibility for resolving this issue. labels Apr 16, 2024
@bhavukkalra
Copy link
Contributor

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

@vickywane
Copy link
Contributor

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

@benjagm
Copy link
Collaborator

benjagm commented Apr 19, 2024

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

Thanks a lot @vickywane ! Please go ahead

@bhavukkalra
Copy link
Contributor

bhavukkalra commented Apr 20, 2024

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.

@Temidayo32
Copy link

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

@starlightknown
Copy link
Contributor

Hi can I take up JSON pointer and
validation result?

@benjagm
Copy link
Collaborator

benjagm commented Apr 25, 2024

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

Thanks a lot. Please go ahead.

@benjagm
Copy link
Collaborator

benjagm commented Apr 25, 2024

Hi can I take up JSON pointer and validation result?

Thanks a lot. Please go ahead!

Copy link

github-actions bot commented Jun 9, 2024

Hello! 👋

This issue has been automatically marked as stale due to inactivity 😴

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 ❤️

@github-actions github-actions bot added the Status: Stale It's believed that this issue is no longer important to the requestor. label Jun 9, 2024
@benjagm benjagm added Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically. and removed Status: Stale It's believed that this issue is no longer important to the requestor. labels Jun 9, 2024
@benjagm
Copy link
Collaborator

benjagm commented Jun 9, 2024

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

@umarbshehu
Copy link

umarbshehu commented Aug 5, 2024

@benjagm I am working on relative JSON pointer.

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

@benjagm
Copy link
Collaborator

benjagm commented Aug 7, 2024

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.

@DhairyaMajmudar DhairyaMajmudar added the Hacktoberfest Issues accepeted Hacktoberfest'24 label Oct 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📝 Documentation Indicates improvements or additions to documentation. Hacktoberfest Issues accepeted Hacktoberfest'24 Status: Available No one has claimed responsibility for resolving this issue. Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically.
Projects
None yet
Development

No branches or pull requests