v6 hyper-schema: linkSource

[handrews]

This proposal originally written by @geraintluff at https://github.com/json-schema/json-schema/wiki/linkSource-(v5-proposal)

Proposed keywords

This proposal would introduce the following keyword to LDOs:

• linkSource

Purpose

Currently, links described in links apply to the instance being described by that schema.

Sometimes, however, it would be good to be able to describe links for other data items.

Values

The value of linkSource would be a relative JSON Pointer.

Behaviour

When parsing a link definition, the substitution (for href and possible rel) would be processed as normal.

Once the link had been determined, though, the Relative JSON Pointer in linkSource would be resolved. The result of resolving that pointer should be considered the "source" of the link, instead of the current instance.

Example

Take this data for example:

{
    "postType": "blog",
    "authors": [
        "someuser123",
        "otheruser"
    ],
    ...
}

The entries in "authors" represent authors for the post - but the best we can currently do is to define a rel="author" link on the string itself (e.g. "someuser123"), or perhaps just define a rel="full" link (not specify an author link at all).

This would be incorrect - the links shouldn't apply to the individual entries in "authors", but to the post itself. Using linkSource, we could represent this as:

{
    "type": "object",
    "properties": {
        "authors": {
            "type": "array",
            "items": {
                "type": "string",
                "links": [{
                    "rel": "author",
                    "href": {
                        "template": "/users/{username}",
                        "vars": {"username": "0"}
                    },
                    "linkSource": "2"
                }]
            }
        }
    }
}

Concerns

Walking the whole instance tree

If link definitions can be defined outside of the data they describe, then in order to find all the links that apply to the instance, it would no longer be enough to process the "immediate" schemas for that data - tools would have to inspect the schemas for all children in the entire instance.

[handrews]

The schemas I worked with at Riverbed (published on their support site) made use of links defined deep in a schema of exactly the sort described here. Based on that experience, I do not see any need for linkSource.

How would this example be any different without linkSource? I don't see anything in the current JSON Hyper-schema specification that prevents defining links from within child schemas, and I don't see any other way to interpret such child schema links, either. I definitely do not see how a linkSource pointing to anything but the root schema would work.

In practice, walking the instance to find all links was not a problem for us. The algorithm is very straightforward. While being able to validate an "immediate" schema independent of its children is a desirable principle for validation, I think hyper-media concerns should not have the same constraint ( yet another topic for issue #55 ). Hypermedia works on the level of complete representations, not individual data structure levels within a document.

[handrews]

@awwright , @Relequestual , @jdesrosiers , @slurmulon , @epoberezkin , @Anthropic , anyone want to defend this proposal? I've not found any further discussion of this one anywhere, and still can't figure out what actual problem it's solving. Would like to close if no one wants to champion this.

[awwright]

@handrews If you don't have a need for an issue yourself then I wouldn't bother pulling it over

[handrews]

@awwright I have a need for this project not to be a confusing mess on GitHub. Having read through many past email threads and issues all over the place, I know that it is very confusing for anyone trying to join the project. It was very confusing for me, and it is confusing to have to refer my co-workers to multiple repos.

I know you disagree with me on this and think the current mess is totally fine. Or at least fine enough to continue as-is. As far as I can tell most people who have offered an opinion at all think the current situation is a problem. So I will continue trying to clean it up and hope I can get the attention of someone who can close the old issues.

[handrews]

Specific to this sort of thing, we need to have clear evidence of having considered and discarded proposals so they don't get raised over and over again. If no one wants this, we just close it and then it's clear, and anyone who finds the old wiki page will know what the decision was.

[awwright]

@handrews JSON Schema follows the IETF "rough consensus" model of decision making. So if there's no particular controversy facing us, it doesn't make sense to have an open issue on the issue tracker.

And further, this means we can re-examine an issue if there's a new argument for doing something differently, even if we decided otherwise earlier on in the process.

And finally, when this gets adopted under a WG, discussion will probably move to their email list anyways.

So in general, I'd consider the old repository dead, you can just ignore it. I've already trolled around and cherry picked all the issues I'm interested in myself.

[handrews]

@awwright I can totally be on board with that model, but it's not apparent to people who just search GitHub, and we will keep having people show up and comment on issues (or refer to wiki pages as active proposals which just happened less than an hour ago in another issue).

You being fine with ignoring the repo (which at first glance looks at least as official as this one) has no impact on how likely other people are to get confused by it. I agree that the RFC process does not require closing it, but that's not the point.

@Julian offered to close issues if you specifically approved them. Would you be willing to tell him to close all issues? I can put an explanatory note referring to the new repos on all of them first if that seems better. I've already done at least a third of them anyway.

Also, if he'd accept my pull request to make it so that "master" no longer looks like it has a bunch of active specs in it, that would be even better.

For wiki pages, I can put in notes that the proposal is considered rejected for lack of active support, and point to this repo. I've done a lot of those already, too.

[Relequestual]

I wonder if it's worth closing issues where the original author hasn't come back to defend it, and commenting as such for the reason.

[handrews]

I was actually planning to comment on all of the ones I brought over that I don't personally care about and send a "last call to adopt these" message to the google group. And then perhaps close anything that hasn't been adopted after two weeks.

[handrews]

Or maybe just comment here and close- if anyone was following the old issue they would already have seen that it migrated anyway and presumably be following it here anyway.

[Relequestual]

It would be great if you could auto close issues after a time... wonders if the github api supports the required functionaity for a bot to... nope... no time haha

[handrews]

It's been over two weeks since asking if anyone wants to take this over, and all named people have commented on other issues in the interim. Pretty clear that no one wants to take this on, so I'm closing it.

If anyone else wants to champion it, please re-file under your own account.

[awwright]

Ooh, I see what's going on here, I think. Yeah, JSON Schema should probably
be able to define an arbitrary source for a link. The HTTP Link header
calls this an "anchor". I'll open up a task for this when I get a chance.

On Nov 8, 2016 12:32 PM, "Henry Andrews" notifications@github.com wrote:

Closed #61 #61
.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#61 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAatDfq2hI-OheK3O7LVllVFzWCOl49Mks5q8M5GgaJpZM4KAAk4
.

[handrews]

@awwright can you explain this at all? I still can't figure out what it's doing that we can't already do.

[awwright]

Suppose I define a link right here (HTML):

<link rel="next" href="62" />

We can express the information links convey in a format called N-Triples (a subset of the more general grammar Turtle). Since links by default have a subject of the current document, it would look like:

<https://github.com/json-schema-org/json-schema-spec/issues/61> iana:next <https://github.com/json-schema-org/json-schema-spec/issues/62> .

But it might be the case we want to use JSON Schema to let documents make links about other documents to different other documents. A subject that's not <https://github.com/json-schema-org/json-schema-spec/issues/61>

Well in that case we need to allow JSON Schema to define what that "subject"/"source"/"anchor" is.

[awwright]

Opened issue in #140