Web architecture encourages client software that is designed as an agent in a dynamic information space (Charlton, 2012). This is enabled by one of the fundamentals of REST architecture (Fielding, 2000; Fielding, 2008), 'hypermedia as the engine of application state' (HATEOS). Understanding this rather arcane concept is central to understanding modern web applications and architecture. The idea is that a web application is a software agent that retrieves documents from the web, and follows instructions contained in those documents to move towards a goal. The application starts with some objective, and a link to retrieve a hypermedia document that contains the initial instructions. Application logic consists of inspecting the instructions in the document, determining which instructions to follow, and executing those instructions. The logic may involve requesting user input to make choices or to provide information (fill out forms) necessary to complete the process; such user input is well accounted for by the hypermedia controls offered by HTML. This investigation is focused on links in documents that are intended to be processed by machine agents.

The original web architecture was designed to account for human-directed navigation of links to obtain resources that for the most part were intended for display and visual processing by human users. With the increasing adoption of service-based architecture, linked data, and semantic web technology, machine interpretation and processing of resources is becoming an integral part of an evolving distributed computation system. Simply clicking on a link to see what you get does not work in this environment. Links between resources for machine-automated processing require additional information about the nature of the target resource, its capabilities, data structure, and content.

This approach revolves around the concept of hypermedia, a document that contains both information and controls to enable a user (human or automated) to make choices and select actions that direct the execution of an application towards a goal. HTML is a widely used hypermedia type. As originally conceived, it provided a human user with a text document containing links that could be followed to view other text documents. In the language of hypermedia, the text provides information, and links are the controls that provide the mechanism to change browser application state, i.e. display a new web page. The user in this case is a human, and any necessary explanation of the controls (links) is in the text for a user to read. This document outlines a scheme for properties that can be used to specify the behavior of a link in a hypermedia document such that machine agents can interpret the link and use it with minimal intervention by a human user. The idea is that the details of application execution are dynamic; the client doesn't have a fixed copy of the instructions with locked-in dependencies on particular URIs or processing models. Thus the application can evolve as technology changes or new capabilities are introduced.

This proposal addresses the following situation: given a choice between a number of hypermedia controls (links, also called 'affordances'), a software application (machine) must determine which controls will activate a representation or interface that progresses the application towards its goal. The solution proposed here is to develop conventions for a hypermedia format to describe the controls (links) it presents in a general way that can be used by a wide variety of hypermedia applications. This information is supplied as properties associated with the links in a hypermedia document instance.

There are a variety of situations in which a hypermedia document might present a list of links (affordances, controls). The objective might be to make an information resource available to a user in their native work environment, to reconstruct an archived compound digital object, or to execute a workflow or data visualization. The problem this project addresses is development of an abstract model for the information that must be included with these controls to enable a machine agent to select the proper one to achieve the application goal in a wide variety of situations. Various implementations based on a shared conceptual model will facilitate integration of applications and reuse of components.

This issue impacts a variety of current activities considering use of various hypermedia formats, including Atom, GeoRSS, and various XML schema to describe associations between resources. Some examples are the Open Geospatial Consortium OWS context Standards Working Group, the Earth Science Information Partners (ESIP) data and service casting schemes, the Energistics energy industry ISO19115-1 metadata profile, the protocol for Web Description Resources (POWDER), USGS Community for Data Integration Web Application Integration Framework group, the Constrained Restful Environments Link Format (CoRE), linked data profiles being developed for JSON encoding (JSON-LD, http://json-ld.org/), JSON hypermedia profiles (HAL, SIREN, Hydra, Home Document), Signposting for Scholarly Web and the Open Archives Initiative Object Reuse and Exchange specification.

Use Scenarios

Here are a variety of scenarios framed in several contexts: a metadata record, a ‘service cast’ or ‘dataset cast’ document, an ‘OWS context’ (‘common operating picture’) document (Atom XML or JSON), or an XML ‘data’ document (like GeoSciML). These use cases are all related to the issue of what information needs to be encoded to make a URI machine-actionable in a simple, useful way .

· A data citation provides a link to directly access a particular subset of some data set.

· A GeoSciML instance document contains URIs that specify terminological quantifiers for various property elements; a user interface must present these using labels intelligible to users of the data

· A WaterML instance document contains URIs that specify terminological quantifiers for various property elements; a data processing application is comparing these attribute values to data from another source and must assess concept similarity. An owl representation would be most useful.

· A WFS server is processing filter requests against a GeoSciML document with concept expansion on attribute values specified by URIs, and must determine the transitive closure of the concept in the containing concept scheme.

· Geospatial information context document (common operating picture, OWS context) provides links to a collection of resources that constitute a workspace environment, e.g. a map mash-up bringing a variety of service-based spatial data together to convey some interpretation, including portrayal configuration, filters on datasets, operation options, etc...

· A metadata record for a data granule links to a metadata record describing the collection that contains the granule

· A metadata description of a service resource links to metadata for datasets it serves.

· Metadata for a dataset contains actionable link/description of services providing the data so that a client can connect to the service and access data without human intervention.

· Dataset (or collection) cast specifies what services are available to query, access, or transform each dataset, and client software can enable user to do these without intervention.

· An Atom feed describing an information resource provides links enabling a variety of human and machine interactions with the resource that access different representations and interfaces.

· A workflow is described by a branching chain of service calls described in a hypermedia document.

Link Properties Review

To explore what is being done to implement machine actionable links, a survey was made of several specifications that are in use (Table 1). The various approaches generally build on the html <Link> approach, with information encoded in one or more attributes on the link, or in the codelist/controlled vocabulary associated with these attributes. All utilize MIME type in some fashion, and generally include some kind of ‘rel’ or ‘role’ attribute used to indicate the semantics of the link.

Table 1. Link parameter specifications reviewed for this analysis

Specification	Link	Notes
ATOM	http://tools.ietf.org/html/rfc4287	An XML-based document format that describes lists of related information known as "feeds". Feeds are composed of a number of items, known as "entries", each with an extensible set of attached metadata. Defines link element with relation type, original vocabulary of 5 types extended in IANA link type registry
CoRE	http://tools.ietf.org/html/rfc6690	link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links.
ESIP discovery	http://wiki.esipfed.org/index.php/Discovery_Change_Proposal-8		Links to datasets (i.e. collections) that are made available by a given service; link to services available to discover & access collection items; link to additional resources or metadata.
GML codeType		XML element scheme to associate a URI with a context, use for linking to concept resources. Similar to CodeList type in ISO 19139.
HAL	http://tools.ietf.org/html/draft-kelly-json-hal	JSON Hypertext Application Language (HAL) is a standard which establishes conventions for expressing hypermedia controls.
Home document	http://tools.ietf.org/html/draft-nottingham-json-home	IETF rfc draft. Hypermedia document format to describe capabilities of a resource so non-browser client can decide at run time how to interact with the server based upon the described capabilities
Hydra	http://www.markus-lanthaler.com/hydra/spec/latest/core/	RDF vocabulary for hypermedia HATEOAS API; indirect implications for link properties on Collection entity. Focus is on Templated Web API description.
IANA link type registry
IETF Web Linking	http://tools.ietf.org/html/rfc5988	IETF-5988 specifies relation types for web links, defines a registry for type definitions to enable interoperability, and defines the use of the Link field in HTTP headers to encode links.
ISO19115/ 19139	see USGIN profile document	formal metadata specification. CI_OnlineResource element is used to encode machine actionable links
RDFa	http://rdfa.info/about/	scheme to add attributes on xml elements to tag them with RDF encoded metadata, designed for use in XHTML web documents. These allow association of xml element values with URI’s for properties, datatypes, linked resources (only one, because they are xml attibutes), types, or identifiers
xlink	http://www.w3.org/TR/xlink11/	specification for attributes associated with links in xml documents
OWC offering	OCG 12-080 Table 3	the properties of a specific service binding , characterized by a series of parameters. The parameters valid for a specific type of service binding, are defined on a case by case basis.

Table 2. Link type relation vocabularies reviewed for this analysis

Vocabulary	link	Notes
DataCite RelType	http://schema.datacite.org/meta/kernel-2.2/doc/DataCite-MetadataKernel_v2.2.pdf	relationships from a citation to a related resource
Dublin Core Terms	http://dublincore.org/documents/dcmi-terms/	Compare terms in substitution group for dct:relation.
ESIP link type		for data casting and service casting, to extend ATOM Link types
IANA link relations	http://www.iana.org/assignments/link-relations/link-relations.xml	for rel attribute of Link element. extends link types defined in IETF-5988
ISO19115-1 online function codes		for function property of CI_Online Resource. From draft version of 19115-1 DIS.
RDFa relation	http://www.w3.org/TR/rdfa-syntax/#relValues	RDF predicates for relationships between resources
Microformats	http://microformats.org/wiki/existing-rel-values	compilation of rel values for html link <a> and <area> elements [new addtion to this list 2014-0314; values have not been integrated]

Results of compilation of specifications

Table 3 is a summary of parameters used as link properties in the various schema that were studied (see Table 1). These are grouped into related attributes color coded in the table. 1) Basic information necessary to understand the link and its target. 2) Additional useful information about the target. 3) Information about link function. 4) operational switches that indicate suggested or required client behavior when a link is used, and are all optional. Sources of link relationship vocabularies are summarized in Table 2, and a compilation of the relationship types is presented in Table 4.

Table 3. Link properties that are in use. The first four are the most widely used and are considered the ‘core’ attributes. Abbreviations in the schemes column: xlink—W3C link specification; atom—IETF4287 Atom feed specification RFC; iso—ISO 19115/19139; 5988—IETF5988 web link RFC; esip—ESIP discovery cluster data and web casting discussion; ows—OpenGeospatial consortium OWS context discussion from Standards working group.

Element	Scope note	Schemes that use
1. Basic information
targetURI	URI that identifies the resource that is the source of the link. This is generally an http URI, which will be dereferenced. The associated attributes provide guidance for client software to determine if it wants to dereference this identifier and what representations is can expect when it does. If identifier is not http, then the protocol property should indicate the scheme used.	xlink, atom, iso, 5988, esip, ows, HAL
rel	URI from IANA rel vocabulary for consistency with IETF5988. Semantics of link from global vocabulary for interoperability. Semantics in this context means calculatable (see discussion in Coyle, 2010 p. 19). Attribute value is list; best practice is to include one of the 5 original Atom link@rel values for interoperability. HAL uses IETF RFC-5988 rel terms for JSON property names, and adds an extra name property to differentiate links with same rel.	xlink, atom, 5988, esip, HAL
title	free text to label link in GUI, used to describe the meaning of a link or resource in a human-readable fashion	xlink, atom, iso, 5988, owc, HAL
MIMEtype	MIME content type. Indicates media format of link target. Expects a MIME type (http://www.iana.org/assignments/media-types). Intention is that if a type is listed here, it is known to be available from the host when the href is dereferenced.	atom, 5988, esip, owc, HAL
template	Boolean to indicate if the provided targetURI is a template according to RFC-6570 (http://tools.ietf.org/html/rfc6570); templates have parameters, which may have controlled vocabularies; to use template need binding between template URI and parameter definitions. This is done with a template-vars property	HAL, Hydra
template-vars	A collection of key value pairs that map parameter names in the template to global identifiers for resources that define the semantics and syntax of the parameter	home-doc:href-vars
2. Additional information
altTitle	String that encodes title value in a different character set, and/or contains language information as per [RFC5987].	5988
description	detailed text description of the target resource content and capabilities	iso
media	indicates intended destination medium or media for style information (see Le Hors et al., 1999, Section 6.13 http://www.w3.org/TR/html401 ). Example values include 'screen', 'tty', 'print', 'braille', 'aural'... Vocabulary appears to be related to type of device (including paper as a device...) that is intended target for resource representation. Default to 'screen', and it is anticipated that other values would be only rarely required.	5988
length	Numeric value, indicates an advisory length of the linked content in octets; it is a hint about the content length of the representation returned when targetURI is dereferenced	atom, CoRE
hreflang	Three-letter language code that specifies the language of the target resource content. When used together with the rel="alternate", it implies a translated version of the target resource. Multiple "hreflang" parameters on a single link-value indicate language options that may be requested by the client.	atom, 5988
3. Function, format, schema of target
function	Term that tells client why they’d use this link. Purpose property provides mechanism for more granular, application specific indication of link semantics. Example values: 'download', ‘browsing’, 'fileAccess'. Analogous to ISO19115 CI_OnlineFunctionCode. See Table 5. Default is ‘download’.	iso
protocol	Identifier for basic messaging protocol to be used to dereference the TargetURI, e.g. http, ftp, dns, smb, nfs, smtp, pop; other identifier schemes that may not have implicit web behavior are also possible, e.g. ARK DOI EAN13 EISSN ISBN ISSN ISTC LISSN LSID UPC URN. See IETF registry at http://www.rfc-editor.org/rfcxx00.html. Protocol operating at the 'bottom' of the application layer of the OSI network protocol stack. Default is HTTP.	iso
overlayAPI	URI that identifies the API for messages that may be tunneled to client applications using the protocol specified by the 'protocol' property. URI to identify serviceType and version should be defined by the service specification.	esip, owc, iso
profile	Profile of media type specified by MIMEtype; specifies information model for content contained in messages conforming to the MIMEtype media format; note that the same output scheme might be encoded using different MIME types, so the two are somewhat orthogonal. Map to CoRE interface description.	iso, esip, HAL, CoRE
resourceType	opaque string used to assign an application-specific semantic type to a resource. One can think of this as a noun describing the resource.	CoRE
hints	Object that contains additional information about link operation/actions. ServiceType and outputScheme specific information that assists clients to find relevant information about interacting with a resource beforehand, as a means of optimizing communications, as well as advertising available behaviors (e.g., to aid in laying out a user interface for consuming the API). Home-documents draft proposes set of common hints.	home-doc
4. Operational switches
xml:base	stem for relative URI in attributes, or for CURIEs	xml
nofollow	Indicates that the context’s original author or publisher does not endorse the link target. Optional, Boolean; default is ‘False’	IANA
show	When link is to resource that is a component of the resource containing the link, indicates desired presentation of the ending resource on traversal from the starting resource. Value must be one of the values "new", "replace", "embed", "other", and "none". Used to assemble a resource 'by reference' to libraries of component parts. 'new' and 'replace' only make sense in the context of a window-based browsing application.	xlink
actuate	When link is to resource that is a component of the resource containing the link, indicates desired behavior when the containing resource is parsed or loaded into the client environment. Values: "onLoad", "onRequest", "other", and "none". Is ‘onLoad same as ‘prefetch’?	xlink
noreferrer	Indicates that no referrer information is to be leaked when following the link	IANA
prefetch	Indicates that the link target should be preemptively cached	IANA

Table 4. Compilation of relation type terms from analyzed specifications. Terms are grouped according to the scope of the relation; each attribute group is shaded with a different color and the groups are labeled with gray-shaded cells. Rel terms that specify link function are summarized separately in Table 5.

Type		Subtype		Notes	Vocabularies
Access to resource representation and description
alternate				link is to a different representation (substitute, variant, version) of the context resource. [this appears to make sense only if the context resource is a particular representation, otherwise the alternates shouldbe separate links to access the resource]	IANA, DataCite, RDFa, DCT
alternate		duplicate		link to a resource whose available representations are byte-for-byte identical with the corresponding representations of the context	IANA
alternate		isOriginalFormOf		link from the original version in version sequence to some successor version.	DataCite
alternate		isVersionOf		inverse link for isOriginalFormOf; link from a version to the original resource in a version sequence	DCT
alternate		predecessor-version		link to resource that precedes the context resource in a version history	IANA, dataCite
alternate		successor-version		link to resource that supersedes the context resource in a version history	IANA, DataCite, DCT
alternate		working-copy		link to a resource that is a revision draft for a successor resource	IANA
alternate		working-copy-of		link from a revision draft resource to the resource it is intended to supersede	IANA
browseGraphic				link to low-resolution visualization of resource, used for determination of fitness for purpose	esip, iso
browsing				link is to web application that will allow user to explore the resource content	iso
contents				link to listing of the parts of the context resource. This listing is considered a kind of feed	IANA, RDFa
current-version (iana:current)				link to current version of the context resource; MIMEtype, outputschema used to disambiguate different representations available. This is to allow advertising of specific representations. [syn: latest-version]	IANA
documentation (iana:describedBy)				online information about the resource	esip, ISO, IANA, DataCite
icon				Link to icon resource representing the link context	IANA, RDFa
index				link to index resource for searching context resource(?)	IANA, RDFa
metadata				link retrieves formal metadata record describing resource. outputScheme provides information to select metadata	esip, ISO, RDFa
monitor				Link to resource (feed) that can be used to monitor changes in the context resource. See http://tools.ietf.org/html/rfc5989. This relation type target URI apparently has to be a session Initiation Protocol (sip:) URI.	IANA
monitor		monitor-group		resource that can be used to monitor changes in a group of HTTP resources that includes the context resource. From rfc5989: The monitor-group URI corresponds only to an Resource List Server (RLS as defined in RFC 4662) and never an HTTP resource or fixed set of HTTP resources. This relation type target URI apparently has to be a session Initiation Protocol (sip:) URI.	IANA
Alternate identifiers associated with resource
bookmark				target of relationship is permanent link to use for bookmarking purposes.	IANA RDFa
canonical				target of relationship is preferred version of a set of URIs with highly similar content. It is intended to help search engines when the same or highly similar similar content is available at different URIs.	IANA
self				a link (URI) for the current context. E.g. use in search result listing to reproduce the search URI that produced the result.	IANA
Links between parts of a segmented resource
first				to the first item in the ordered collection of resources that contains the current context. (see also start and top).	IANA, DataCite, RDFa
hasPart				Generic type for links to parts of a resource	DCT
hasPart		chapter		identifier for a chapter (part) within a resource	IANA, DataCite, RDFa
hasPart		section		link to a section (part) of a collection of resource	IANA, RDFa
hasPart		subsection		[how are chapters, sections, and subsections distinguished?]	IANA, RDFa
last				last resource in the ordered collection of resources that contains the current context.	IANA, DataCite, RDFa
next				to the next item in the ordered collection of resources that contains the current context. (see also start and top).	IANA, DataCite, RDFa
prev				to the previous item in the ordered collection of resources that contains the current context. (see also start and top).	IANA, DataCite, RDFa
start				first resource in the ordered collection of resources that contains the current context.	IANA, RDFa
up				link to a parent resource in a linked hierarchy of resources.	IANA, RDFa, DCT
Links to resource specifying properties of the context resource
author				link is to Author. The author is the originating agent for a resource; this is a 'non-information' resource, thus there is some representation involved	IANA
conformsTo				dublin core relation type; explicit link to specification that resource conforms to. Normally this should be same as URI in outputScheme link parameter, but as a distinct relation element allows separate explicit link to conformance spec for target resource. Title of link should be same as outputScheme or ServiceType URI in a link rel.	DCT
copyright				Link to copyright statement that applies to the context resource	IANA, RDFa
hasFormat				if a type attribute is not a registered MIME type, or needs additional explanation, a separate hasFormat element with title={the type string} can be included.	DCT
license				Link to a resource that specifies licensing stipulations for use of context resource	IANA, RDFa
privacyPolicy				link to a Platform for Privacy Preferences (P3P) privacy scheme Policy Reference File.	RDFa
requires				link to a resource to which the context resource has a dependency. This element must be contained in a metadata description for the resource that present the requirement.	DCT
tag				a literal value (string) to be associated with the context resoruce as a finding aid	IANA
via				link to a resource that is a source of information in the context resource; interpreted here to be generic term subsuming compilation, citation, referencing. Provenance.	IANA
via		cites		link to a resource that is cited for some reason (evidence, authority, attribution) in the context resource. Distinction of Cite and Reference needs clarification	DataCite, RDFa
via		compiles		Link to resource whose content has been incorporated into the context resource	DataCite
via		references		link to a resource that provided information used in the development of the context resource. Distinction of Cite and Reference needs clarification	DataCite, DCT
Link is to related resource
appendix				link is to appendix resource	IANA, RDFa
appendix		isSupplementTo/ isSupplementedBy		subtyping is based on interpretation that an appendix is equivalent to a supplement	DataCite
archives				link to collection of resources of historical interest relative to the context resource	IANA
archives		next-archive		Navigation through archive resource-- have to maintain relationship with what the archive context is… Intention is unclear	IANA
archives		prev-archive		Navigation through archive resource-- have to maintain relationship with what the archive context is… Intention is unclear	IANA
archives		version-history		a listing (feed) that enumerates ordered collection of all versions of the context resource	IANA
collection				link gets Data Casting Collection. Function unclear; guess is a document that is a list of related resources. How is this different from esip feed?	esip
collection		feed		link is to a related RSS or ATOM feed; esip restricts to feed of feeds… only necessary if use serviceCast and dataCast as other collection subtypes	esip
documents				link to a resource that is the subject of information in the context resource	DataCite
event				link is to micro-article related to context resource [intention is somewhat unclear in esip discussions]	esip
glossary				a glossary that defines terms used in the context resource	IANA, RDFa
help				link to a help resource that provides guidance on the use and interpretation of the context resource	IANA, RDFa
isCitedBy				link to a resource that cites the context resource for some reason (evidence, authority, attribution). Distinction of Cite and Reference needs clarification	DataCite
isCompiledBy				link to resource that incorporates context resource into a compiled resource	DataCite
isCompiledBy				link to resource that incorporates context resource into a compiled resource	DataCite
isFormatOf				if resource is a format specification, this relation indicates link to resources that are examples of the format	DCT
isReferencedBy				generic type for inverse link to resource that uses information from and references (by link?) the context resource. Distinction of Cite and Reference needs clarification+C43	DataCite, DCT
isRequiredBy				inverse link for Requires--explicit link to resources that have a dependency on the context resource.	DCT
payment				this is considered a link function, not a relationship type; listed here because is IANA rel type.	IANA
related				link is to a resource that has some useful association to the context resource; generic link with essentially no semantics	IANA
related		enclosure		a related resource that is potentially large and might require special processing. [Not very useful because semantics are unclear]	IANA
replaces				link to a resource that the context resource is meant to supersede. See also 'predessor-version'. Distinction is that replace is used if resources are not a version sequence, for instance if a new specification is superseding some existing spec.	DCT
replies				link is to a resource that responds in some way to assertions or information in the context resource	IANA
stylesheet				link to resource that provides instructions for presentation of the context resource	IANA, RDFa
Function
download			link will retrieve data from web			ESIP, ISO
download	fileAccess		link is network file path specific to some local area network			iso
edit			link to a resource that can be used to edit the link's context			IANA
edit-media			link to a resource that can be used to edit media associated with the link's context			IANA
emailService			should be smtp or mailTo protocol type for user to interact with context contact agent			iso
hub			link to online web application that enables registration for notification of updates to the context (see monitor relation types…)			IANA
offlineAccess			link to online instructions for requesting the resource from the provider			iso
offlineAccess	order (iana:payment)		link to online order web application for obtaining the resource. Payment may be part of this process.			iso, IANA
service			link is to service end point that provides access to resource through some interface			esip, IANA
service	search		link to online web application to search within the described resource; not clear if ISO intention is the same (or what it is!)			iso, IANA
upload			link endpoint will accept file upload (? POST, or get web-form that user interacts with to upload a file?)			iso

Discussion

Applications implemented using the Internet typically communicate using application layer (ITU-T, 1994-07) protocols such as HTTP, FTP, or SMTP. Many applications, such as web browsers, e-mail clients, and file-transfer programs, require only the operations provided by these protocols. More complex distributed applications that are now common use various techniques to nest complex data bundles and operation invocations within messages transported via the basic application layer protocols. Three general styles have emerged in messaging schemes for such web applications: component-based (tunneling), object-based, and hypermedia-based (Amundsen, 2012-12-14).

In the component-based style, HTTP messages directed to a single web location contain requests against some component's API. The HTTP protocol is incidental, simply acting as transport to tunnel requests to the actual application. This style is illustrated by SOAP-based implementations that use XML-encoded content in HTTP POST requests to tunnel procedure calls to application components on the host machines. In the object-based style, a domain object hierarchy is defined, and application function is based on HTTP methods that create, read, update, and delete the domain objects (e.g. users, products etc.). In the hypermedia-based style, a media type is defined for messages that specify resources (users, products etc.) and possible actions (read, write, create, delete, filter, report, etc.) on those resources. The media format must be understood a priori by client applications. The object of this proposal is a hypermedia profile to specify component-based, object based, or hypermedia-based interactions, enabling a hypermedia-based application to interact with server capabilities utilizing any of the styles.

Media type

A hypermedia definition (media type) describes a processing model in terms of some collection of controls used to change application state, and the syntax and vocabulary of instructions used to guide a client in navigating application states towards a goal. A hypermedia format must enable complex application behavior using the base protocol (e.g. HTTP), specifying actions as desired side-effects. The format should not be proscriptive about how the base protocol methods are used to achieve specific goals. One server may implement a process via single POST, while another may use a PUT-POST-POST sequence for the same process. The format should be self-explanatory within the scope of semantics defined for the media type; such semantics normally take the form of vocabularies of properties used to characterize controls (e.g. links) in hypermedia documents. Presentation and description of processing options and control operation should follow consistent and uniform patterns, such that automated clients can utilize the instructions without resorting to sophisticated parsing and text analysis.

Client applications on World Wide Web use a media type specified by the content-type header in the response to an ‘HTTP GET’ to determine how to process the document. The client has to know characteristics of the media type to utilize the response content. An application will commonly be presented with a hypermedia document and need to choose from a variety of links. In order to function correctly, the software must identify the links that will access resources that are useful to the application, or meet its processing requirements. A software agent may only know how to parse CSV or NetCDF files, or might require an OGC WMS, WFS or WCS; perhaps it requires graphics encoded as SVG; it may require content encoded in particular xml schema, e.g. GeoSciML, WaterML, or a particular RDF vocabulary. A client might need to know the available options for representations of a requested resource.

Content negotiation in http allows management of these options in simple cases, but the use of MIME types to specify details of xml schema, data structure, or vocabulary does not scale. These conventions become very application- and domain-specific and MIME is intended to be a ‘standard’ that spans multiple applications and domains. To address the specifics of particular applications or domains, media-type profiles are used to add additional semantics to the media type.

The most common hypermedia control is a link, and these are the focus of this proposal. Links are machine actionable if a software application can parse the link and use the information it contains to make appropriate decisions about application progress and how to utilize the target resource. The profile specified in this document defines properties that must be specified for links to resources using the three web application styles outlined above. The specification is abstract, in that it does not proscribe a particular encoding scheme. The intention is that the properties can be implemented in hypermedia formats using various encodings like XML, JSON, RDF, etc.

Protocol and URI Scheme

Link targets are specified using a URI [RFC3986] string. Various schemes have been defined for the syntax and interpretation of URI's, e.g. http, ftp, dns, smb, nfs, pop. See the Interned Assigned Numbers Authority (IANA) registry at http://www.iana.org/assignments/uri-schemes.html for a complete list of formally registered URI schemes; there are a variety of other identifier schemes in use that are not formally registered with IANA (e.g. ARK, DOI, EAN13, EISSN, ISBN, ISSN, ISTC, LISSN, LSID, UPC), but are well known and defined within certain communities. Many of the registered schemes are associated with protocols that specify a messaging scheme to access a representation of the identified resource, and operations that may be invoked on that resource. URI syntax defined by IETF RFC-3986 specifies that "each URI begins with a scheme name" [RFC3986, section 1.1.1]. Thus, if a link target is specified by a URI whose URI scheme has a known binding with an internet messaging protocol, this protocol does not have to be explicitly specified by an additional property associated with the link.

The World Wide Web is a network of linked resources based on the HyperText Transfer Protocol (HTTP [RFC2616]) and the Internet. HTTP offers a simple set of requests for interactions between networked resources. As the complexity of client-server and distributed applications using the World Wide Web has evolved, various schemes have been developed to utilize HTTP to implement networked programming interfaces with other operations and messaging schemes. Simple Object Access Protocol (SOAP [SOAP]) and Microsoft RPC-over-HTTP [MSRPC] are two examples of such schemes. In these models, interaction (procedure calls) between software agents is through a communication protocol that is 'tunneled' through an HTTP messaging channel. Although a link to a resource based on this Remote Procedure Call (RPC) over HTTP approach may have a URI that uses the 'http:' URI scheme, the important protocol that must be specified for the link is the protocol that is tunneled through HTTP. Similar schemes may be implemented on other URI schemes that have defined messaging protocols. Protocols specific to particular applications that are layered on the base protocol specified by the URI scheme are indicated using overlayAPI and profile properties.

URI Templates

Another common approach to developing networked applications is to define a collection of resources and parameters on the resource that allow a pattern- and rule-based scheme to access particular resource instances. Interaction with the resource instances is based on standard HTTP operations to create, read, update, and delete instances. A URI template [RFC6570] defines URI syntax with parameters that may be assigned values to access particular resources. The OpenSearch specification [OpenSearch1.1] is a widely used example of this approach. Link descriptions in hypermedia documents must also be able to provide sufficient information to enable a software agent to utilize these kind of network applications.

Proposed solution for machine actionable links

In order for software client to utilize a link, it first must understand the URI scheme for the link identifier and how to dereference that kind of URI. Table 6 lists elements that are considered most important for characterizing machine actionable links. This information could conceivably all be encoded in the MIME type, perhaps even utilizing some structured syntax to allow analysis of the MIME type string to extract some of these properties. It would lead to a massive proliferation of MIME types of increasing length and complexity. The solution favored here is to define properties with specific semantics that characterize link operation.

Table 6. Proposed properties for useful machine-actionable links.

property	scope notes
linkage (syn: href, targetURI)	URI that identifies the resource that is the target of the link. Mandatory. MUST use a URI scheme that can be dereferenced on the WWW. This is typically an http URI.
title	Free text to label the link in user interfaces. Optional. The content of the "title" attribute is Language-Sensitive. Entities such as "&" and "<" represent their corresponding characters ("&" and "<", respectively), not markup. Link elements MAY have a title attribute. The "title" parameter MUST NOT appear more than once in a given link-value; occurrences after the first MUST be ignored by parsers.
type	Media type of response, specified by registered MIME media format. Mandatory, default value text/html. The intention is that the type is known to be offered by the host that the targetURI accesses, but this should not be assumed. The Content-Type header of the response obtained by dereferencing targetURI should be checked to verify the actual response media type. There MUST NOT be more than one type parameter in a link-value; occurrences after the first MUST be ignored by parsers. If multiple media type representations are available, they should be indicated by separate link elements. This property is about the target of the link. If the target resource is in a container file (e.g. zip, tar…) the MIME type identifies the container, and the file type of the contained resource should be specified in an 'InnerResourceType' property.
rel	Semantics of link (see discussion in Coyle, 2010 p. 19). Mandatory. Term from IANA rel vocabulary should be included for consistency with IETF RFC-5988. Recommendation is to use the Terms not namespace qualified, following guidance in Atom Specification RFC-4287, section 4.2.7.2. Other domain-specific terms, not from IANA registry MAY be included; these SHOULD be namespace qualified. Multiple rel values are separated by comma; a rel value string MUST be quoted if it contains a comma (","). This property provides guidance on the relationship between the resource that contains the link and the target resource; generally it will be used by applications to determine the purpose of traversing/actuating the link.
overlayAPI	URI that identifies the API for messages tunneled to a component on the target server. Optional, provide if such scheme or protocol is necessary to utilize the link. The URI should be defined by the service specification for the protocol or service type; version information should be included if applicable. E.g. OGC WMS, WS-services. This property is typically used for services that encode remote procedure calls using identifiers dereferenced using standard HTTP methods (GET, POST).
template	URI that identifies a template scheme for describing a range of Uniform Resource Identifiers through variable expansion. Optional, if a value is provided for this attribute, the targetURI MUST be interpreted as a template conforming to the identified template scheme. Template scheme defines the valid variable names that may appear in the template, and any restrictions or conventions for the values that may be substituted in valid URIs under the scheme. Note that a profile may also be specified that further restricts or specifies conventions for variable substitution. The service specification should define the URI that identifies the template scheme and version. Typically used for services that implement CRUD against a resource scheme using HTTP verbs.
profile	Identifier for profile of specifications identified by type, overlayAPI, and template attributes. Optional, provide if additional conventions are necessary for content contained in messages through this link. Note that the same output scheme might be encoded using different types. Profiles typically add usage conventions when the interchange scheme offers alternate approaches, restrict cardinality for elements in the interchange format, or specify usage of particular vocabularies.
parameters	name/value pairs for other specific parameters necessary to automate usage of the link. E.g. WMS layer name or WFS feature type.

Other properties that may be useful (all optional)
altTitle	String that encodes title value in a different character set, and/or contains language information as per [RFC5987].
behavior	A comma separated list of properties specifying behavior expected in client when link is actuated. See Table 7 for list of values.
descriptionURL	detailed text description of what the online resource is/does. Since is not considered good practice to put extensive text in an element attribute, implement by reference with a url for an html description page.
hints	Object with additional, profile-specific information about link operation; granular to protocol or overlayAPI method level. Object provides additional information to allow clients to interact with a resource beforehand, as a means of optimizing communications, as well as advertising available behaviors (e.g., to aid in laying out a user interface for consuming the API). Home-documents draft proposes set of common hints as an example.
hreflang	describes the language of the resource pointed to by the linkage attribute. When used together with the rel="alternate", it implies a translated version of the entry. Multiple "hreflang" parameters on a single link-value indicate language options that may be indicated by the client.
length	Indicates an advisory length of the linked content in octets; it is a hint about the content length of the representation returned when linkage identifier is dereferenced
innerResourceType	File type for a resource that is 'wrapped' in a container file for delivery, e.g. inside a zip archive.

Table 7. Vocabulary for specifying link behavior property.

Term	Explanation
actuateOnLoad	equivalent to ‘onLoad’ value for xlink:actuate property.
actuateOnRequest	equivalent to ‘onRequest’ value for xlink:actuate property.
nofollow	if property is specified, indicates that the context’s original author or publisher does not endorse the link target.
noreferrer	if property is specified, indicates that no referrer information is to be leaked when following the link
prefetch	if property is specified, indicates that the link target should be preemptively cached
showembed	equivalent to ‘embed’ value for xlink:show property.
showreplace	equivalent to ‘show’ value for xlink:show property.

Appendix 1. Examples

These are in progress. Please add or make corrections (track changes…)

OpenSearch link in ESIP discovery/data cast

Link property	Value
linkage	http:// http://mirador.gsfc.nasa.gov/cgi-bin/mirador/collectionlist.pl? keyword={searchTerms}
rel	search
title	Search template for Mirador keyword search
type	application/atom+xml
overlayAPI
template	http://a9.com/-/spec/opensearch/1.1
profile	http://commons.esipfed.org/ns/discovery/1.2/collectionCast#
description	Search service for a collection cast entry

link to opensearch description

Link property	Value
linkage	http://mirador.gsfc.nasa.gov/mirador-plugin-search.xml
rel	documentation
title	Opensearch description for accessing this collection
type	application/opensearchdescription+xml
overlayAPI
template
profile	http://commons.esipfed.org/ns/discovery/1.2/collectionCast#
description	Point to a search service from a collection cast entry

OGC Web Feature Service link

link to get some features.

Link property	Value
linkage	http://kgs.uky.edu/arcgis/services/aasggeothermal/ARSeismicHypocenters/MapServer/WFSServer?request=GetFeature&service=WFS&TypeName=Hypocenter&MaxFeatures=10
rel	download
title	Example WFS getFeature request for NGDS seismic event hypocenters
type	application/gml+xml
overlayAPI	OGC:WFS
template
profile	http://stategeothermaldata.org/uri-gin/aasg/xmlschema/hypocenter/1.7
parameter	typeName=Hypocenter

link to get the self-description document for an OGC feature service.

Link property	Value
linkage	http://kgs.uky.edu/arcgis/services/aasggeothermal/ARSeismicHypocenters/MapServer/WFSServer?request=GetCapabilities
rel	documentation
title	Get the capabilities document for seismic event hypocenter
type	application/xml
overlayAPI	OGC:WFS
template
profile	http://stategeothermaldata.org/uri-gin/aasg/xmlschema/hypocenter/1.7
parameter	typeName=Hypocenter

OGC Web Feature Service link

Template for get feature request.

Link property	Value
linkage	http://kgs.uky.edu/arcgis/services/aasggeothermal/ARSeismicHypocenters/MapServer/WFSServer?request=GetFeature&service=WFS&TypeName=Hypocenter&bbox={geo:box}
rel	template
title	Template for WFS getFeature request for NGDS seismic event hypocenters with bounding box filter
type	application/gml+xml
overlayAPI	OGC:WFS
template	http://a9.com/-/opensearch/extensions/geo/1.0/
profile	http://stategeothermaldata.org/uri-gin/aasg/xmlschema/hypocenter/1.7
parameter	typeName=Hypocenter

OpenDAP endpoint

DAP-URL = "http://" host [ ":" port ] [ abs-path ]

abs-path = server-path data-source-id [ "." ext [ "?" query ] ]

server-path = [ "/" token ]

data-source-id = [ "/" token ]

ext = "das" | "dds" | "dods"

token = <See IETF RFC 2396 for allowable characters>

Link property	Value
linkage	http://test.opendap.org:80/opendap/data/nc/ber-2002-10-01.nc.nc
rel	download
title	example NetCDF file retrieval via OpenDAP
type	application/x-netcdf
overlayAPI	OpenDAP
template
profile	http://test.opendap.org:80/opendap/data/nc/ber-2002-10-01.nc.dds

WS service

with SOAP

Link property	Value
linkage	http://footballpool.dataaccess.eu/data/info.wso?WSDL
rel	documentation
title	Worldcup 2010 Football Championships
type	text/xml
overlayAPI
template
profile	http://www.w3.org/TR/wsdl20/

ESRI geoservice

endpoint

Link property	Value
linkage	http://services.azgs.az.gov/ArcGIS/rest/services/fissures/EarthFissures/MapServer?f=json
rel	documentation
title	Earth Fissures ESRI vector map service
type	application/json
overlayAPI	ESRI MapService 10.0
template
profile

TileMill map service

Link property	Value
linkage	http://a.tiles.mapbox.com/v3/examples.map-zr0njcqy.json
rel	documentation
title	DC Weekend Picks tile map from MapBox
type	application/json
overlayAPI
template
profile	tilejson:2.0.0

Link property	Value
linkage	http://a.tiles.mapbox.com/v3/examples.map-zr0njcqy/{z}/{x}/{y}.png
rel	template
title	DC Weekend Picks tile map from MapBox
type	image/png
overlayAPI
template	http://a.tiles.mapbox.com/v3/examples.map-zr0njcqy.json
profile	tilejson:2.0.0

OWS context link

Link property	Value
linkage
rel
title
type
overlayAPI	http://www.opengis.net/spec/owc-atom/1.0/req/wfs
template
profile

CSW catalog

Identify catalog that uses USGIN ISO metadata profile

Link property	Value
linkage	http://catalog.usgin.org/geoportal/csw?request=GetCapabilities&service=CSW
rel	documentation
title	Capabilities document for USGIN CSW 2.0.2 service
type	application/xml
overlayAPI	OGC:CSW
template
profile	ISO-USGIN

macrostrat endpoint

Shanan Peters' services

Link property	Value
linkage
rel
title
type
overlayAPI
template
profile

IRIS seismic data web service

Link property	Value
linkage	http://service.iris.edu/fdsnws/event/1/application.wadl
rel	documentation
title	WADL description of event service
type	application/xml
overlayAPI
template
profile	http://service.iris.edu/fdsnws/event/1/

Link to home document

for an NGDS node

Link property	Value
linkage
rel
title
type
overlayAPI
template
profile

References and related reading

[MSRPC] Remote Procedure Calls Using RPC over HTTP (Windows): web page http://msdn.microsoft.com/en-us/library/windows/desktop/aa375384(v=vs.85).aspx (accessed 2013-02-26).

[OpenSearch1.1] Clinton, DeWitt, no date, OpenSearch 1.1 specification, Draft 5: Web Document, http://www.opensearch.org/Specifications/OpenSearch/1.1 (accessed 2013-02-26).

[RDF-xlink] Brickley, Dan, 2000-09-08, Notes on RDF, Xlink as linked information systems: http://www.w3.org/2000/02/rdf-xlink/ accessed 2010-02-07

[RFC 2616] Fielding, R., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and Berners-Lee, T., 1999-06, Hypertext Transfer Protocol -- HTTP/1.1: RFC2616, accessed at http://tools.ietf.org/html/rfc2616 (accessed 2010-02-19).

[RFC 3986] Berners-Lee, T., Fielding, R., and Masinter, L., 2005-01, Uniform Resource Identifier (URI): Generic Syntax: IETF RFC 3986, http://www.ietf.org/rfc/rfc3986.txt.

[RFC 5023] Gregorio, J.C., and deHora, B., editors, 2007-10, The Atom Publishing Protocol: IETF RFC 5023 http://www.ietf.org/rfc/rfc5023.txt (accessed 2013-02-26).

[RFC 6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and Orchard, D., 2012-03, URI Template: Internet Engineering Task Force (IETF) Request for Comments RFC-6570, http://tools.ietf.org/html/rfc6570 (accessed 2013-02-26).

[RFC 6690] Shelby, Z., 2012-08, Constrained RESTful Environments (CoRE) Link Format, : Internet Engineering Task Force (IETF) Request for Comments RFC-6690, http://tools.ietf.org/html/rfc6690 (accessed 2013-04-03).

[SOAP] W3C, 2007-04-27, Latest SOAP Versions, http://www.w3.org/TR/soap/ (accessed 2013-02-26).

Adida, Ben, Birbeck, Mark, McCarron, Shane, and Pemberton, Steven, editors, 2008-10-14, RDFa in XHTML: Syntax and Processing, A collection of attributes and processing rules for extending XHTML to support RDF: W3C Recommendation 14 October 2008, accessed at http://www.w3.org/TR/2008/REC-rdfa-syntax-20081014, 2011-09-30.

Amundsen, Mike, 2012-12-14, Three Common Web Architecture Styles: web page, http://www.layer7tech.com/blogs/index.php/three-common-web-architecture-styles/, accessed 2013-02-18.

Booth, David, 2003-01-28, Four uses of a URL: Name, Concept, Web Location and Document instance: accessed at http://www.w3.org/2002/11/dbooth-names/dbooth-names_clean.htm (2010-02-15).

Charlton, Stuart, 2012-09-14, Linking Data and Actions on the Web: Slides from Keynote address at RESTfest 2012, accessed at https://github.com/restfest/2012-greenville/wiki/Keynote (2013-02-22).

Coyle, Karen, 2010, Understanding the Semantic Web: Bibliographic Data and Metadata: Library Technology Reports, v.46, American Library Association, 31 p., ISSN 0024-2586

Duerst, M., and Suignard, M., January 2005, Internationalized Resource Identifiers (IRIs): IETF RFC-3987, accessed at http://www.ietf.org/rfc/rfc3987.txt .

Fielding, Roy T., 2008, REST APIs must be hypertext-driven: Untangled, Web BLOG, http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven (accessed 2013-01-25).

Fielding, Roy T., 2000, Architectural Styles and the Design of Network-based Software Architectures [Ph. D. dissertation]: Irvine, CA, University of California, accessed at http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm (2013-07-05).

Halpin, Harry, and Presutti, Presutti, 2009, An Ontology of Resources for Linked Data: LDOW 2009, April 20–24, 2009, Madrid, Spain, ACM 978-1-60558-487-4/09/04, http://events.linkeddata.org/ldow2009/papers/ldow2009_paper19.pdf (accessed 2011-09-03).

ISO19115 WG, in prep, ISO 19115-1 Geographic information — Metadata – Part 1: Fundamentals: ISO TC211 N3071

ISO19119, 2005-02-15, Geographic Information—Services.

ISO19119:2005/Amd.1, 2008-05-01, Geographic information — Services, AMENDMENT 1: Extensions of the service metadata model.

ITU, 1994, Information Technology – Open Systems Interconnection – Basic Reference Model: The Basic Model: ITU-T Recommendation X.200, 63 pages.

ITU-T, 1994-07, Information Technology-Open Systems Interconnection – Basic Reference Model: The Basic Model: International Telecommunications Union Recommendation X.200, 63 p. Accessed at http://www.itu.int/rec/T-REC-X.200-199407-I/en (2013-02-23)

Le Hors, A., Raggett, D., and I. Jacobs, December 1999, HTML 4.01 Specification, W3C Recommendation REC-html401-19991224, <http://www.w3.org/TR/1999/REC-html401-19991224>. Latest version available at <http://www.w3.org/TR/html401>.

Linked Data for the Web, http://www.rdfabout.com/intro/?section=8 accessed 2010-02-07

Mendelsohn, Noah, and Williams, Stuart, 2007-01-02, The use of Metadata in URIs: W3C TAG Finding, accessed at http://www.w3.org/2001/tag/doc/metaDataInURI-31-20070102.html.

Nottingham, M., 2013-05-08, Home Documents for HTTP APIs -03: IETF Network Working Group Internet Draft draft-nottingham-json-home, http://tools.ietf.org/html/draft-nottingham-json-home

Nottingham, M., and Sayre, R., eds., 2005, The Atom Syndication Format: IETF Network Working Group Request for Comments RFC-4287, http://www.ietf.org/rfc/rfc4287.txt .

Nottingham, M., ed., 2010, Web Linking: IETF RFC-5988, ISSN:2070-1721, http://www.ietf.org/rfc/rfc5988.txt.

Rosinger, David, and Tillman, Stan, eds., 2010-06-24, OGC® OWS-7 Information Sharing Engineering Report: Open Geospatial Consortium, Inc., document OGC 10-035r1, accessed at https://portal.opengeospatial.org/files/?artifact_id=40031&version=1 (OCG members only).

Starr, Joan (head of working group) and DataCite Metadata Working Group, 2011-07, DataCite Metadata Schema for the Publication and Citation of Research Data, version 2.2: DOI:10.5438/0005, http://schema.datacite.org/meta/kernel-2.2/doc/DataCite-MetadataKernel_v2.2.pdf (accessed 2011-09-30).

USGIN Standards and Protocols Drafting Team, 2010-11, Use of ISO metadata specifications to describe geoscience information resources, Doc ID gin2010-009, available at http://repository.usgin.org/uri_gin/usgin/dlio/337.

van Kesteren, A., Glazman, D., Lie, H., and T. Celik, September 2009, "Media Queries", W3C Candidate Recommendation CR-css3-mediaqueries-20090915, <http://www.w3.org/TR/2009/CR-css3-mediaqueries-20090915/>.

Glossary

identifier: a string that is intended to correspond to a specific, particular resource

link: an object that has the purpose of enabling access to a resource, a representation of a resource, or some method offered by the resource.

Protocol: a scheme for messaging between two agents, defining what requests are supported, how requests and responses (both normal and for error conditions) are encoded, and how messages are addressed and directed to the proper recipient.