report

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/folio/main/json-schema/folio-report-schema.json",
  "title": "report",
  "description": "Usage report schema",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/folio-mod-eusage-reports-eusage-reports-1-0-openapi.yml#/components/schemas/report",
  "type": "object",
  "properties": {
    "agreementId": {
      "type": "string",
      "description": "Agreement identifier",
      "format": "uuid"
    },
    "accessCountPeriods": {
      "description": "List of reporting periods, either a list of months or a list of years, for example [\"2020-03\", \"2020-04\", \"2020-05\"]",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "totalItemRequestsTotal": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Access count total for all periods and all items"
    },
    "totalItemRequestsByPeriod": {
      "type": "array",
      "description": "Access count per period, total for all items",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "totalRequestsPublicationYearsByPeriod": {
      "type": "array",
      "description": "Access count per period for each publication year, total for all items",
      "items": {
        "type": "object",
        "description": "object with publication year as key and count as value"
      }
    },
    "totalRequestsPeriodsOfUseByPeriod": {
      "type": "array",
      "description": "Access count per period for each publication period, total for all items",
      "items": {
        "type": "object",
        "description": "object with publication year as key and count as value"
      }
    },
    "uniqueItemRequestsTotal": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unique access count total for all periods and all items"
    },
    "uniqueItemRequestsByPeriod": {
      "type": "array",
      "description": "Unique access count per period, total for all items",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "uniqueRequestsPublicationYearsByPeriod": {
      "type": "array",
      "description": "Unique count per period for each publication year, total for all items",
      "items": {
        "type": "object",
        "description": "object with publication year as key and count as value"
      }
    },
    "uniqueRequestsPeriodsOfUseByPeriod": {
      "type": "array",
      "description": "Unique access count per period for each publication period, total for all items",
      "items": {
        "type": "object",
        "description": "object with publication year as key and count as value"
      }
    },
    "items": {
      "description": "List of items, with access data per item",
      "type": "array",
      "items": {
        "$ref": "#/$defs/reportRow"
      }
    },
    "execution": {
      "description": "Information about execution, such as various timings",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "reportRow": {
      "description": "Single row of usage report data",
      "type": "object",
      "properties": {
        "kbId": {
          "type": "string",
          "description": "KB identifier"
        },
        "title": {
          "type": "string",
          "description": "Title of the item"
        },
        "printISSN": {
          "type": "string",
          "description": "ISSN for print instance"
        },
        "onlineISSN": {
          "type": "string",
          "description": "ISSN for online instance"
        },
        "ISBN": {
          "type": "string",
          "description": "ISBN for instance"
        },
        "publicationYear": {
          "type": "string",
          "description": "Publication year .. or range (eg 2000 for 1Y, or 2000-2001 for 2Y)"
        },
        "periodOfUse": {
          "type": "string",
          "description": "The usage period of this publication year report row, either one month like 2018-03 or one year like 2018 or a month range like 2018-03 - 2018-05 or a year range like 2018-2019"
        },
        "accessType": {
          "type": "string",
          "description": "Counter report access type like controlled or OA_Gold"
        },
        "metricType": {
          "type": "string",
          "enum": [
            "Total_Item_Requests",
            "Unique_Item_Requests"
          ],
          "description": "Handling of multiple requests of the same client"
        },
        "accessCountTotal": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Sum of all access counts"
        },
        "accessCountsByPeriod": {
          "type": "array",
          "description": "Access count per reporting period",
          "items": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "additionalProperties": false
    }
  }
}