JSON Linking - GistLabs/mechanize GitHub Wiki

Given this input JSON:

	"template-path-segments" : {
		"href": "http://example.com{/a,b}/baz",
		"a": "foo",
		"b": "bar"
	}

The "template-path-segments" object would result in a hyperlink being created with the value http://example.com/foo/bar/baz

Another more rich example is:

	"nested-links": {
		"uri": "/id/42",
		"rel": "self",
		"next": {
			"uri": "/id/43",
			"about": {
				"href": "a"
			}
		},
		"prev": {
			"uri": "/id/41",
			"about": {
				"href": "a"
			}
		}
	}	

Here, the "nested-links" object defines it's own uri, and the "next" and "prev" objects each define links.

These examples come from links.json and find-links.json.

Linking is simply defining hyperlinks and providing connections to other resources on the web. In HTML this is primarily the <a> anchor element, but also the <form> element as well (especially when used to generate a GET request).

XML has the XLink standard, but besides being exciting reading it isn't in much use.

JSON linking is using JSON data structures to define and generate hyperlinks. See [JSON Actions] for the more info on generating entire HTML requests (including POSTs).

This work, and the way links are defined in JSON, is designed to be:

• heuristic, as opposed to schema, based
• easily able to blend into any JSON data format

The implementation currently being worked on is JsonLink. This is intended to be both practically useful and a demonstration of a simple way to achieve these ideas.

This is a description of the way JsonLink functions. See the examples in links.json for actual use.

1. The JSON object that contains values that generate a hyperlink is called the link object.
2. The URI that is produced from the link object is called the hyperlink.
3. The attribute from the link object this is used as source for the hyperlink is called the linking attribute.
4. The linking attribute name is configurable, but frequently will be href or uri. See Finding JSON Links for more.
5. The URI of the JSON document itself may be used as the base URI, used when the content of linking attribute is relative. If the base URI is present during processing, then an attempt is made to generate a new URI based on that base. In Java this would be new URI(new URI(baseUri), linkingAttributeValue).
6. The value of the linking attribute is treated as a URI Template to generate the hyperlink.
7. Attributes and nested objects of the link object contribute to template resolution.

• See examples in links.json for single value attribute, array, and map expansion.

1. The presence of an attribute named inheritProperties enables URI template parameters to be defined on the parent object. This applies to the link object and recursively up the parent objects.