This document specifies the technical requirements for software to address the needs of ubiquitous linking.
A link is a reference to an information resource (data) that the user can access by interacting with the link. It consists of an address of that resource and the name of the resource. Typically the address has the form of a Uniform Resource Identifier (“URI”), as described in RFC-3986, scheme:[//authority]path[?query]. Web URIs are common but there are also custom, app-specific URIs.
Developers of software that processes information resources should strive to:
- Ensure that each user-accessible resource (object or entire document) that their software creates and processes can be identified and accessed via links.
- Enable identification of – and access to – deeply nested selections, such as a region of text or a node within a hierarchical object (e.g. a node in a mind map, or a task in a project).
- Ensure that links to information resources are robust. For instance, they should still be useful if the addressed resource is renamed or moved.
- When applicable, ensure that there is a clearly documented separation between the top-level (primary) resource (such as a document) and the deep (secondary) identifier within the resource, so that the user can choose whether to access the overal resource or a nested item within it (e.g., at a particular anchor, page and/or character location).
- Make the user interfaces for copying links and accessing linked resources as easy and convenient to use as copying and pasting, keeping accessibility considerations in mind (such as providing keyboard shortcuts and ensuring menu items are easy to reach).
- Provide an application programming interface (“API”) to:
- obtain the link, address or other unique identifier and name of the currently selected or open resource, and of the deeply nested selection (if any)
- open or reveal a resource by its address — and to a location or item within the resource if a deep link is provided
- If users can create resources with the software’s user interface, then provide an API to create a resource with user-specified parameters (such as name), which returns the address of the newly created resource.
- If the resources created by the software are accessible both from a browser app and a special-purpose app, then publish a scheme for converting local addresses to web addresses. This should allow conversion of local URLs or IDs to web URLs and vice-versa. Using universal links may avoid the need for two different addresses for web and local access to information resources.
This manifesto does not specify a specific API. Nor does it specify a particular programming language or technology (such as x-callback-url). It does not require that the API involve RFC-3986 compliant links (though using this standard format may be beneficial). It does, however, entail that a clearly documented API be published by the developers, that addresses the ubiquitous linking requirements listed above. This will allow software developers to implement linking systems with the technology of their choice.