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 20240627: https://signposting.org/FAIRiCat/
Previous version, created 20240227
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.
Signposting the Scholarly Web: FAIRiCat

Image courtesy of Patrick Hochstenbach.



"It is funny that there hasn't been a clear way of representing this information in the repository space. Anecdotally, last year when I was bringing a grad student onboard one of my projects, the challenges we had in finding if, and where, a repository provided access to OAI-PMH was much harder than it should have been." - Mark Phillips of the University of Northern Texas Digital Library.

Make it so!

Table of Contents

  1. Introduction
  2. Building Blocks
    1. The FAIRiCat Link Set
    2. Link Relation Types to Point at Machine Interface Descriptions
    3. Discovery of the FAIRiCat Link Set
  3. Examples
    1. Discovery
    2. FAIRiCat Link Set
      1. Repository-Level Affordances
      2. Object-Level Affordances
    3. FAIRiCat Entries for Selected Interoperability Affordances
    4. FAIRiCats for Selected Interoperability Affordances

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:

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:
Interoperability affordances that can be advertised using the approach can be:
The approach leverages the following formal specifications:

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:

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:

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:

FAIRiCat discovery via well-known URI

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:

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://spec.openapis.org/oas/v3.1.0",
          "type": "text/html",
          "title": "OpenAPI Specification v3.1.0"
        },
        {
          "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:
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 v.3.1 API
Affordance type repository-level
svc-desc URL of JSON or YAML OpenAPI description of the API
svc-doc https://spec.openapis.org/oas/v3.1.0
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 Signmap
Affordance type repository-level
svc-desc not used
svc-doc https://signposting.org/Signmap/
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://spec.openapis.org/oas/v3.1.0",
          "type": "text/html",
          "title": "OpenAPI Specification v3.1.0"
        },
        {
          "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"
        }
      ]
    }
  ]
}
Signmap, Open Archieven
{
  "linkset": [
    {
      "anchor": "https://www.openarchieven.nl/foundlinks-signmap.xml",
      "service-doc": [
        {
          "href": "https://signposting.org/Signmap/",
          "type": "text/html",
          "title": "Signmap - Signposting the Scholarly Web"
        }
      ]
    }
  ]
}
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"
        }
      ]
    }
  ]
}