example in overview of hyperschema spec

[dlax]

Prior to the rewrite in #427, there was a simple yet illustrative example in the overview of hyperschema specification. See http://json-schema.org/latest/json-schema-hypermedia.html#rfc.section.3

Should we restore it?
I think so and can submit a PR if there's an agreement.

[handrews]

I always hated that example. It's a bunch of stuff that is not explained or motivated and puts the emphasis on the wrong things. And breaks up the flow way too much. I would really rather not put it back.

If we must have an example in the overview (and I'm actually pretty strongly agains that) then it needs to have a very clear, concise, and specific purpose. What is it trying to illustrate? "Just show a hyper-schema" is not sufficient. People can jump to the "Examples" section if that's how they want to start. There has to be a really compelling reason to break up the overview. Keeping the overview high-level is very important.

[handrews]

@dlax I can perhaps see the need to just show what the basic structure of a hyper-schema is in the overview. I think what I really dislike about the example in draft-06 is how long it is, and how much it clutters hyper-schema with other things. However, a minimal example such as:

    {
       "links": [
           {
               "rel": "self",
               "href": "article/{id}"
           }
        ]
    }

(or perhaps with $schema and $id included to make it a proper schema document?)

could work fine. This would show the minimum useful hyper-schema (ignoring that {} is trivially a valid hyper-schema, which is covered elsewhere I think).

I considered putting something like that in §5 Schema Keywords, but that didn't feel quite right (too much that was not a schema keyword).

But the above example illustrates how to connect a minimally templated link with a standard link relation type to an unconstrained schema, using the instance's request URI as the base URI for href.

@dlax would that work for you?

[dlax]

@handrews Thank you taking time to answer here and trying to move forward.

I'm not sure I get your proposal right, do you mean to include the schema above with only links and nothing else (especially no data description like type, properties, etc)? If so, it'd certainly be minimal but I'm afraid it wouldn't be very understandable and readers would then wonder where {id} comes from.

My point about having a simple but demonstrative example upfront is that readers should be able to infer how JSON Hyper-Schema can work by just reading the example and practically without reading the spec (which I think is possible with the previous example).

Also, as far as I remember, there has been no clear motivation for removing examples during the rewrite in #427. So one objective of this issue is to make the decision clearer and hopefully reach a consensus. As mentioned elsewhere, we (@handrews and me) disagree about how examples should be used in the specification but since nobody else voiced their opinion, the discussion is somehow going circles. So, unless other people comment further, we (the project) should try and follow the editor's (@handrews) taste and move forward by releasing as is and closing this issue (and I'm fine with this).

[handrews]

@dlax (some of this we've discussed elsewhere, but for anyone just joining..)

I'd like to strike some level of compromise here, even if it is more in my direction because I would like to see what kind of feedback that produces (honestly, I expect questions about more examples, but the interesting thing will be to see which questions we get). That said, the spec needs to be comprehensible enough for people to find it worth reading. So I'd like to find the minimal example that achieves that goal.

A lot of this comes back to how the validation spec has almost no examples and has been extremely successful. Other resources fill the example role. The only examples are for content* (which came over from hyper-schema, and is kind of complicated anyway) and definitions (presumably b/c $ref and $id confuse everyone).

The reason that there are as many examples in Hyper-Schema as there are even now is that hardly anyone has ever really understood it, especially not from just reading through the spec. And (in my experience with collections) have found it difficult to apply to non-trivial systems.

Basically, I want minimal examples, if any, interrupting the flow of the high-level description, with detailed, realistic examples down in the examples section. This is why I'm arguing for less here and more in #465.

How would this work for you?

    {
        "type": "object",
        "properties": {
            "id": {
                "type": "number",
                "readOnly": true
            }
        },
        "links": [
            {
                "rel": "self",
                "href": "article/{id}"
            }
        ]
    }

This at least hints at where {id} comes from. The caption would be something along the lines of "this shows how to build a self link out of an object containing only an identifier." I'd need to work on that a bit as I don't want to dive into what a "self" link is but maybe we can get away with a forward xref for that?

[dlax]

How would this work for you?

That'd work well :)
Perhaps just use "things" instead of "article" to keep the current theme consistent between example.

[handrews]

Merged #494.