feat: add glossary term for Anchor

[vickywane]

What kind of change does this PR introduce?

This pull request will add a definition for the anchor and ref terms to the glossary page as mentioned in this comment.

Issue Number:

• Related to Create a JSON Schema Glossary Page or Site #266

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

[github-actions]

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.

[vickywane]

@gregsdennis I was about to define ref for this PR but I can see it's already well defined here.

Should I redefine it within the glossary?

Cc: @benjagm

[Julian]

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

[gregsdennis]

We have pointer coming in another PR that's not merged yet.

I also agree with the above.

[vickywane]

@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.

[vickywane]

Thank you for the suggestions @jdesrosiers.

I have accepted them in.

[Julian]

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 -- with section-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

[kakabisht]

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.`

[gregsdennis]

according to the Microsoft style guide...

Do you have a link? What guidance in particular are you following?

[kakabisht]

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

[gregsdennis]

Just going to close and reopen this to see if the pr-dependencies action runs.

[gregsdennis]

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.

[vickywane]

Hi everyone,

Do you know if any additional changes are required from me on this pull request?

Cc: @gregsdennis @kakabisht @Julian

[Julian]

Hi @vickywane, have you seen my comment above?