linkSource (v5 proposal) - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.

---

Note: This proposal has been migrated to https://github.com/json-schema-org/json-schema-spec/issues/61

---

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.