Aggregator

An aggregator needs to share a list of DOIs that they host with GetFTR, so that our internal API can send entitlement requests for those DOIs to both the publisher (if they partcipcate in GetFTR), and the aggregator.

Without a list of DOIs held by the aggregator, GetFTR is unable to determine which entitlement requests it should send to both publisher and aggregator APIs. GetFTR supports ingesting lists of DOIs per aggregator platform.

Process

1. .jsonl.gz files are periodically submitted to GetFTR using an AWS S3 Bucket 
2. GetFTR ingests these les and adds or removes DOI holdings for the aggregator
3. Our internal API receives an entitlement request for a DOI held by an aggregator and sends an entitlement request to both the Publisher and Aggregator

Getting Started

Once an aggregator has agreed to join GetFTR, they will provide the name of their platform. GetFTR then provides access to submit les for ingestion to an AWS S3 Bucket.

File Format

Each file sent to GetFTR should be a .jsonl.gz file containing a list of DOIs. The file has the following requirements and constraints:

• A maximum of 10,000 DOIs per file
• Contains newline delimited JSON 
• Is gzipped before submission
• Filename must be unique, including a UUID (e.g. f0e17914-9c70-4520-8196-4f8b47d40876.jsonl.gz)

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Aggregator Deposit Schema",
  "description": "Schema for associating a DOI with an aggregator",
  "type": "object",
  "required": ["doi"],
  "additionalProperties": false,
  "examples": [
    {
      "doi": "10.1234/5678",
      "accessType": "paid",
      "vor": [
        {
          "url": "https://example.com/content.pdf",
          "contentType": "application/pdf"
        }
      ]
    },
    {
      "doi": "10.9876/54321",
      "deleted": true
    },
    {
      "doi": "10.5678/1234",
      "accessType": "paid"
    }
  ],
  "properties": {
    "deleted": {
      "type": "boolean",
      "description": "If true, the record will be disassociated"
    },
    "doi": {
      "type": "string",
      "description": "DOI to store information against"
    },
    "accessType": {
      "type": "string",
      "description": "Access Type for the DOI",
      "enum": ["paid", "open", "free", "permFree"]
    },
    "vor": {
      "type": "array",
      "minItems": 1,
      "description": "List of additional content links for the DOI, typically used for providing a link directly to a PDF",
      "items": {
        "type": "object",
        "required": ["url"],
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to the content",
            "pattern": "^https?://"
          },
          "contentType": {
            "type": "string",
            "description": "Content Type for the URL, eg. application/pdf",
            "enum": [
              "application/pdf",
              "text/html",
              "application/epub+zip",
              "other"
            ]
          }
        }
      }
    }
  }
}

Updates

Updates to records will overwrite existing data for the association of a DOI with an aggregator. When deleted is set to true, the association of a DOI for an aggregator is removed.

Error Handling

The ingestion pipeline will be monitored by GetFTR. The pipeline will automatically handle recoverable failures. Failures that cannot be recovered from automatically will be manually handled by GetFTR. GetFTR will reach out to the producer if their input is required.

Entitlement Resolution

For DOIs submitted by an aggregator with an accessType of paid, requests will be sent to the Aggregator Entitlement API. For DOIs with an accessType of open, free or permFree, the platform will respond on behalf of the aggregator, using the vor property submitted alongside the DOI.

Entitlement API

For an aggregator providing an Entitlement API, please follow instructions as per a publisher.