authorIDy - Listing Contributions by Contributor Identifier

authorIDy: Listing Contributions by Contributor Identifier

Warning: Discussion document - Not a specification (yet)

This version, created 20240224: https://signposting.org/authorIDy/

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

Increasingly, repositories allow, recommend, or require providing unique contributor identifiers, such as ORCID or ISNI, when depositing contributions. Despite this evolution, few repositories provide a machine interface that allows listing the contributions made by a researcher using their contributor identifier as a key. An interface with this capability, supported across repositories, would facilitate a range of use cases and could be an important next step towards realizing COAR’s Next Generation Repositories vision. This document describes core characteristics of authorIDy, a conceptual proposal for such a machine interface. Hopefully, this description will evolve into a specification.

Motivation
Design Principles
Protocol Request
Protocol Response
Interface Discovery
Possible authorIDy JSON Response Body
JSON Schema for Possible authorIDy Response Body
OpenAPI Description for Proposed authorIDy Interface

1. Motivation

The following motivate the work on authorIDy:

Traditionally, scholarly communication was artifact-centric, i.e. had the journal (ISSN) and then the paper (DOI) as the center of attention.
In the last decade, a shift towards contributor/researcher-centric scholarly communication has taken place, see e.g. Who Is Competing to Own Researcher Identity? Significant investments have been made in promoting, adopting, implementing contributor identifiers such as ORCID and ISNI.
Yet, repositories have remained largely artifact-centric. Only few repositories offer an API that allows listing contributions by contributor identifier, whereas this is common practice in general purpose web portals.
Extending repository APIs with an affordance to list contributions by contributor identifier might be an approach to address this shortcoming. But a uniform interface supported across repositories lowers the barrier for client implementations.

2. Design Principles

These are proposed design principles for a possible authorIDy interface:

KISS
Support for cross-platform contributor identifiers (e.g. ORCID, ISNI) as well as platform-specific contributor identifiers (e.g. GitHub user tokens, repository-specific unique contributor identifiers).
Adoptable by repositories that already have affordance for listing contributions by contributor identifier.
Slim response payload, assuming additional information can be obtained via URIs provided in the payload (REST/HATEOAS approach).
Request:
- List contributions by a contributor by providing the contributor’s identifier.
- Optional support for incremental listing contributions by providing “since” accession date.
Response:
- Minimal, not a metadata harvesting protocol, not a metadata format.
- Assumes that metadata about contributions (if needed) can be obtained by means of affordances that are provided in the response (e.g. landing page URI, PID-URI)
- Support for filtering on accession date range as alternative for optional incremental request.
- Optional support for filtering on contribution facets: contributor role, contribution type.
- No particular order required when listing contributions (client can sort according to facets of its choosing).
- Paging support? One expects most responses would fit in single response. But, if paging is needed, use "next" and "prev" links.

3. Protocol Request

Requirement	Purpose	Request syntax
mandatory	all contributions	`baseURL-service//contributor-id-uri/`, e.g. <https://mirepo.org/createdby//https://orcid.org/1234-5678-1234-5678>
optional	contributions since	`baseURL-service/yyyymmdd/contributor-id-uri/`, e.g. <https://github.com/byuser/20231107/https://github.com/phonedude/>

4. Protocol Response

4.1. Protocol Response HTTP Header

A request may yield a paged response, in which case each individual response uses the HTTP Link header to link to previous and/or next portions of the response.

HTTP header	Requirement	Value
HTTP status code	mandatory	For successful requests: `200 OK`. For unsupported requests (i.e. no support for the optional "contributions since" request) and malformed requests (e.g. 3-digit date): `400 Bad Request`. For unknown contributor identifiers: `404 Not Found`
`Content-Type`	mandatory	`application/json`
`Link`	mandatory for paged response	links with `rel="prev"` and/or `rel="next"` and `type="application/json"` to point at previous/next contributions

4.2. Protocol Response Body

Each response body is a JSON document consisting of a single header followed by a list of entries, one entry per contribution.

4.2.1. Single Header for an Entire Response Body

Property	Requirement	Cardinality	Data Type	Content
`contributor`	mandatory	[1]	HTTP URI	contributor identifier URI

4.2.2. Content for an Entry in a List of Contributions

Property	Requirement	Cardinality	Data Type	Content
`contribution-page`	mandatory	[1]	HTTP URI	URI of contribution, e.g. landing page URI
`accession-date`	mandatory	[1]	ISO8601 date, Complete date format	repository accession date
`publication-date`	optional	[0,1]	ISO8601 date, Year format	publication date
`cite-as`	optional	[0,1]	HTTP URI	persistent identifier URI (redirects to landing page URI)
`contributor-type`	optional	[0,n]	HTTP URI	contributor type URI from vocabulary, e.g. https://credit.niso.org/
`contribution-type`	optional	[0,n]	HTTP URI	contribution type URI from vocabulary, e.g. https://vocabularies.coar-repositories.org/resource_types/

5. Interface Discovery

The following paths can be be pursued:

Provision of the authorIDy interface endpoint in the repository's FAIRiCat, using the URL of the interface as the anchor:
- for a link that has <https://signposting.org/authorIDy/> as the target and service-doc as the link relation type
- for a link that has as target a schema/template/OpenAPI-spec specifying the nature of the authorIDy implementation and service-desc as the link relation type
Provision of the /.well-known/authoridy URI that resolves to a schema/template/OpenAPI-spec specifying the nature of the authorIDy implementation

6.Possible authorIDy JSON Response Body

Sample authorIDy Response Body with required properties only

{
  "contributor": "https://orcid.org/1234-5678",
  "contributions": [
    {
      "contribution-page": "https://mirepo.org/item/9876",
      "accession-date": "2023-01-04"
    },
    {
      "contribution-page": "https://mirepo.org/item/5432",
      "accession-date": "2022-03-20"
    }
  ]
}

Sample authorIDy Response Body including optional properties

{
  "contributor": "https://orcid.org/1234-5678",
  "contributions": [
    {
      "contribution-page": "https://mirepo.org/item/9876",
      "accession-date": "2023-01-04",
      "publication-date": "2022",
      "cite-as": "https://doi.org/12.9876",
      "contributor-type": [
        "https://credit.niso.org/contributor-roles/writing-original-draft/",
        "https://credit.niso.org/contributor-roles/software/"
      ],
      "contribution-type": [
        "https://vocabularies.coar-repositories.org/resource_types/c_6501/",
        "https://vocabularies.coar-repositories.org/resource_types/c_c950/"
      ]
    },
    {
      "contribution-page": "https://mirepo.org/item/5432",
      "accession-date": "2022-03-20",
      "publication-date": "2021",
      "cite-as": "https://doi.org/84.47562",
      "contributor-type": [
        "https://credit.niso.org/contributor-roles/writing-original-draft/"
      ],
      "contribution-type": [
        "https://vocabularies.coar-repositories.org/resource_types/c_6501/"
      ]
    }
  ]
}

7. JSON Schema for Possible authorIDy Response Body

Sample JSON Schema for authorIDy Response Body

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$id": "https://signposting.org/authorIDy/schema.json",
  "title": "authorIDy",
  "description": "An authorIDy response body",
  "type": "object",
  "properties": {
    "contributor": {
      "description": "contributor identifier URI",
      "type": "string",
      "pattern": "http(s)?://.*"
    },
    "contributions": {
      "description": "list of entries, one entry per contribution",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contribution-page": {
            "description": "URI of contribution, e.g. landing page URI",
            "type": "string",
            "pattern": "http(s)?://.*"
          },
          "accession-date": {
            "description": "repository accession date",
            "type": "string",
            "pattern": "\\d{4}-[01]\\d-[0-3]\\d"
          },
          "publication-date": {
            "description": "publication date",
            "type": "string",
            "pattern": "\\d{4}"
          },
          "cite-as": {
            "description": "persistent identifier URI (redirects to landing page URI)",
            "type": "string",
            "pattern": "http(s)?://.*"
          },
          "contributor-type": {
            "description": "contributor type URI from vocabulary, 
                            e.g. https://credit.niso.org/",
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "http(s)?://.*"
            }
          },
          "contribution-type": {
            "description": "contribution type URI from vocabulary, 
             e.g. https://vocabularies.coar-repositories.org/resource_types/",
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "http(s)?://.*"
            }
          }
        },
        "required": [
          "contribution-page",
          "accession-date"
        ]
      },
      "minItems": 1
    }
  },
  "required": [
    "contributor",
    "contributions"
  ]
}

8. OpenAPI Description for Proposed authorIDy Interface

Sample OpenAPI Description for authorIDy Interface

{
    "openapi": "3.0.3",
    "info": {
        "description": "This is mirepo's authorIDy instance",
        "version": "v1.0",
        "title": "mirepo authorIDy",
        "termsOfService": "https://mirepo.org/terms-of-service/",
        "contact": {
            "email": "admin@mirepo.org"
        },
        "license": {
            "name": "AGPL v3",
            "url": "https://www.gnu.org/licenses/agpl-3.0.en.html"
        }
    },
    "servers": [
        {
            "url": "https://mirepo.org/authorIDy",
            "description": "The production authorIDy server"
        }
    ],
    "paths": {
        "/*/{contributorID}": {
            "get": {
                "description": "Retrieve all contributions for a specified contributor identifier.",
                "parameters": [
                    {
                        "name": "contributorID",
                        "in": "path",
                        "description": "The HTTP identifier of a contributor",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "http(s)?://.*"
                        },
                        "style": "simple"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful operation",
                         "headers": {
                           "Link": {
                            "schema": {
                              "type": "array",
                                "items": {
                                  "type": "string"
                                 },
                            "example": 
                              "<http://service/{sinceDate}/{contributorID}?page=0> 
                                   ; rel=\"prev\",
                               <http://service/{sinceDate}/{contributorID}?page=2> 
                                   ; rel=\"next\""
                              },
                             "required": false,
                             "description": "Optional links to next or previous pages (or both)"
                             }
                        },
                        "content": {
                            "application/json":
                            {
                              "schema":
                               {
                               "$ref": "https://signposting.org/authorIDy/authorIDy_schema.json"
                               }
                            }
                         }
                    },
                    "404": {
                        "description": "Unknown contributor identifier"
                    }
                }
            }
        },
        "/{sinceDate}/{contributorID}": {
            "get": {
                "description": "Retrieve contributions since and including 
                 an accession date (yyyymmdd) for a specified contributor identifier.",
                "parameters": [
                    {
                        "name": "contributorID",
                        "in": "path",
                        "description": "The HTTP identifier of a contributor",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "http(s)?://.*"
                        },
                        "style": "simple"
                    },
                    {
                        "name": "sinceDate",
                        "in": "path",
                        "description": "The accession date in yyyymmdd format",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "\\d{4}\\d{2}\\d{2}"
                        },
                        "style": "simple"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful operation",
                         "headers": {
                           "Link": {
                            "schema": {
                              "type": "array",
                                "items": {
                                  "type": "string"
                                 },
                            "example": 
                              "<http://service/{sinceDate}/{contributorID}?page=0> 
                                   ; rel=\"prev\",
                               <http://service/{sinceDate}/{contributorID}?page=2> 
                                   ; rel=\"next\""
                              },
                             "required": false,
                             "description": "Optional links to next or previous pages (or both)"
                             }
                        },
                        "content": {
                            "application/json":
                            {
                              "schema":
                               {
                               "$ref": "https://signposting.org/authorIDy/authorIDy_schema.json"
                               }
                            }
                         }
                    },
                    "404": {
                        "description": "Unknown contributor identifier"
                    },
                    "400": {
                        "description": "Date in yyyymmdd format required."
                    }
                }
            }
        }
    }
}