"self" links, "hrefSchema", and collections

[handrews]

While working on the rewrite, it occurred to me that using hrefSchema with a "self" link doesn't make much sense. So I wrote up a bit on how hrefSchema MUST NOT be used with a "self" link, and hrefRequired SHOULD be used to ensure that the self link can always fully resolve from instance data (or if i cannot, it cannot be used).

Then I thought about collections, with filtering and pagination. What does "self" mean in such a case? Strictly speaking, a page of a filtered collection is not the same resource as an unfiltered, unpaginated collection. Or a different page from the same filter, etc. etc. Similar concepts apply to other resources that are logically "modified" or made into a sub-resource by query parameters.

However, there is no inherent distinction between this use of query parameters and a use that produces entirely different resources which are only distinguished by non-hierarchical identifiers.

So if a "self" link MUST NOT use hrefSchema (which is a debatable point), how does a collection or similar resource expose its pagination/filtering/whatever interface for users?

While there are numerous pagination link relations, they should not take user input for the page parameters either. A "first" link must always go to the first page, a "next" link must always go to the next page, whatever that means.

Using a "collection" link alongside of "self" to specify hrefSchema for pagination/filtering/etc doesn't seem to work, as setting the context of "collection" correctly in this scenario is more or less impossible (if there are no items in the collection, then it is entirely impossible).

There is a "search" link relation that has as it's target a description of an interface to search the context. This seems close to what we want, although the target would ideally be the hrefSchema of... um... something? Ugh.. brain hurts. Anyone have ideas on this?

[handrews]

Related: Is it possible for a resource to have more than one "self" link? I mean where the resource is the context of the link, not the situation where there are "self" links attached to, for instance, individual array items within a larger resource. In that case, each "self" link has a different context so there is still only one per context.

It's definitely possible for the same abstract resource to be accessible at multiple URIs, but would those other URIs also be "self" links or would at most one be "canonical" and the others be "alternate"?

[MetaAbstract]

Hi, i am working on project . It's based on json and json schema. In practice href depends from server which keep document. For example json document has been sent from one server to another. It's will be different hyper schema elements for one document and ever different id and related schema's $ref. Really i was inspired by hyper schema first. Especially by media types. I think hyper schema is movement to graphql technology.

[handrews]

@MetaAbstract it is great to hear from someone working with JSON Hyper-Schema, thanks for letting us know! Please send announcements such as this, as well as general questions, to the JSON Schema Google group/mailing list.

Issues such as this are focused on a single topic, and off-topic comments will generally be removed to help us focus on the primary topic.

[dlax]

There is a "search" link relation that has as it's target a description of an interface to search the context. This seems close to what we want, although the target would ideally be the hrefSchema of... um... something? Ugh.. brain hurts. Anyone have ideas on this?

Some times ago, I started using "search" links but didn't not pay much attention to what the target the relation should be and I instead designed them to point to search results. I did use hrefSchema for that purpose and, in the context of a collection, it more or less matched the item's schema.

On the other hand, following the actual semantics of the relation type, the "search interface" would be a search form which input would be populated according to hrefSchema? I'm not sure it's very interesting for an hypermedia system...

(I need more time to think about other parts of the issue.)

[MetaAbstract]

@handrews i am in forum already:) , but my comment was about you question

It's definitely possible for the same abstract resource to be accessible at multiple URIs, but would those other URIs also be "self" links or would at most one be "canonical" and the others be "alternate"?

[handrews]

@MetaAbstract I'm afraid something is being lost in translation. I do not follow how your comment relates to the question that you quoted. Trying to figure it out, I'm looking at:

In practice href depends from server which keep document.

Yes, this is true, and a fundamental principle of JSON Hyper-Schema. But it's not relevant to this issue. The question is which link relation the server should chose, not whether the server chooses the link relation.

[handrews]

@dlax:

On the other hand, following the actual semantics of the relation type, the "search interface" would be a search form which input would be populated according to hrefSchema? I'm not sure it's very interesting for an hypermedia system...

Yeah, it's really geared towards interactive hypermedia. "hrefSchema" itself would be the "form" in this case. And we don't have a good way to write link target URIs within the schema (link targets are relative to the instance base, and there is currently no way to access the schema's base URI). I'm not particularly trying to use "search" here. I just brought it up because it seems relevant, but is not actually quite right.

[handrews]

I suspect we'll need to put draft-07 out and provoke some more feedback before this can really be addressed. I'm going to move it to the "future" milestone and call what we have good enough for a draft. It is only a draft after all- gathering feedback is the point at this stage.

Here are the two CREFs that will be left in the draft to help provoke feedback, both attached to the "rel": "thing-collection" link added to the entry point schema:

                    I left off the scrolling parameters for this link.  Technically,
                    the link should go to the page containing the specific "thing"
                    that is the context of the link.  If the collection is using
                    semantic sorting, then this is do-able (ideally setting
                    the page boundary such that this is the first item, and allowing
                    input on the page count / "limit" parameter).  But getting into
                    semantic scrolling/pagination seems way too involved for this
                    example.

                    Note also that POST-ing to a collection page that will not contain
                    the created item also seems weird.  While retrieving the collection
                    from a query parameter-less URI will still retrieve a page, that's
                    a limit imposed by the server.  POST-ing to such a URI and disregarding
                    the "default" values for the parameters seems correct.  This is another
                    reason to *not* automatically write default values into the query.

[anatoli26]

I guess the "rel": "canonical" could refer to the pure (unpaginated, unfiltered) collection. According to the RFC6596 (The Canonical Link Relation):

The canonical link relation specifies the preferred IRI from resources with duplicative content. Common implementations of the canonical link relation are to specify the preferred version of an IRI from duplicate pages created with the addition of IRI parameters (e.g., session IDs) or to specify the single-page version as preferred over the same content separated on multiple component pages.

And the hyper-schema spec could even define that the href of paginated/filtered rel versions (self, next, etc.) should or could be resolved from the "rel": "canonical" href, e.g.:

"links": [
    {
        "rel": "canonical",
        "href": "things",
        "targetSchema": {"$ref": "#"}
    }, {
        "rel": "self",
        "href": "{?offset,limit}",
        "templateRequired": ["offset", "limit"],
        "templatePointers": {
            "offset": "/meta/current/offset",
            "limit": "/meta/current/limit"
        },
        "targetSchema": {"$ref": "#"}
    }, {
        "rel": "prev",
        "href": "{?offset,limit}",
        "templateRequired": ["offset", "limit"],
        "templatePointers": {
            "offset": "/meta/prev/offset",
            "limit": "/meta/prev/limit"
        },
        "targetSchema": {"$ref": "#"}
    }, {
        "rel": "next",
        "href": "{?offset,limit}",
        "templateRequired": ["offset", "limit"],
        "templatePointers": {
            "offset": "/meta/next/offset",
            "limit": "/meta/next/limit"
        },
        "targetSchema": {"$ref": "#"}
    }
]