-
-
Notifications
You must be signed in to change notification settings - Fork 164
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
feat: add glossary term for Anchor #680
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Welcome to the JSON Schema Community. Thanks a lot for creating your first pull request!! 🎉🎉 We are so excited you are here! We hope this is only the first of many! For more details check out README.md file.
@gregsdennis I was about to define Should I redefine it within the glossary? Cc: @benjagm |
pages/learn/glossary.md
Outdated
|
||
### anchor | ||
|
||
The `$anchor` keyword is one of the ways to identify the location of a subschema within a document. By applying an anchor, the subschema becomes identifiable via a plain-name URI string. An anchor is also a shorter alternative to using a JSON Pointer for identifying a subschema. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd at least flip the order of the sentences here -- we're defining anchor
(the concept) not $anchor
(the keyword which helps create them).
Also I wouldn't assume someone reading this knows what a "plain-name URI string" is -- levelwise, I'd assume the person reading this barely knows what a URI itself is! Giving a one sentence example of what that is is likely useful.
Also cross-link to JSON Pointer
if we have an entry for that (and if not add a TODO probably).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have pointer coming in another PR that's not merged yet.
I also agree with the above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Julian Thank you for the comments.
I redefined the anchor
term and added a URI example to my new definition. @gregsdennis I added a TODO note to add a "see more" to the JSON pointer when the other PR is merged.
Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>
Thank you for the suggestions @jdesrosiers. I have accepted them in. |
|
||
### anchor | ||
|
||
An anchor identifies the location of a subschema within a JSON document. By applying an anchor to a subschema using the `$anchor` keyword, the subschema becomes identifiable via a plain-name URI string containing the value of the `$anchor` property starting with a `#` character. An example of a plain-name URI is `https://example.com/schemas/vehicle#owners` identifying the `owners` subschema within the `vehicle` JSON document. An anchor is also a shorter alternative to using a JSON Pointer for identifying a subschema. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I honestly still worry that someone reading this definition who doesn't know what an anchor is will still have no idea after reading it. To try to show myself why, here's a hasty attempt at what I'd have written myself -- it might be useful to show what you have to someone who doesn't already know what this is and literally ask them whether they feel they understand it after (and then perhaps see if anything I've changed in mine helps them any):
An anchor is a way of giving a name to a subschema which is located within a larger schema. Anchors exist in broader contexts than JSON Schema; in the context of web pages (and URLs which identify them), anchors are often used in order to identify a subsection within the web page. For example, a browser visiting the link http://example.com/foo#section-two will navigate directly to an element on the page identified by
section-two
-- withsection-two
being the anchor's name. Within the context of JSON Schema, anchors serve a similar purpose, allowing a subschema to be independently referred to by name even when it sits inside of a larger schema. In newer versions of JSON Schema, the$anchor
keyword is the keyword used to define a new anchor, and the$ref
keyword is used when referencing them for use. Anchors allow for naming a subschema within the parent schema in a way which is then independent of where within the parent schema they appear -- they may be nested inside various keywords within the parent schema. A related mechanism for referencing subschemas are JSON pointers, which allow for referring to subschemas by their position within the document rather than by a unique name.
As I say I wouldn't take that exactly as is, but some elements I specifically changed or didn't change are:
- I wouldn't mention
plain-name URIs
at all as a term personally, I don't think it's helpful - I would mention anchors aren't unique to JSON Schema they're inspired by something the person reading is more likely to be familiar with
- I wouldn't use the language "applying an anchor to a subschema", it's confusing to someone who doesn't know what that means (I'm not even sure it's the correct technical phrasing but I'm not an expert on the RFC)
- I'd say very slightly more about anchors vs pointers
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hello Julian,
Thank you for the content; it's really clear to me now. I just fixed some minor typos and simplified content according to the Microsoft style guide for technical writing. I hope this helps, if doesn't. Please disregard my comment.
`An anchor is a way of giving a name to a subschema located within a larger schema. Anchors exist in broader contexts than JSON Schema; in the context of web pages (and URLs that identify them), anchors are often used to identify a subsection within the web page.
For example, a browser visiting the link http://example.com/foo#section-two navigates directly to an element on the page identified by section-two -- with section-two being the anchor's name. Within JSON Schema, anchors serve a similar purpose, allowing a subschema to be independently referred to by name, even when it sits inside a larger schema.
In newer versions of JSON Schema, the $anchor keyword is used to define a new anchor, and the $ref keyword is used when referencing them for use. Anchors allow for naming a subschema within the parent schema in a way that is independent of where within the parent schema they appear -- they may be nested inside various keywords within the parent schema. A related mechanism for referencing subschemas are JSON pointers, which allow for referring to subschemas by their position within the document rather than by a unique name.`
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
according to the Microsoft style guide...
Do you have a link? What guidance in particular are you following?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, this is the link: https://learn.microsoft.com/en-us/style-guide/welcome/.
You could also refer, Google Style guide for technical writing : https://developers.google.com/style
Just going to close and reopen this to see if the |
Yea! It did! @vickywane I updated your opening comment to list a dependency on the PR that's adding the JSON Pointer definition. Once that's merged, this can be updated. |
Hi everyone, Do you know if any additional changes are required from me on this pull request? |
Hi @vickywane, have you seen my comment above? |
Hello! 👋 This pull request 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 pull request 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 pull request forward. Connect with us through our slack channel : https://json-schema.org/slack Thank you for your patience ❤️ |
Issue closed due to inactivity. Thanks everyone who was part of the discussions. |
@benjagm I would love to finish up this PR within the next few days. I just got busy with other work activities. Can it be reopened? |
Of course @vickywane |
Congratulations, @vickywane for your first pull request merge in this repository! 🎉🎉. Thanks for your contribution to JSON Schema! |
I merged this PR by mistake when trying to close it. After months without progress we have decided to close it. |
@benjagm do we need to revert it? |
I already did. Thanks Greg. |
What kind of change does this PR introduce?
This pull request will add a definition for the
anchor
andref
terms to the glossary page as mentioned in this comment.Issue Number:
Depends on #677
Screenshots/videos:
If relevant, did you update the documentation?
No
Summary
This is a contribution to the ongoing effort to define the terms for JSON-Schema within a glossary page.
Does this PR introduce a breaking change?
No