Link Properties Proposal
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.
see Content model for hypermedia affordances for a complete discussion
| 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" at-tribute 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. |
| 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 pro-cedure 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; ideally these URI strings should be registered in the cat-interop lookup table for interoperability. Typically used for services that implement CRUD against a resource scheme using HTTP verbs. |
| profile(syn: applicationProfile) | 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 to target different profiles. 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. The profile should be specific enough to understand what particular applications will work with the content at the linkage URL. |
| parameters | name/value pairs for other specific parameters necessary to automate usage of the link. E.g. WMS layer name or WFS feature type. |
These might logically be implemented as parameter key-value pairs.
| property | scope notes |
| 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 [Content model for hypermedia affordances](https://github.com/usgin/usginspecs/blob/master/MetadataAsHypermediaApp.docx?raw=true) 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 |
see Content model for hypermedia affordances Appendix 1 for example link properties for various kinds of services and end points.
Here's some examples of what the content of a dct:references element would look like if a JSON representation of this link representation was used as the encoding for a machine actionable link:
{ "link":"http://mirador.gsfc.nasa.gov/mirador-plugin-search.xml", "rel":"documentation", "title":"OpenSearch description for accessing this colleciton", "type":"application/opensearchdescription+xml", "profile":"http://commons.esipfed.org/ns/discovery/1.2/collectionCast#", "description":"point to a search service from a ESIP collection cast entry" }
{ "link":"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", "profile":"http://stategeothermaldata.org/uri-gin/aasg/xmlschema/hypocenter/1.7", "parameter":"typeName=Hypocenter" }
{ "link":"http://kgs.uky.edu/arcgis/services/aasggeothermal/ARSeismicHypocenters/MapServer/WFSServer?request=GetCapabilities", "rel":"documentation", "title":"Get the capabilities document for seismic event hypocenter WFS service", "type":"application/xml", "overlayAPI":"OGC:WFS" }
/* OpenSearch link in ESIP discovery/data cast
{ "link":"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", "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" }
/* OpenDAP endpoint
{ "link":"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", "profile":"http://test.opendap.org:80/opendap/data/nc/ber-2002-10-01.nc.dds" }