FAIRiCat - Signposting the Scholarly Web

FAIRiCat: Supporting Discovery of a Repository's Interoperability Affordances

Prepared by: Herbert Van de Sompel, Robert Huber, Patrick Hochstenbach, Michael L. Nelson, Martin Klein, Andrea Bollini, Enno Meijers, Petr Knoth, Paul Walk, Wim Hugo, Jim Meyers, ...

This version, created 20240227: https://signposting.org/FAIRiCat/

Previous version, created 20240212

Version history

Versions prior to name change from API Catalog to FAIRiCat

Please provide feedback in the GitHub Signposting repository, using label FAIRiCat

In order to meet FAIR expectations, repositories provide affordances to support Finding, Accessing, Interoperating, and Reusing the scholarly objects they manage. Some affordances focus on supporting machine interaction with scholarly content and entail implementing common specifications as well as repository-specific machine interfaces. Discovering whether and which interoperability affordances are provided by a repository remains a challenge. Some specifications describe how to advertise a compliant interface, but, the discovery approach is different for different specifications. Other specifications don't detail an approach to discover a compliant interface and rely on a central registry instead. For yet other specifications, no way to advertise compliance exists. This document describes the FAIR Interoperability Catalogue - FAIRiCat - approach that repositories can uniformly use to advertise the interoperability affordances they provide. FAIRiCats can be used manually as a way to obtain a quick overview of the interoperability characteristics of a repository. They can be used in automatic processes by clients that are looking for specific approaches to interoperate with a repository, e.g. via OAI-PMH, SPARQL, Sitemaps, Linked Data Notifications.

Image courtesy of Patrick Hochstenbach.

Introduction
Building Blocks
Examples

1. Introduction

This specification details the FAIR Interoperability Catalog - FAIRiCat in short - approach that repositories that manage scholarly objects can use to advertise the interoperability affordances they provide. A repository can use the FAIRiCat approach, for example, to:

indicate what the URL of its OAI-PMH interface is,
point to a Sitemap that lists the objects managed by the repository,
convey the URL of a repository-specific API,
advertise support for FAIR Signposting,
convey that objects managed by the repository can be downloaded as RO-Crates.

A very simple FAIRiCat that only advertises a SPARQL endpoint. The URL of the endpoint is provided as the value of anchor. service-doc indicates that a human-readable document specifies the nature of the endpoint and href provides the URL of that document, i.e. the SPARQL 1.1 specification.

{
  "linkset": [
    {
      "anchor": "https://triplestore.netwerkdigitaalerfgoed.nl/sparql",
      "service-doc": [
        {
          "href": "https://www.w3.org/TR/sparql11-query/",
          "type": "text/html",
          "title": "SPARQL 1.1 Query Language"
        }
      ]
    }
  ]
}

The approach consists of:

Publishing a single FAIRiCat, which is a JSON Link Set that contains links to documentation for each available affordance. The FAIRiCat has static content for as long as a repository’s interoperability affordances don’t change.
Making the FAIRiCat discoverable using established approaches: a dedicated well-known URI and typed link.

Interoperability affordances that can be advertised using the approach can be:

Repository-level affordances: Machine interfaces that can be used to interact with the repository as a whole, e.g. the aforementioned OAI-PMH interface.
Object-level affordances: Affordances that are available when interacting with a single scholarly object managed by the repository, e.g. the aforementioned support for FAIR Signposting.

The approach leverages the following formal specifications:

The api-catalog Internet Draft - This specification defines the api-catalog well-known URI and link relation type that can be used to point at a machine-readable document that provides an overview of the machine interfaces for a repository. The draft has been adopted by the IETF HTTP API Working Group and will eventually be published as an RFC.
RFC9264: Linkset: Media Types and a Link Relation Type for Link Sets - This RFC defines the application/linkset+json document format that can be used to convey a set of typed links. The API Catalog Internet Draft recommends using Link Sets to advertise API endpoints.
RFC8631: Link Relation Types for Web Services - This RFC defines the service-doc, service-desc, and service-meta link relation types that can be used to, respectively, link to a human-readable description of a machine interface, a machine-readable description of a machine interface, and additional information pertaining a the machine interface.

2. Building Blocks

This section provides a description of the building blocks of the FAIRiCat approach that can be used to provide details about the interoperability affordances that are supported by a repository.

2.1. The FAIRiCat Link Set

The FAIRiCat is a Link Set that is serialized in the application/linkset+json format. The content of the Link Set is as follows:

For each interoperability affordance provided by a repository, the Link Set contains a link context object with a mandatory anchor member. The URL provided as value of the anchor member depends on the nature of the affordance:

Repository-level affordance: The value of the anchor member is the URL of the machine interface. If more than one affordance of the same type exist, a distinct anchor member must be used for each.
Object-level affordances: The value of the anchor member is the URL of the constituent resource of a single example object managed by the repository that illustrates the affordance. If more than one object-level affordance exists, each should be illustrated by means of a different example object.

The anchor member is the context for links to resources that provide information about the interoperability affordance. Links with the service-doc, service-desc, and service-meta link relation types can be provided; the semantics of these relation types are described in Section 2.2. Links with other link relation types must not be provided.
For each link, the type link target attribute must be used to convey the media type of the resource that is the target of the link. The profile attribute may be used to provide further specificity regarding the media type, and, if used, must contain a profile URI. The title attribute may be used to improve human readability of the Link Set, and, if used, must contain the title of the resource that is the target of the link.
All URLs in the Link Set must be absolute URIs; relative URIs must not be used.

2.2. Link Relation Types to Point at Descriptions of Interoperability Affordances

RFC8631 defines the following link relation types that are used in a FAIRiCat Link Set to point at various descriptions of a specific interoperability affordance that is provided by a repository:

service-doc: This link relation type is used to point at a human-readable specification of an interoperability affordance. It can, for example, be used to point at the URI of a specification or standard, e.g. the OAI-PMH specification, the SPARQL 1.1 W3C Recommendation, the FAIR Signposting specification.
service-desc: This link relation type is used to point at a machine-readable specification of the interoperability affordance. It can, for example, be used to point at the URI of an OpenAPI or RESTdesc specification of an API exposed by the repository.
service-meta: This link relation type is used to point at further details regarding the interoperability affordance. It can, for example, be used to point at the Identify endpoint of an OAI-PMH interface or a SPARQL 1.1 Service Description document.

2.3. Discovery of the FAIRiCat Link Set

A repository's FAIRiCat Link Set can be made discoverable using two approaches. Both leverage its repository-entry-URL. What the repository-entry-URL is depends on how/where the repository was installed. For example, it could be <https://myuniversity.edu/repository/home>, or <https://repository.myuniversity.edu/home>, or <https://repo.org/>. Generally speaking it is the de-facto entry page to a repository.

The following discovery approaches may be provided simultaneously and one must be supported:

Discovery via the /.well-known/api-catalog URI provided at the repository-entry-URL of a repository, i.e. at <repository-entry-URL/.well-known/api-catalog>:
- An HTTP GET request against <repository-entry-URL/.well-known/api-catalog> must resolve to the repository's FAIRiCat Link Set serialized in the application/linkset+json format.
- An HTTP HEAD request against <repository-entry-URL/.well-known/api-catalog> should have an HTTP response header with a link that points at the repository's FAIRiCat Link Set. The properties of this link are as described below for the api-catalog discovery approach.
Discovery via an api-catalog link provided at the repository-entry-URL: An HTTP HEAD/GET request against <repository-entry-URL/>, must have an HTTP response header with a link that points at the repository's FAIRiCat Link Set. This link:
- Must be provided in the HTTP Link header.
- Must have the api-catalog link relation type.
- Must have a type attribute with value application/linkset+json.
- Must have a profile attribute with value https://signposting.org/FAIRiCat/.

3. Examples

3.1. Discovery

The below example illustrates how an agent can discover a repository's FAIRiCat using the api-catalog link provided at the repository-entry-URL. It shows the response to an HTTP HEAD request issued against the repository-entry-URL <https://my.repo.org/home/>. The response contains an HTTP Link header that has a link with the api-catalog link relation type and the mandatory type and profile attributes as described in Section 2.3. The link's target <https://my.repo.org/fairicat/api-info.json> is the URL of the repository's FAIRiCat Link Set. The client can proceed by issuing an HTTP GET against that URI to obtain the FAIRiCat. Note that, if this repository also implements the /.well-known/api-catalog discovery approach, an HTTP GET against <https://my.repo.org/home/.well-known/api-catalog> must lead to the FAIRiCat at <https://my.repo.org/fairicat/api-info.json>.

HTTP HEAD against a repository-entry-URL: request and response

$ curl -I "https://my.repo.org/home/"

HTTP/1.1 200 OK
Date: Sat, 18 Nov 2023 14:43:06 GMT
Link: <https://my.repo.org/fairicat/api-info.json> 
      ; rel="api-catalog" 
      ; type="application/linkset+json" 
      ; profile="https://signposting.org/FAIRiCat/" 
   Content-Length: 0
   Connection: close

3.2. FAIRiCat Link Set

This section illustrates FAIRiCats that have repository-level and object-level entries, respectively. In actual FAIRiCats, these entries can be combined. But, here, they are shown separately for increased clarity.

3.2.1. Repository-Level Affordances

The below example shows an FAIRiCat listing only repository-level interoperability affordances. For such affordances, the value of the anchor member is the URL where the affordance is accessible:

The affordance at <https://my.repo.org/oaipmh> is detailed in a human-readable manner (service-doc link relation type) by the document at <https://www.openarchives.org/OAI/openarchivesprotocol.html>, which is the OAI-PMH specification. Further information about the repository's OAI-PMH implementation is provided by means of a link with the service-meta link relation type that points at the URL for the Identify request against the OAI-PMH interface.
The affordance at <https://my.repo.org/sitemap/index.xml> is detailed in a human-readable manner (service-doc link relation type) by the document at <https://www.sitemaps.org/protocol.html>, which is the Sitemap protocol specification. No further information is provided for this affordance.
The affordance at <https://my.repo.org/sparql11> is detailed in a human-readable manner (service-doc link relation type) by the document at <https://www.w3.org/TR/sparql11-query/>, which is the SPARQL 1.1 W3C Recommendation. Further information about the repository's SPARQL end-point is provided by means of a link with the service-meta link relation type that points at the URL of a SPARQL Description document.
The affordance at <https://my.repo.org/api> is detailed in a machine-readable manner (service-desc link relation type) by the JSON document at <https://my.repo.org/api/api-specification.json>, which could be an OpenAPI document. It is also detailed in a human-readable manner (service-doc link relation type) by the document at <https://my.repo.org/api/api-specification.html>.

A FAIRiCat listing only repository-level affordances

{
  "linkset": [
    {
      "anchor": "https://my.repo.org/oaipmh",
      "service-doc": [
        {
          "href": "https://www.openarchives.org/OAI/openarchivesprotocol.html",
          "type": "text/html",
          "title": "Open Archives Initiative - Protocol for Metadata Harvesting - v.2.0"
        }
      ],
      "service-meta": [
        {
          "href": "https://my.repo.org/oaipmh?verb=Identify",
          "type": "application/xml"
        }
      ]
    },
    {
      "anchor": "https://my.repo.org/sitemap/index.xml",
      "service-doc": [
        {
          "href": "https://www.sitemaps.org/protocol.html",
          "type": "text/html",
          "title": "sitemaps.org - Protocol"
        }
      ]
    },
    {
      "anchor": "https://triplestore.netwerkdigitaalerfgoed.nl/sparql",
      "service-doc": [
        {
          "href": "https://www.w3.org/TR/sparql11-query/",
          "type": "text/html",
          "title": "SPARQL 1.1 Query Language"
        }
      ],
      "service-meta": [
        {
          "href": "https://my.repo.org/sparql11/description.xml",
          "type": "application/rdf+xml"
        }
      ]
    },
    {
      "anchor": "https://my.repo.org/api",
      "service-desc": [
        {
          "href": "https://my.repo.org/api/openapi.yml",
          "type": "application/yaml"
        }
      ],
      "service-doc": [
        {
          "href": "https://my.repo.org/api/api-specification.html",
          "type": "text/html",
          "title": "My Repo API"
        }
      ]
    }
  ]
}

3.2.2. Object-Level Affordances

The below example shows a FAIRiCat listing only object-level interoperability affordances. For such affordances, the value of the anchor member is the URL of the constituent resource of a single example object managed by the repository that illustrates the affordance. When multiple object-level interoperability affordances are listed in a FAIRiCat, each should be illustrated by means of a different example object:

To illustrate the first object-level affordance, FAIR Signposting, the landing page URL <https://my.repo.org/item/747369/> of an example object managed by the repository is used as value of the anchor member, because Signposting links are consistently provided at landing pages. The FAIR Signposting affordance is detailed in a human-readable manner (service-desc link relation type) by the document <https://signposting.org/FAIR/>.
To illustrate the second object-level affordance, RO-Crate, the URL <https://my.repo.org/item/747369/crate/> of an actual RO-Crate rendering of an example object managed by the repository is used as value of the anchor member. The RO-Crate affordance is detailed in a human-readable manner (service-desc link relation type) by the document <https://w3id.org/ro/crate/1.1>, which is the RO-Crate 1.1 specification.

A FAIRiCat listing only object-level affordances

{
  "linkset": [
        {
      "anchor": "https://my.repo.org/item/747369/",
      "service-doc": [
        {
          "href": "https://signposting.org/FAIR/",
          "type": "text/html",
          "title": "FAIR Signposting Profile - Signposting the Scholarly Web"
        }
      ]
    },
    {
      "anchor": "https://my.repo.org/item/008375/crate/",
      "service-doc": [
        {
          "href": "https://w3id.org/ro/crate/1.1",
          "type": "text/html",
          "title": "RO-Crate 1.1 | Research Object Crate (RO-Crate)"
        }
      ]
    }
  ]
}

3.3. FAIRiCat Entries for Selected Interoperability Affordances

This section provides an overview of the entries to use in a FAIRiCat Link Set for a range of interoperability affordances. Where possible, examples of Link Sets describing operational affordances are also provided.

Affordance	FAIR Signposting
Affordance type	object-level
svc-desc	not used
svc-doc	https://signposting.org/FAIR/
service-meta	not used
Example entry	Pangea

Affordance	IIIF Presentation API 3.0
Affordance type	object-level
svc-desc	not used
svc-doc	https://iiif.io/api/presentation/3.0/
service-meta	not used
Example entry	BnF

Affordance	Linked Data Notifications Inbox
Affordance type	repository-level
svc-desc	not used
svc-doc	https://www.w3.org/TR/ldn/
service-meta	not used
Example entry	Fictitious

Affordance	Memento
Affordance type	object-level
svc-desc	not used
svc-doc	https://datatracker.ietf.org/doc/rfc7089/
service-meta	not used
Example entry	Fictitious example

Affordance	OAI-ORE, RDF/XML
Affordance type	object-level
svc-desc	not used
svc-doc	https://www.openarchives.org/ore/1.0/rdfxml
service-meta	not used
Example entry	DANS SSH Data Station

Affordance	OAI-PMH
Affordance type	repository-level
svc-desc	not used
svc-doc	https://www.openarchives.org/OAI/openarchivesprotocol.html
service-meta	URL of Identify protocol request
Example entry	arXiv.org

Affordance	OpenAPI API
Affordance type	repository-level
svc-desc	URL of JSON or YAML OpenAPI description of the API
svc-doc	URL of HTML pages describing the API
service-meta	not used
Example entry	EMBL-EBI

Affordance	OpenSearch 1.1
Affordance type	repository-level
svc-desc	URL of the OpenSearch Description Document
svc-doc	https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md
service-meta	not used
Example entry	Open Archieven

Affordance	Robots Exclusion Protocol aka robots.txt
Affordance type	repository-level
svc-desc	not used
svc-doc	https://datatracker.ietf.org/doc/rfc9309/
service-meta	not used
Example entry	arXiv.org

Affordance	RO-Crate 1.1
Affordance type	object-level
svc-desc	not used
svc-doc	https://w3id.org/ro/crate/1.1
service-meta	not used
Example entry	ROhub

Affordance	RSS 2.0
Affordance type	repository-level
svc-desc	not used
svc-doc	https://www.rssboard.org/rss-specification
service-meta	not used
Example entry	Open Archieven

Affordance	Sitemap protocol
Affordance type	repository-level
svc-desc	not used
svc-doc	https://www.sitemaps.org/protocol.html
service-meta	not used
Example entry	DIGITAL.CSIC

Affordance	SPARQL 1.1
Affordance type	repository-level
svc-desc	not used
svc-doc	https://www.w3.org/TR/sparql11-query/
service-meta	URL of SPARQL 1.1 Service Description
Example entry	Uniprot

Affordance	Well-known URI, FAIRiCat
Affordance type	repository-level
svc-desc	not used
svc-doc	https://signposting.org/FAIRiCat/
service-meta	not used
Example entry	Fictitious example

3.4. FAIRiCat Examples for Selected Interoperability Affordances

FAIR Signposting, Pangea

{
  "linkset": [
    {
      "anchor": "https://doi.pangaea.de/10.1594/PANGAEA.867908",
      "service-doc": [
        {
          "href": "https://signposting.org/FAIR/",
          "type": "text/html",
          "title": "FAIR Signposting Profile - Signposting the Scholarly Web"
        }
      ]
    }
  ]
}

IIIF Presentation API, BnF

{
  "linkset": [
    {
      "anchor": "https://gallica.bnf.fr/iiif/ark:/12148/bpt6k10733944/manifest.json",
      "service-doc": [
        {
          "href": "https://iiif.io/api/presentation/3.0/",
          "type": "text/html",
          "title": "Presentation API 3.0 —  IIIF | International Image Interoperability Framework"
        }
      ]
    }
  ]
}

Linked Data Notification Inbox, Fictitious

{
  "linkset": [
    {
      "anchor": "https://my.repo.org/ldn/inbox/",
      "service-doc": [
        {
          "href": "https://www.w3.org/TR/ldn/",
          "type": "text/html",
          "title": "Linked Data Notifications"
        }
      ]
    }
  ]
}

Memento, Fictitious

{
  "linkset": [
    {
      "anchor": "https://my.repo.org/item/747369/",
      "service-doc": [
        {
          "href": "https://datatracker.ietf.org/doc/rfc7089/",
          "type": "text/html",
          "title": "RFC 7089 - HTTP Framework for Time-Based Access to Resource States -- Memento"
        }
      ]
    }
  ]
}

OAI-ORE (RDF/XML serialization), DANS SSH Data Station

{
  "linkset": [
    {
      "anchor": "https://ssh.datastations.nl/api/datasets/export?exporter=OAI_ORE&persistentId=doi%3A10.17026/dans-29r-wyyr",
      "service-doc": [
        {
          "href": "https://www.openarchives.org/ore/1.0/rdfxml",
          "type": "text/html",
          "title": "ORE User Guide - Resource Map Implementation in RDF/XML"
        }
      ]
    }
  ]
}

OAI-PMH, arXiv.org

{
  "linkset": [
    {
      "anchor": "https://export.arxiv.org/oai2",
      "service-doc": [
        {
          "href": "https://www.openarchives.org/OAI/openarchivesprotocol.html",
          "type": "text/html",
          "title": "Open Archives Initiative - Protocol for Metadata Harvesting - v.2.0"
        }
      ],
      "service-meta": [
        {
          "href": "https://export.arxiv.org/oai2?verb=Identify",
          "type": "application/xml"
        }
      ]
    }
  ]
}

OpenAPI, EMBL-EBI

{
  "linkset": [
    {
      "anchor": "https://www.ebi.ac.uk/biomodels/",
      "service-desc": [
        {
          "href": "https://www.ebi.ac.uk/biomodels/docs/biomodels-jummp-swagger.json",
          "type": "application/json",
          "title": "Biomodels"
        }
      ],
      "service-doc": [
        {
          "href": "https://www.ebi.ac.uk/biomodels/docs/",
          "type": "text/html",
          "title": "BioModels REST API documentation"
        }
      ]
    }
  ]
}

OpenSearch 1.1, Open Archieven

{
  "linkset": [
    {
      "anchor": "https://www.openarch.nl/search.php",
      "service-desc": [
        {
          "href": "https://www.openarchieven.nl/opensearch/nl.xml",
          "type": "application/xml"
        }
      ],
      "service-doc": [
        {
          "href": "https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md",
          "type": "text/markdown",
          "title": "OpenSearch 1.1 Draft 6"
        }
      ]
    }
  ]
}

Robots Exclusion Protocol aka robots.txt, arXiv.org

{
  "linkset": [
    {
      "anchor": "https://arxiv.org/robots.txt",
      "service-doc": [
        {
          "href": "https://datatracker.ietf.org/doc/rfc9309/",
          "type": "text/html",
          "title": "RFC 9309 - Robots Exclusion Protocol"
        }
      ]
    }
  ]
}

RO-Crate, ROhub

{
  "linkset": [
    {
      "anchor": "https://api.rohub.org/api/ros/80e2215b-49cb-456e-9ae9-803f3bcdbba3/crate/download/",
      "service-doc": [
        {
          "href": "https://w3id.org/ro/crate/1.1",
          "type": "text/html",
          "title": "RO-Crate 1.1 | Research Object Crate (RO-Crate)"
        }
      ]
    }
  ]
}

RSS 2.0, Open Archieven

{
  "linkset": [
    {
      "anchor": "https://www.openarch.nl/rss/collections.php",
      "service-doc": [
        {
          "href": "https://www.rssboard.org/rss-specification",
          "type": "text/html",
          "title": "RSS 2.0 Specification"
        }
      ]
    }
  ]
}

Sitemap Protocol, DIGITAL.CSIC

{
  "linkset": [
    {
      "anchor": "https://digital.csic.es/sitemap",
      "service-doc": [
        {
          "href": "https://www.sitemaps.org/protocol.html",
          "type": "text/html",
          "title": "sitemaps.org - Protocol"
        }
      ]
    }
  ]
}

SPARQL 1.1, Uniprot

{
  "linkset": [
    {
      "anchor": "https://sparql.uniprot.org/sparql/",
      "service-doc": [
        {
          "href": "https://www.w3.org/TR/sparql11-query/",
          "type": "text/html",
          "title": "SPARQL 1.1 Query Language"
        }
      ]
    }
  ]
}

Well-known URI api-catalog, Fictitious

{
  "linkset": [
    {
      "anchor": "https://my.repo.org/.well.known/api-catalog",
      "service-doc": [
        {
          "href": "https://signposting.org/FAIRiCat/",
          "type": "text/html",
          "title": "FAIRiCat - Signposting the Scholarly Web"
        }
      ],
      "service-doc": [
        {
          "href": "https://datatracker.ietf.org/doc/draft-ietf-httpapi-api-catalog/",
          "type": "text/html",
          "title": "draft-ietf-httpapi-api-catalog-00 - api-catalog: A well-known URI to help discovery of APIs"
        }
      ]
    }
  ]
}