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

• 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.

• 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.

• 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 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.

• 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.

• 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. It could also be used to link to a document that explains the terms and conditions for use of an interoperability affordance.

• 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/.

• 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 is an OpenAPI document. The API description is expressed using the OpenAPI specification <https://spec.openapis.org/oas/v3.1.0>, which is provided in a first link with the service-doc link relation type. A second link with that same link relation type points at the human-readable description of the actual API.

• 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.

3.4. FAIRiCat Examples for Selected Interoperability Affordances

{
  "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"
        }
      ]
    }
  ]
}

{
  "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"
        }
      ]
    }
  ]
}

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