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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Oct 2, 2024
Merged

feat: add glossary term for Anchor #680

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
556cecb
feat: add glossary term for Anchor
vickywane Apr 26, 2024
bcd5942
update: redefine anchor term and add URI example
vickywane Apr 30, 2024
441e2ec
update: add editorial suggestions to anchor definition.
vickywane May 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions pages/learn/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,12 @@ Said more plainly, whether a particular value is a subschema or not depends on i

Subschemas may themselves contain sub-subschemas, though colloquially one generally uses the term "subschema" regardless of the level of nesting, further clarifying which larger schema is the parent schema whenever needed.


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

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

Copy link

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

Copy link
Member

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?

Copy link

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


<!-- TODO: add reference to JSON pointer term as a see more. -->
### tooling

A JSON Schema tool (or colloquially "tooling") is any software application or library for working with or evaluating schemas in some way.
Expand Down
Loading