FAIR Signposting Profile

Prepared by: Herbert Van de Sompel, Martin Klein, Shawn Jones, Michael L. Nelson, Simeon Warner, Anusuriya Devaraju, Robert Huber, Wilko Steinhoff, Vyacheslav Tykhonov, Luc Boruta, Enno Meijers, Stian Soiland-Reyes, Mark Wilkinson
This version, created 20231002: https://signposting.org/FAIR/
Previous version created 20230519
Version history
Please provide feedback in the GitHub Signposting repository

This page details concrete recipes that platforms that host research outputs (e.g. data repositories, institutional repositories, publisher platforms, etc.) can follow to implement Signposting, a lightweight yet powerful approach to increase the FAIRness of scholarly objects.
Landing pages support humans that interact with scholarly objects on the web, providing descriptive metadata and links to content. These pages are not optimized for use by machine agents that navigate the scholarly web. For example, how can a robot determine which links on the myriad of landing pages lead to content and which to metadata? Signposting caters to machine agents by providing this information, and more, in a standards-based way. It contributes to FAIR's Findable, Accessible, and Reusable by uniformly conveying to machines what the persistent identifier of a scholarly object is, where its landing page is, where and what its content is, where metadata that describes it is, and what the persistent identifier of its author is. It conveys this by means of meaningful links that have web locations (HTTP URIs) as their target.
Signposting the Scholarly Web: FAIR Signposting

Image courtesy of Patrick Hochstenbach.


As such it does significantly more than merely providing the information. It invites machine agents to follow the links to their target location on the web, and hopefully find further information and links there. It essentially provides them with a map to guide their travels across the scholarly web. Signposting contributes to FAIR's Interoperable through its uniform approach and because it is entirely based on widely implemented web protocols specified in IETF RFCs. As such, the interoperability that results from adopting it is not restricted to the scholarly landscape but encompasses the web at large.
The recipes provided in this document take a gradual approach towards increasing FAIRness for scholarly resources by means of Signposting:
  • Level 1 requires providing a minimal set of typed links via HTTP Link headers and/or HTML <link> elements. Despite its simplicity, it already significantly improves the ability of machine agents to navigate the scholarly web.
  • Level 2 requires providing a comprehensive set of typed links via a Link Set and making that Link Set discoverable. It increases the action radius of machine agents and provides them with a complete map of a scholarly object.
"Signposting has a ridiculously low cost of entry (if you serve scholarly content over HTTP, you're already almost there)" - Luc Boruta in GitHub feedback on this document.

"FAIR Signposting resolves many ambiguities that arise when resolving persistent identifiers to data or landing pages. Signposting's typed links help bots to navigate digital objects on the web in an informed manner." - Mark Wilkinson in CoRDI2023 keynote.

"We should enable Signposting in our Open Access repositories. This will immediately remove the long-standing obstacle of opaque splash pages in repositories. With Signposting, third-party systems and services will reliably navigate from these splash pages to more machine-actionable metadata and content. This is a no-brainer: there is no downside, minimal investment is needed, and the rewards from truly opening up our repository content to play their part in open-science are significant. Let's just do this!" - Paul Walk, Antleaf & COAR Notify.

Make it so!

Table of Contents

  1. Introduction
    1. A Scholarly Object on the Web
    2. Typed Links
    3. Typed Links in the FAIR Signposting Profile
    4. Typed Links Provided in Link Sets
  2. Recipes for Implementing the FAIR Signposting Profile
    1. Level 1 - A Minimal Set of Typed Links via the HTTP Link header and/or HTML <link>
      1. Level 1 - Typed Links Pertaining to the Landing Page
      2. Level 1 - Typed Links Pertaining to Content Resources and Metadata Resources
    2. Level 2 - A Comprehensive Set of Typed Links via a Link Set
      1. Level 2 - Typed Links Pertaining to the Landing Page
      2. Level 2 - Typed Links Pertaining to Content Resources
      3. Level 2 - Typed Links Pertaining to Metadata Resources
  3. Examples
    1. Examples Level 1
    2. Examples Level 2

1. Introduction

1.1. A Scholarly Object on the Web

It has become common to publish scholarly objects on the web as a set of web resources, each equipped with an HTTP URI. A scholarly object typically has:

scholarly object on the web

1.2. Typed Links

Typed links are more expressive than plain href links in HTML. They actually express the nature of the relationship between the origin and the target of the link. Note that, in this document, the term origin is used as an intuitive synonym for the term link context, which is used in the Web Linking RFC8288 that defines typed web links.

The IANA Link Relation Registry lists a wide range of relation types that are described in formal specifications such as IETF RFCs. Using relation types from that Registry yields web-scale interoperability and therefore the FAIR Signposting Profile builds on it.
There are 3 approaches to convey typed links:
  1. For HTML pages: Using the HTML <link> element in the head section of the HTML.
  2. For web resources of any media type: Using Link in the HTTP response header.
  3. For web resources of any media type: Using a standalone document called a Link Set that is made discoverable by means of a typed link with the linkset relation type. More details on Link Set are provided in Section 1.4
Approach (2) has significant advantages:
Approach (3) has the same advantages as approach (2) but additionally allows to convey large numbers of links without running the risk that the HTTP header becomes too large to be handled by the web server.

1.3. Typed Links in the FAIR Signposting Profile

The Relation Types that are used for the FAIR Signposting Profile as a means to meaningfully interlink resources that represent a scholarly artifact on the web are shown in the below table. The general description of their meaning is based on the more formal language used in the specification that define them. Their specific use for the FAIR Signposting Profile is provided in the descriptions of Level 1 and Level 2, below.

Relation Type Description
author The target of the link is a URI for an author of the resource that is the origin of the link.
cite-as The target of the link is a persistent URI for the resource that is the origin of the link.
describedby The target of the link provides metadata that describes the resource that is the origin of the link.
describes The origin of the link is a resource that provides metadata that describes the resource that is the target of the link. It is the inverse of the describedby relation type.
type The target of the link is the URI for a class of resources to which the resource that is the origin of the link belongs.
license The target of the link is the URI of a license that applies to the resource that is the origin of the link.
item The origin of the link is a collection of resources and the target of the link is a resource that belongs to that collection. It is the inverse of the collection relation type.
collection The origin of the link is a resource that belongs to a collection and the target of the link is the collection to which it belongs. It is the inverse of the item relation type.

1.4. Typed Links Provided in Link Sets

Link Sets are specified in RFC9264, Linkset: Media Types and a Link Relation Type for Link Sets:
Link Sets

2. Recipes for Implementing the FAIR Signposting Profile

This section describes two complementary approaches to convey typed links: the Level 1 and Level 2 recipes. They differ regarding the way in which typed links are conveyed and regarding the extent of the set of typed links that is conveyed:
Implementing the Level 1 recipe entails:

2.1. Level 1 - A Minimal Set of Typed Links via the HTTP Link header and/or HTML <link>

Implementing the Level 1 recipe entails:
This Level aims for uniformity for machine agents that navigate scholarly resources. The limitation for the number of links that must be provided avoids that HTTP headers become too large.
2.1.1. Level 1 - Typed Links Pertaining to the Landing Page
The below image and table show the links with the landing page as link origin that are to be provided when implementing Level 1 of this recipe. In the image: Examples are provided in Section 3.1.
Level 1 of FAIR Signposting, Landing Page
Link Relation Type Link Cardinality Comment
author 0 or more For each author of the scholarly object that has a persistent identifier (e.g. ORCID expressed as HTTP URI), provide a link that has the landing page as link origin and the persistent identifier of the author as target. Be aware that the number of authors for a scholarly object can be large. As such, in order to avoid the risk of the HTTP header becoming too large, it may be safer to provide links for a limited number of authors in the HTTP header and to provide them for all when using Link Sets in Level 2.
cite-as 1 Provide a link that has the persistent identifier of the scholarly object (e.g. DOI expressed as an HTTP URI) as target. Note that dereferencing the target of a link with a cite-as relation type must lead to the landing page that provided that cite-as link. Do not use a cite-as link to point at a persistent identifier that does not resolve to the landing page. For persistent identifiers that are associated with the scholarly object but that do not resolve to its landing page, use links with the related link relation type.
describedby 1 or more Provide one or more links that have the URI of metadata that describes the scholarly object in a commonly used format as target. On each link, provide the media type of the metadata in the type attribute. Common media types include
application/x-bibtex (BibTeX),
application/vnd.citationstyles.csl+json (CiteProc JSON),
application/x-research-info-systems (RIS),
application/vnd.datacite.datacite+xml (DataCite XML),
application/vnd.datacite.datacite+json (DataCite JSON),
application/vnd.jats+xml (JATS),
application/vnd.codemeta.ld+json (Codemeta),
text/x-bibliography (Formatted text citation).
Many other bibliographic formats are in use that have text/plain, application/xml, application/json, or application/ld+json as media type. When providing metadata that describes the scholarly object using these media types, use profile as an extension target attribute on the link to convey, by means of an HTTP URI, the specific format of the metadata. For example, for metadata expressed as application/xml, provide the XML Namespace URI in the profile extension attribute.
item 0 or more The landing page is modeled as a collection of content resources. As such, provide links that have content resources (e.g. the PDF article, the CSV dataset, the ZIPped software repository) as target. Use the type attribute on each link to convey the media type of the content resource. If specificity beyond the media type is required to indicate the nature of a content resource, use profile as an extension target attribute on the link to convey, by means of an HTTP URI, the more specific format of the content resource. Be aware that the number of content resources for a scholarly object can be unpredictably large. As such, in order to avoid the risk of the HTTP header becoming too large, it may be safer to only provide links for a limited number of content resources in the HTTP header and provide links for all when using Link Sets in Level 2.
license 0 or 1 If the license under which the scholarly object is made available is known, provide a link that has as target the URI of that license. Valid licenses include the ones listed at SPDX, in which case the use of an SPDX license identifier (e.g. https://spdx.org/licenses/CC0-1.0, not https://spdx.org/licenses/CC0-1.0.html) is encouraged. But licenses may also include other means of expressing permissions to use the object such as terms of service.
type 2 (in most cases) or 1 Provide a first link that has as target the schema.org term (HTTP URI) for a Creative Work that best characterizes the scholarly object as a whole. For example, provide https://schema.org/ScholarlyArticle in case the object is a scholarly paper; provide https://schema.org/Dataset if it is a dataset. If no appropriate term is available in https://schema.org/, select one (HTTP URI) from a commonly used ontology.
Provide a second link that has as target https://schema.org/AboutPage in the common case where an actual landing page is concerned. Do not provide this second link in case a content resource is concerned, i.e. do not provide this second link when the persistent identifier of the scholarly object directly resolves to a content resource, such as an HTML article, without presenting an intermediate landing page.
2.1.2. Level 1 - Typed Links Pertaining to Content Resources and Metadata Resources
The below image and table show the links with content resources and metadata resources as link origin that need to be provided when implementing Level 1 of this recipe. In the image: Examples are provided in Section 3.1.
Level 1 of FAIR Signposting, Content Resources
Link Relation Type Link Cardinality Comment
cite-as 0 or 1 Provide a link only if the content resource has a persistent identifier that is distinct from the persistent identifier of the scholarly object as a whole. In this case, provide a link that has the content resource as origin and the persistent identifier of the content resource (e.g. handle expressed as an HTTP URI) as target. Do not provide a link that expresses the persistent identifier of the scholarly object as a whole.
collection 1 For each content resource, provide a link that has the content resource as origin and the landing page as target.
describes 1 For each metadata resource, provide a link that has the metadata resource as origin and the landing page as target.
license 0 or 1 Provide a link only if the content resource is made available under a license that is distinct from the license that applies to the scholarly object as a whole. In this case, provide a link that has as target the URI of that license. Valid licenses include the ones listed at SPDX, in which case the use of an SPDX license identifier (e.g. https://spdx.org/licenses/CC0-1.0, not https://spdx.org/licenses/CC0-1.0.html) is encouraged. But licenses may also include other means of expressing permissions to use the object such as terms of service. Do not provide a link that expresses the license of the scholarly object as a whole.
type 0 or 1 Provide a link only if the type of the content resource differs from the type that best characterizes the scholarly object as a whole. In this case, provide a link that has as target the schema.org term (HTTP URI) for a Creative Work that best characterizes the content resource. If no appropriate term is available in https://schema.org/, select one (HTTP URI) from a commonly used ontology. For example, if the scholarly object as a whole is best characterized as a scholarly paper (https://schema.org/ScholarlyArticle type is provided at the landing page), and the content resource is a dataset, provide a link that has https://schema.org/Dataset as target.

2.2. Level 2 - A Comprehensive Set of Typed Links via a Link Set

Implementing the Level 2 recipe entails:
The Link Set that is made available at Level 2 combines links that have the landing page as link origin (Section 2.2.1.), links that have each of the content resources as link origin (Section 2.2.2.), and links that have each of the metadata resources as link origin (Section 2.2.3.). Such a Link Set provides machine agents with a complete map of the scholarly object and is easily cacheable. The below image illustrates the approach.
Link Sets Merged
2.2.1. Level 2 - Typed Links Pertaining to the Landing Page
The below image and table show the links with the landing page as link origin that must be conveyed in a Link Set when implementing the Level 2 recipe. In the image: Examples are provided in Section 3.2.
Link Set, Landing Page links
Link Relation Type Link Cardinality Comment
author 0 or more For each author of the scholarly object that has a persistent identifier (e.g. ORCID expressed as HTTP URI) provide a link that has the landing page as origin and the persistent identifier as target. Only if none of the authors have a persistent identifier should there be no links with this relation type.
cite-as 1 Provide a link that has the persistent identifier of the scholarly object (e.g. DOI expressed as an HTTP URI) as target. Note that dereferencing the target of a link with a cite-as relation type must lead to the landing page that provided that cite-as link. Do not use a cite-as link to point at a persistent identifier that does not resolve to the landing page. For persistent identifiers that are associated with the scholarly object but that do not resolve to its landing page, use links with the related link relation type.
describedby 1 or more Provide one or more links that have the landing page as origin and the URI of metadata that describes the scholarly object in a commonly used format as target. On each link, provide the media type of the metadata in the type attribute. For common media types see the description of describedby in Level 1.
item 1 or more For each content resource, provide a link that has the landing page as origin and the content resource (e.g. the PDF article, the CSV dataset, the ZIPped software repository) as target. Use the type attribute on each link to convey the media type of the content resource. If specificity beyond the media type is required to indicate the nature of a content resource, use profile as an extension target attribute on the link to convey, by means of an HTTP URI, the more specific format of the content resource.
license 0 or 1 If the license under which the scholarly object is made available is known, provide a link that has as target the URI of that license. Valid licenses include the ones listed at SPDX, in which case the use of an SPDX license identifier (e.g. https://spdx.org/licenses/CC0-1.0, not https://spdx.org/licenses/CC0-1.0.html) is encouraged. But licenses may also include other means of expressing permissions to use the object such as terms of service.
type 2 (in most cases) or 1 Provide a first link that has as target the schema.org term (HTTP URI) for a Creative Work that best characterizes the scholarly object as a whole. For example, provide https://schema.org/ScholarlyArticle in case the object is a scholarly paper; provide https://schema.org/Dataset if it is a dataset. If no appropriate term is available in https://schema.org/, select one (HTTP URI) from a commonly used ontology.
Provide a second link that has as target https://schema.org/AboutPage in the common case where an actual landing page is concerned. Do not provide this second link in case a content resource is concerned, i.e. do not provide this second link when the persistent identifier of the scholarly object directly resolves to a content resource, such as an HTML article, without presenting an intermediate landing page.
2.2.2. Level 2 - Typed Links Pertaining to Content Resources
The below image and table show the links that must be conveyed in a Link Set for each content resource when implementing Level 2 of this recipe. Examples are provided in Section 3.2.
Link Set, Content Resource links
Link Relation Type Link Cardinality Comment
author 0 or more Provide links only if the content resource has authorship that is distinct from that of the scholarly object as a whole. In this case, for each author of the content resource that has a persistent identifier (e.g. ORCID expressed as HTTP URI), provide a link with with the content resource as origin and that persistent identifier as target. Do not provide links that express the authorship of the scholarly object as a whole.
cite-as 0 or 1 Provide a link only if the content resource has a persistent identifier that is distinct from the persistent identifier of the scholarly object as a whole. In this case, provide a link that has the content resource as origin and the persistent identifier of the content resource (e.g. handle expressed as an HTTP URI) as target. Do not provide a link that expresses the persistent identifier of the scholarly object as a whole.
collection 1 Provide a link that has the content resource as origin and the landing page as target.
describedby 0 or more Provide links only if the content resource is described by metadata that is distinct from the metadata that describes the scholarly object as a whole. In this case, provide one or more links that has the content resource as origin and the URI of metadata that describes the content resource in a commonly used format as target. On each link, provide the media type of the metadata in the type attribute. For common media types see the description of describedby in Level 1.
license 0 or 1 Provide a link only if the content resource is made available under a license that is distinct from the license that applies to the scholarly object as a whole. In this case, provide a link that has as target the URI of that license. Valid licenses include the ones listed at SPDX, in which case the use of an SPDX license identifier (e.g. https://spdx.org/licenses/CC0-1.0, not https://spdx.org/licenses/CC0-1.0.html) is encouraged. But licenses may also include other means of expressing permissions to use the object such as terms of service. Do not provide a link that expresses the license of the scholarly object as a whole.
type 0 or 1 Provide a link only if the type of the content resource differs from the type that best characterizes the scholarly object as a whole. In this case, provide a link that has as target the schema.org term (HTTP URI) for a Creative Work that best characterizes the content resource. If no appropriate term is available in https://schema.org/, select one (HTTP URI) from a commonly used ontology. For example, if the scholarly object as a whole is best characterized as a scholarly paper (https://schema.org/ScholarlyArticle type is provided at the landing page) and the content resource is a dataset provide a link that has https://schema.org/Dataset as target.
2.2.3. Level 2 - Typed Links Pertaining to Metadata Resources
The below image and table show the links that must be conveyed in a Link Set for each metadata resource when implementing Level 2 of this recipe. Examples are provided in Section 3.2.
Link Set, Metadata Resource links
Link Relation Type Link Cardinality Comment
describes 1 For each metadata resource, provide a link that has the metadata resource as origin and the landing page as target.

3. Examples

This section shows examples for providing typed links and Link Sets for Level 1 and Level 2 of the FAIR Signposting Profile. Throughout the examples, the fictitious scholarly object as shown in the below table is used.

Scholarly Object Resources HTTP URI Media Type
Persistent Identifier https://doi.org/10.1234/56789
Landing Page https://example.org/page/7507 text/html
Content Resource 1 - Article https://example.org/file/7507/1 application/pdf
Content Resource 2 - Dataset https://example.org/file/7507/2 text/csv
Content Resource 3 - ZIPped Software Repository https://gitmodo.io/johnd/ct.zip application/zip
Metadata Description 1 https://example.org/meta/7507/bibtex application/x-bibtex
Metadata Description 2 https://example.org/meta/7507/datacite application/vnd.datacite.datacite+json
Metadata Description 3 https://example.org/meta/7507/citeproc application/vnd.citationstyles.csl+json
Author 1 Persistent Identifier https://orcid.org/0000-0002-1825-0097
Author 2 Persistent Identifier https://isni.org/isni/0000002251201436
Other resources involved in signposting the fictitious scholarly object are shown in the table below.

Other Signposting Resources HTTP URI Media Type
Type of Landing Page https://schema.org/AboutPage
Type of Content Resource 1 - Article https://schema.org/ScholarlyArticle
Type of Content Resource 2 - Dataset https://schema.org/Dataset
Type of Content Resource 3 - ZIPped Software Repository https://schema.org/SoftwareSourceCode
License for scholarly object https://spdx.org/licenses/CC-BY-4.0
Link Set https://example.org/linkset/7507/json application/linkset+json
Link Set https://example.org/linkset/7507/lset application/linkset

3.1. Examples Level 1

At Level 1, a minimal set of typed links pertaining to the landing page must be provided. This can be done in the page's HTTP Link header and/or in <link> elements in the <head> section of that page's HTML. Remember that typed links in the HTTP Link header are accessible via both HTTP HEAD and GET, while links in the HTML are only accessible via HTTP GET. Each content resource should also provide a minimal set of links pertaining to itself. This should be done via the resource's HTTP Link header.

When using the Link header approach, the required typed links can be conveyed in a single the HTTP Link header or using multiple Link headers, one header per link. Line breaks must not be used in Link headers as they are not allowed per RFC7230; only whitespaces and tabs are supported as separators.

The below examples show responses to an HTTP GET request issued against the URI of the landing page of our fictitious scholarly object. In the first example, the HTTP header approach is used to convey the typed links, with all links provided in a single Link header. Note that the same links could simultaneously be provided via <link> elements in the HTML's <head>. In the second example, the typed links are provided in the HTML's <head> but not in the HTTP Link header.

Level 1 typed links pertaining to the landing page via the HTTP Link header
$ curl -i "https://example.org/page/7507"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:19:22 GMT
Content-Type: text/html
Content-Length: 25414
Link: <https://doi.org/10.5061/dryad.5d23f> ; rel="cite-as" , <https://schema.org/ScholarlyArticle> ; rel="type" , 
 <https://schema.org/AboutPage> ; rel="type" , <https://orcid.org/0000-0002-1825-0097> ; rel="author" , 
 <https://example.org/meta/7507/bibtex> ; rel="describedby" ; type="application/x-bibtex" , 
 <https://doi.org/10.5061/dryad.5d23f> ; rel="describedby" ; type="application/vnd.datacite.datacite+json" , 
 <https://spdx.org/licenses/CC-BY-4.0> ; rel="license" ,
 <https://example.org/file/7507/1> ; rel="item" ; type="application/pdf" , 
 <https://example.org/file/7507/2> ; rel="item" ; type="text/csv" , 
 <https://gitmodo.io/johnd/ct.zip> ; rel="item" ; type="application/zip"

<html lang="en">
 <head>
  <meta charset="utf-8">
  ...
Level 1 typed links pertaining to the landing page via HTML <link> elements
$ curl -i "https://example.org/page/7507"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:19:48 GMT
Content-Type: text/html
Content-Length: 25414

<html lang="en">
 <head>
  <meta charset="utf-8">
  <link rel="cite-as" href="https://doi.org/10.5061/dryad.5d23">
  <link rel="type" href="https://schema.org/ScholarlyArticle">
  <link rel="type" href="https://schema.org/AboutPage">
  <link rel="author" href="https://orcid.org/0000-0002-1825-0097">
  <link rel="describedby" type="application/x-bibtex" href="https://example.org/meta/7507/bibtex" >  
  <link rel="describedby" type="application/vnd.datacite.datacite+json" href="https://doi.org/10.5061/dryad.5d23f">
  <link rel="license" href="https://spdx.org/licenses/CC-BY-4.0">
  <link rel="item" type="application/pdf" href="https://example.org/file/7507/1">
  <link rel="item" type="text/csv" href="https://example.org/file/7507/2">
  <link rel="item" type="application/zip" href="https://gitmodo.io/johnd/ct.zip">
  ...
The below examples show responses to an HTTP HEAD request issued against the URI of a content resource (respectively, "Content Resource 1 - Article" and "Content Resource 2 - Dataset") of our fictitious scholarly object. Typed links are provided in the resource's HTTP header because that approach can uniformly be used for resources of any media type. Note that Content Resource 1 does not provide a type link because its type coincides with that of the scholarly object as a whole and that type is expressed at the level of the landing page. Content Resource 2, however, has a different type and expresses it by means of a type link.

Level 1 typed links pertaining to the Article content resource via the HTTP Link header
$ curl -I "https://example.org/file/7507/1"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:21:29 GMT
Content-Type: application/pdf
Content-Length: 36588
Link: <https://example.org/page/7507> ; rel="collection" ; type="text/html"
Level 1 typed links pertaining to the Dataset content resource via the HTTP Link header
$ curl -I "https://example.org/file/7507/2"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 20:03:49 GMT
Content-Type: text/csv
Content-Length: 4285
Link: <https://example.org/page/7507> ; rel="collection" ; type="text/html" , 
 <https://schema.org/Dataset> ; rel="type"
The below example shows the response to an HTTP HEAD request issued against the URI of a metadata resource of our fictitious scholarly object. The typed link is provided in the resource's HTTP header because that approach can uniformly be used for resources of any media type.

Level 1 typed links pertaining to a metadata resource via the HTTP Link header
$ curl -I "https://example.org/meta/7507/bibtex"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:24:33 GMT
Content-Type: application/x-bibtex
Content-Length: 120
Link: <https://example.org/page/7507> ; rel="describes" ; type="text/html"

3.2. Examples Level 2

At Level 2, a single Link Set contains a comprehensive set of links pertaining to the landing page, all content resources, and all metadata resources. This Link Set is made available through the provision of linkset links by both the landing page and each of the content/metadata resources.

For the landing page, this can be done using the HTTP Link header and/or via <link> element's in the HTML's <head>. The below examples illustrate both approaches. Each shows the inclusion of two linkset links pointing to different serializations of the Link Set. Note that the responses also contain the Level 1 links pertaining to the landing page.

Link Sets made discoverable by the landing page using the HTTP Link header
$ curl -i "https://example.org/page/7507"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:19:22 GMT
Content-Type: text/html
Content-Length: 25414
Link: <https://doi.org/10.5061/dryad.5d23f> ; rel="cite-as" , <https://schema.org/ScholarlyArticle> ; rel="type" , 
 <https://schema.org/AboutPage> ; rel="type" , <https://orcid.org/0000-0002-1825-0097> ; rel="author" , 
 <https://example.org/meta/7507/bibtex> ; rel="describedby" ; type="application/x-bibtex" , 
 <https://doi.org/10.5061/dryad.5d23f> ; rel="describedby" ; type="application/vnd.datacite.datacite+json" , 
 <https://spdx.org/licenses/CC-BY-4.0> ; rel="license" ,
 <https://example.org/file/7507/1> ; rel="item" ; type="application/pdf" , 
 <https://example.org/file/7507/2> ; rel="item" ; type="text/csv" , 
 <https://gitmodo.io/johnd/ct.zip> ; rel="item" ; type="application/zip" , 
 <https://example.org/linkset/7507/lset> ; rel="linkset" ; type="application/linkset" , 
 <https://example.org/linkset/7507/json> ; rel="linkset" ; type="application/linkset+json"

<html lang="en">
 <head>
  <meta charset="utf-8">
  ...

Link Sets made discoverable by the landing page using HTML link elments
$ curl -i "https://example.org/page/7507"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 19:19:22 GMT
Content-Type: text/html
Content-Length: 25785

<html lang="en">
 <head>
  <meta charset="utf-8">
  <link rel="cite-as" href="https://doi.org/10.5061/dryad.5d23">
  <link rel="type" href="https://schema.org/ScholarlyArticle">
  <link rel="type" href="https://schema.org/AboutPage">
  <link rel="author" href="https://orcid.org/0000-0002-1825-0097">
  <link rel="describedby" type="application/x-bibtex" href="https://example.org/meta/7507/bibtex" >  
  <link rel="describedby" type="application/vnd.datacite.datacite+json" href="https://doi.org/10.5061/dryad.5d23f">
  <link rel="license" href="https://spdx.org/licenses/CC-BY-4.0">
  <link rel="linkset" type="application/linkset" href="https://example.org/linkset/7507/lset">
  <link rel="linkset" type="application/linkset+json" href="https://example.org/linkset/7507/json">
  ...
Each content and metadata resource should also make the Link Set discoverable by means of a linkset link. The only way to do so uniformly for resources of any media type is by using the HTTP Link header approach. The below example illustrates this for Content Resource 1 (Article) of our fictitious scholarly object. It shows the response to an HTTP HEAD issued against that resource's URI. Note that the response also contains the Level 1 links pertaining to the content resource.

Content resource provides linkset links
$ curl -I "https://example.org/file/7507/1"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 20:14:29 GMT
Content-Type: application/pdf
Content-Length: 36588
Link: <https://example.org/linkset/7507/1/lset> ; rel="linkset" ; type="application/linkset" , 
 <https://example.org/linkset/7507/1/json> ; rel="linkset" ; type="application/linkset+json" ,
 <https://example.org/page/7507> ; rel="collection" ; type="text/html"
An actual Link Set is obtained by issuing an HTTP GET on a URI discovered as described above. The below examples show responses to requests issued against https://example.org/linkset/7507/json (application/linkset+json serialization) and https://example.org/linkset/7507/lset (application/linkset serialization), respectively. Note that it is possible to allow clients to interpret this JSON as JSON-LD by: This is shown in detail in Appendix B of the Linkset Internet Draft.

As indicated in Section 2.2.2., if a content resource has distinct a persistent identifier, type, authorship, or descriptive metadata it can be provided in the Link Set using cite-as, type, author, and describedby links, respectively, with the URI of the content resource as anchor. But such links must not be used if these properties are shared with the scholarly object as a whole. Note the way the anchor of each link is provided explicitly in the application/linkset serialization to avoid ambiguous interpretation.

Level 2 typed links via a Link Set in application/linkset+json serialization
$ curl -i "https://example.org/linkset/7507/1/json"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 20:23:44 GMT
Server: Apache-Coyote/1.1
Content-Length: 2608
Content-Type: application/linkset+json
Connection: close

{
  "linkset": [
    {
      "anchor": "https://example.org/page/7507",
      "cite-as": [
        {
          "href": "https://doi.org/10.5061/dryad.5d23f"
        }
      ],
      "type": [
        {
          "href": "https://schema.org/ScholarlyArticle"
        },
        {
          "href": "https://schema.org/AboutPage"
        }
      ],
      "author": [
        {
          "href": "https://orcid.org/0000-0002-1825-0097"
        },
        {
          "href": "https://isni.org/isni/0000002251201436"
        }
      ],
      "item": [
        {
          "href": "https://example.org/file/7507/1",
          "type": "application/pdf"
        },
        {
          "href": "https://example.org/file/7507/2",
          "type": "text/csv"
        },
        {
          "href": "https://gitmodo.io/johnd/ct.zip",
          "type": "application/zip"
        }
      ],
      "describedby": [
        {
          "href": "https://example.org/meta/7507/bibtex",
          "type": "application/x-bibtex"
        },
        {
          "href": "https://doi.org/10.5061/dryad.5d23f",
          "type": "application/vnd.datacite.datacite+json"
        },
        {
          "href": "https://example.org/meta/7507/citeproc",
          "type": "application/vnd.citationstyles.csl+json"
        }
      ],
      "license": [
        {
          "href": "https://spdx.org/licenses/CC-BY-4.0"
        }
      ]
    },
    {
      "anchor": "https://example.org/file/7507/1",
      "collection": [
        {
          "href": "https://example.org/page/7507",
          "type": "text/html"
        }
      ]
    },
    {
      "anchor": "https://example.org/file/7507/2",
      "collection": [
        {
          "href": "https://example.org/page/7507",
          "type": "text/html"
        }
      ],
      "type": [
        {
          "href": "https://schema.org/Dataset"
        }
      ]
    },
    {
      "anchor": "https://gitmodo.io/johnd/ct.zip",
      "collection": [
        {
          "href": "https://example.org/page/7507",
          "type": "text/html"
        }
      ],
      "type": [
        {
          "href": "https://schema.org/SoftwareSourceCode"
        }
      ]
    },
    {
      "anchor": "https://doi.org/10.5061/dryad.5d23f",
      "describes": [
        {
          "href": "https://example.org/page/7507",
          "type": "text/html"
        }
      ]
    },
    {
      "anchor": "https://example.org/meta/7507/bibtex",
      "describes": [
        {
          "href": "https://example.org/page/7507",
          "type": "text/html"
        }
      ]
    }
  ]
}
Level 2 typed links via a Link Set in application/linkset serialization
$ curl -i "https://example.org/linkset/7507/lset"

HTTP/1.1 200 OK
Date: Fri, 9 Oct 2020 20:22:19 GMT
Server: Apache-Coyote/1.1
Content-Length: 2247
Content-Type: application/linkset
Connection: close

<https://doi.org/10.5061/dryad.5d23f> ; rel="cite-as" ; anchor="https://example.org/page/7507" , 
<https://schema.org/ScholarlyArticle> ; rel="type" ; anchor="https://example.org/page/7507" , 
<https://schema.org/AboutPage> ; rel="type" ; anchor="https://example.org/page/7507" , 
<https://orcid.org/0000-0002-1825-0097> ; rel="author" ; anchor="https://example.org/page/7507" , 
<https://isni.org/isni/0000002251201436> ; rel="author" ; anchor="https://example.org/page/7507" ,
<https://example.org/file/7507/1> ; rel="item" ; type="application/pdf" ; anchor="https://example.org/page/7507" , 
<https://example.org/file/7507/2> ; rel="item" ; type="text/csv" ; anchor="https://example.org/page/7507" , 
<https://gitmodo.io/johnd/ct.zip> ; rel="item" ; type="application/zip" ; anchor="https://example.org/page/7507" ,
<https://example.org/meta/7507/bibtex> ; rel="describedby" ; type="application/x-bibtex" 
; anchor="https://example.org/page/7507" , <https://doi.org/10.5061/dryad.5d23f> ; rel="describedby" ; 
type="application/vnd.datacite.datacite+json" ; anchor="https://example.org/page/7507" , 
<https://example.org/meta/7507/citeproc> ; rel="describedby" ; type="application/vnd.citationstyles.csl+json" ; 
anchor="https://example.org/page/7507" , <https://spdx.org/licenses/CC-BY-4.0> ; rel="license" ; 
anchor="https://example.org/page/7507" , <https://example.org/page/7507> ; rel="collection" ; type="text/html" ; 
anchor="https://example.org/file/7507/1" , <https://example.org/page/7507> ; rel="collection" ; 
type="text/html" ; anchor="https://example.org/file/7507/2" , <https://schema.org/Dataset> ; rel="type" ; 
anchor="https://example.org/file/7507/2" , <https://example.org/page/7507> ; rel="collection" ; type="text/html" ; 
anchor="https://gitmodo.io/johnd/ct.zip" , <https://schema.org/SoftwareSourceCode> ; rel="type" ; 
anchor="https://gitmodo.io/johnd/ct.zip" <https://example.org/page/7507> ; rel="describes" ; type="text/html" ; 
anchor="https://doi.org/10.5061/dryad.5d23f" , <https://example.org/page/7507> ; rel="describes" ; type="text/html" ; 
anchor="https://example.org/meta/7507/bibtex"