href - sgpinkus/json-schema GitHub Wiki

The href property of a Link Description Object is the only property that is templated. It defines the URI that is the target of the link, and is filled out using values from the instance itself.

The rules are: the href value in a Link Description Object can contain pairs of { and }. These brackets (and the section of the string in between them) are replaced using data from the instances. The value in between these brackets is used to determine what data is taken from the instance as a replacement:

• @ - this means that the string representation of the instance itself (if it is a string, number or boolean) should be used as a replacement.
• Anything else - the value is interpreted as a key. If the instance is an object, and the object contains a property corresponding to that key, then the string value of that property should be used as a replacement.

In order to correctly find the pairs of curly brackets, the remainder of the URI must not contain { or }, and the value inside must not contain { or } either, or it will be ambiguous which brackets should be used. The value inside the brackets must not be @ either, or that will be interpreted as using the link value itself.

In order to correctly insert values into the template to create a URI, the values cannot be objects or arrays. See below for what agents might do about this.

In the case where a suitable value cannot be extracted from the instance, such as a referenced property not existing, or the value not being a string, number or boolean, then a user agent MAY take one of the following actions:

• prompt the user for input when they wish to follow the link, or at any other appropriate time
• ignore the hyperlink definition, or
• take any other action to obtain a suitable value relating to the instance.

Let's work through a simple example, to see how it works.

Say we have an object:

{
    "postId": 101
}

The schema describing the object looks like this:

{
    "links": [
        {   
            "href": "http://example.com/posts/{postId}/comments",
            "rel": "comments"
        }   
    ]   
}

So inside the links property is a single Link Description Object. The href property of that Link Description Object is "http://example.com/posts/{postId}/children". The rel property tells us that the link being described contains commentary on the post.

However, if we want to get the comments for the above instance, we should not fetch http://example.com/posts/{postId}/comments. To find out the URI that we should fetch, we need to fill out this template with values from our instance.

Essentially, we just want to look for pairs of { and }. The values in between these curly brackets are keys. In this case, there only have one pair of brackets, and the text inside them is "postId". This means that to find the URI of the instance's commentary, we replace "{postId}" with the value of our instance's postId property.

If the instance for which the links are being described is not an object, then this can be specified using the special sequence: {@}

For example, if our instance data was a simple string:

"foo"

and our Link Description Object was as follows:

{
    "href": "http://example.com/strings/{@}",
    "rel": "self",
}

then the value of our instance should be inserted into href, resulting in a URI of: "http://example.com/strings/foo".