updates to Hyperschema page #1039
Conversation
kwennB
added
📝 Documentation
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1039 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 10 10
Lines 373 373
Branches 94 94
=========================================
Hits 373 373 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
I think there should be some text introducing each section and more thorough explanation of each example. I only provided the examples and very sparse explanation. I was expecting you would flesh it out a lot more.
For example, the first section is describing the basic concept. It would be nice if we explain the general idea briefly before showing the example. I'd like to see that for all the sections.
|
|
||
| When `anchor` appears in an LDO, it becomes the base URI for resolving `href`. | ||
|
|
||
| > NOTE: I don't have an example because I can't think of any reason someone would want to do this. It's an anti-pattern at best. It might be best to just leave `anchor` and `anchorPointer` undocumented. |
There was a problem hiding this comment.
The audience of this NOTE is us, not the reader, so I'm just commenting here so we don't forget to remove it later when it's decided what to do with this section. I'm still in favor of removing it altogether and leaving this feature undocumented.
| GET https://example.com/book/12345 | ||
| ``` | ||
|
|
||
| _This `GET` request fetches information about a specific book, identified by the `book` ID (`12345`). In response:_ |
There was a problem hiding this comment.
issue(style-blocking): remove italics from this text
Google style guide: https://developers.google.com/style/text-formatting
|
|
||
| _The server responds with a successful `200 OK` status, JSON-formatted data, and a `Link` header that references the schema describing the structure of the returned data, including details like the `book` `title` and a link to the author via `authorId`._ | ||
|
|
||
| **Get the schema that describes the instance using the "`describedby`" Link header.** |
There was a problem hiding this comment.
issue(style-blocking): remove quotation marks from describedby; use code font for Link; remove bold formatting
Google style guide: https://developers.google.com/style/quotation-marks
| GET https://example.com/schemas/book | ||
| ``` | ||
|
|
||
| _This request fetches the schema describing the structure of the `book` object. |
There was a problem hiding this comment.
issue(style-blocking): remove italics from this text
| } | ||
| ``` | ||
|
|
||
| _The server responds with a successful `200 OK` status, JSON-formatted data, and a `Link` header that references the schema describing the structure of the returned data, including details like the `book` `title` and a link to the author via `authorId`._ |
There was a problem hiding this comment.
suggestion: "book" does not appear as a keyword in this example, so I think it should not be formatted with code font in this sentence.
| ``` | ||
|
|
||
| _This request fetches the schema describing the structure of the `book` object. | ||
| In response:_ |
There was a problem hiding this comment.
suggestion: The next sentence starts with "The response". To avoid repetitiveness, remove "In response" in this sentence
This request fetches the schema describing the structure of the book object:
|
|
||
| _The response contains a JSON Schema describing the instance's structure and links to relevant resources, such as the author's resource via `rel="author`." It also specifies that the `authorId` is required to complete the URL template._ | ||
|
|
||
| **Use the LDO combined with the instance to construct a link to get information about the author.** |
There was a problem hiding this comment.
todo: please define what "LDO" is
There was a problem hiding this comment.
LDO = Link Description Object. links is an array of LDOs.
There was a problem hiding this comment.
question: wouldn't it be appropriate to format the sentences in bold as H4?
|
|
||
| _The response includes a JSON object with the author's details, and the `Link` header points to the schema that describes the author, following the same format as the book schema._ | ||
|
|
||
| Keep following links to discover more content. |
There was a problem hiding this comment.
question: what are the links about? I assume this version is incomplete and you will add the links later but the sentence is too generic.
suggestion: add more context so readers know what information you're pointing them to is about.
There was a problem hiding this comment.
You've misunderstood the context here. Normal JSON doesn't have a way to express links the way markdown or HTML does. Hyper-schema allows you define links in a JSON document. The sentence about following more links is describing the iterative process of following the links in the JSON document to discover what other data is available from the API the same way you follow links on a website to find related information.
Here's a simple website I made a while ago to visualize this concept. Follow the links in the JSON to explore the database. https://explore.hyperjump.io/#https://swapi.hyperjump.io/api/films/1
There was a problem hiding this comment.
Thanks for adding this context @jdesrosiers
|
|
||
| #### Search | ||
|
|
||
| Using a link to construct a URI from user input. (Analogous to `<form method="get">`) |
There was a problem hiding this comment.
suggestion: use the bare infinitive "Use" instead of "Using"
| ] | ||
| ``` | ||
|
|
||
| _The response returns a successful `200 OK` JSON-formatted data with a `Link` to the schema describing the book collection, and the response body contains an array of books, each with details such as the `title` and `authorId`._ |
There was a problem hiding this comment.
suggestion: add specificity to this sentence. For example:
"...the response returns an array of books whose title value is Moby-Dick"
|
|
||
| #### Submission | ||
|
|
||
| Using a link to submit user input. (Analogous to `<form method="post">`) |
There was a problem hiding this comment.
suggestion: use bare infinitives for actions
|
|
||
| ##### Submission Media Type | ||
|
|
||
| You can also make submission will media types other than JSON. |
There was a problem hiding this comment.
todo: fix typo "with" instead of "will"
|
|
||
| _The request was successful, and the book was created, but the response contained no content._ | ||
|
|
||
| ##### Submission Media Type |
There was a problem hiding this comment.
suggestion: keep this heading at the same level as the "submission" heading
| 204 No Content | ||
| ``` | ||
|
|
||
| _This code shows using application/xml, to create a new book resource with a `POST` request._ |
There was a problem hiding this comment.
suggestion: "This request uses the media type application/xml to create a new book resource with the POST method."
|
|
||
| #### Registered relation | ||
|
|
||
| A registered relation pointing to an author. |
There was a problem hiding this comment.
suggestion: "This is a registered relation pointing to an author"
|
|
||
| #### Custom relation | ||
|
|
||
| A custom relation linking to a specific review. |
There was a problem hiding this comment.
suggestion: "The following is an example of a custom relation linking to a specific review."
|
|
||
| #### Multiple relations | ||
|
|
||
| A multiple relations associating a comments collection with two different relationship types. |
There was a problem hiding this comment.
suggestion: "This JSON describes a link to a collection of reviews on a website. It uses both a generic relation type ("collection") and a custom relation type, ("https://example.com/relations/reviews"), specific to the website."
There was a problem hiding this comment.
specific to the website
Should be "specific to the API".
|
|
||
| #### Setting the base URI | ||
|
|
||
| `base` can be used to alter the base URI. It is a URI Template and can be relative. |
There was a problem hiding this comment.
suggestion: remove uppercase from "Template"
Google developer style: https://developers.google.com/style/capitalization
There was a problem hiding this comment.
URI Template is a proper name referring to RFC 6570. It should be capitalized.
|
|
||
| #### Setting a link's "anchor" | ||
|
|
||
| A link is a connection between two resources. The source of the link is called the "anchor" and the destination is called the "target. The "anchor" usually doesn't need to be specified because it's understood to be the resource the link appears in. `anchor` allows you to change the link's "anchor" to something other than the resource it appears in. |
There was a problem hiding this comment.
todo: remove the quotation marks from this paragraph
Google style guidelines: https://developers.google.com/style/quotation-marks
|
|
||
| **about**: `https://example.com/docs` | ||
|
|
||
| ##### Required/Optional variables |
There was a problem hiding this comment.
todo: use sentence case capitalization
Google style guideline: https://developers.google.com/style/headings
|
|
||
| **previous**: N/A | ||
|
|
||
| Note: Optional variable `perPage` is present and included in the link. |
There was a problem hiding this comment.
todo: for all notes and notices intended for readers, follow the Google style guidelines and format them using our Markdown tags
Google style: https://developers.google.com/style/notices
JSON style guide: https://github.com/json-schema-org/website/blob/main/pages/md-style-guide.md
| } | ||
| ``` | ||
|
|
||
| **next**: `https://example.com/books?page=1` |
There was a problem hiding this comment.
todo: remove bold format, add code font
|
|
||
| **next**: `https://example.com/books?page=1` | ||
|
|
||
| **previous**: N/A |
There was a problem hiding this comment.
todo: remove bold format, add code font
|
|
||
| **previous**: N/A | ||
|
|
||
| Note: `previous` doesn't apply because the required property "previous" is not present. |
There was a problem hiding this comment.
See the comment below for notes and notices.
thought: the reason why previous doesn't appear in this example is because the current page (0) doesn't have a previous page. Stating this would make the NOTE more specific and informative.
suggestion: "The previous link is not defined in this JSON example because the current page ("page": 0) has no preceding page to link to. However, in other instances, a previous link might be available with the "rel": "previous" property in the response."
| ### Actions | ||
|
|
||
| #### Search | ||
|
|
There was a problem hiding this comment.
issue(blocking): Most use cases jump straight into the examples without giving much context. I think the document could benefit from adding more context and linking to other resources readers can use to expand their knowledge about the hyper-schema. This is especially important for readers who are new to the hyper-schema vocabulary.
|
|
||
| Note: Optional variable `perPage` is present and included in the link. | ||
|
|
||
| ##### Variable coersion |
There was a problem hiding this comment.
suggestion: unless this is a technical term I'm not aware of, the correct spelling of this word is "coercion"
There was a problem hiding this comment.
Good job putting together all these examples!
Are you still working on the final sections?
There are several things to take care of with respect to structure and style. From a high-level perspective, these are my observations:
- Add more context to the use cases and links to learning resources. The use cases lack an introductory context and jump directly into examples. Beginners may have difficulty understanding the examples because of this.
- Review the structure of the headings. In my opinion. some headings could be formatted as H4 instead of H5, but this might be due to the lack of context I mentioned in the previous bullet point.
- Edit the document for style. I left some specific comments about style but I recommend a major revision of the document to implement the Google style rules and our Markdown tags.
I appreciate your efforts in creating this document. I'm confident that with a little more work, it can become a valuable resource.
What kind of change does this PR introduce?
Hyperschema documentation
Issue Number:
Summary
With @jdesrosiers we're creating a better useful JSON Hyperschema page.
Does this PR introduce a breaking change?
No