Skip to content

Add minimal example to the hyper-schema Overview #494

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

Merged
merged 2 commits into from
Nov 18, 2017
Merged

Add minimal example to the hyper-schema Overview #494

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2fe4e1c
As minimal example to the hyper-schema Overview
handrews Nov 16, 2017
0b3ddf6
Simplify hyper-schema overview example caption
handrews Nov 17, 2017
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
32 changes: 32 additions & 0 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,38 @@
other link serializations or representation formats at runtime, or pre-emptively
follow links to facilitate server push usage.
</t>
<figure>
<preamble>
The empty schema is a valid hyper-schema, as all schema keywords are optional,
and simply has no effect. No hyperlinks are applied by default. The following
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this should be a new paragraph, to show we've moved on from "no links is fine.

Here are some links"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went back and forth on that a couple of time. Let's see what @dlax (or anyone else who wants to jump in) says :-)

Reading your comment I'm leaning towards splitting it, but like I said, back and forth...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm missing the purpose of the first two sentences. And I'm not sure I get what you want to split off either :(

Why not simply have the third sentence phrased as "Here is an example of JSON Hyper-Schema with a single link, ..."? No need to mention it's minimal or non-trivial, I think.

(Apart from this, this looks good to me.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dlax I like the simplification idea. The empty schema is covered elsewhere, and you're right that the non-trivial/minimal language wasn't adding anything important.

I've updated this with a shorter caption now. @philsturgeon does this look OK to you?

fairly minimal non-trivial hyper-schema shows a single link, with the
IANA-registered link relation type "self", that is build from the lone object
field in the instance:
</preamble>
<artwork>
<![CDATA[{
"type": "object",
"properties": {
"id": {
"type": "number",
"readOnly": true
}
},
"links": [
{
"rel": "self",
"href": "thing/{id}"
}
]
}]]>
</artwork>
<postamble>
If the instance is {"id": 1234}, and its base URI according to
<xref target="RFC3986">RFC 3986 section 5.1</xref>, is
"https://api.example.com/", then "https://api.example.com/thing/1234"
is the resulting link's target URI.
</postamble>
</figure>

<section title="Terminology">
<t>
Expand Down