Events API Specification - ASPSP Endpoints

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/open-banking-uk/refs/heads/main/json-schema/events.json",
  "title": "Events API Specification - ASPSP Endpoints",
  "description": "OpenAPI for Events (Subscription & Aggregated Polling) API Specification - ASPSP Endpoints.\n\n**Please Note**: There are no optional fields, if a field is not marked as \u201cRequired\u201d it is a Conditional field.\n",
  "version": "4.0.1",
  "$defs": {
    "ISODateTime": {
      "description": "All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00",
      "type": "string",
      "format": "date-time"
    },
    "Links": {
      "type": "object",
      "description": "Links relevant to the payload",
      "properties": {
        "Self": {
          "type": "string",
          "format": "uri"
        },
        "First": {
          "type": "string",
          "format": "uri"
        },
        "Prev": {
          "type": "string",
          "format": "uri"
        },
        "Next": {
          "type": "string",
          "format": "uri"
        },
        "Last": {
          "type": "string",
          "format": "uri"
        }
      },
      "additionalProperties": false,
      "required": [
        "Self"
      ]
    },
    "Meta": {
      "title": "MetaData",
      "type": "object",
      "description": "Meta Data relevant to the payload",
      "properties": {
        "TotalPages": {
          "type": "integer",
          "format": "int32"
        },
        "FirstAvailableDateTime": {
          "$ref": "#/components/schemas/ISODateTime"
        },
        "LastAvailableDateTime": {
          "$ref": "#/components/schemas/ISODateTime"
        }
      },
      "additionalProperties": false
    },
    "OBError1": {
      "type": "object",
      "properties": {
        "ErrorCode": {
          "$ref": "#/components/schemas/OBExternalStatusReason1Code"
        },
        "Message": {
          "description": "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nOBIE doesn't standardise this field",
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "Path": {
          "description": "Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency",
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "Url": {
          "description": "URL to help remediate the problem, or provide more information, or to API Reference, or help etc",
          "type": "string"
        }
      },
      "required": [
        "ErrorCode"
      ],
      "additionalProperties": false,
      "minProperties": 1
    },
    "OBErrorResponse1": {
      "description": "An array of detail error codes, and messages, and URLs to documentation to help remediation.",
      "type": "object",
      "properties": {
        "Id": {
          "description": "A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.",
          "type": "string",
          "minLength": 1,
          "maxLength": 40
        },
        "Code": {
          "description": "Deprecated <br>High level textual error code, to help categorise the errors.",
          "type": "string",
          "minLength": 1,
          "example": "400 BadRequest",
          "maxLength": 40
        },
        "Message": {
          "description": "Deprecated <br>Brief Error message",
          "type": "string",
          "minLength": 1,
          "example": "There is something wrong with the request parameters provided",
          "maxLength": 500
        },
        "Errors": {
          "items": {
            "$ref": "#/components/schemas/OBError1"
          },
          "type": "array",
          "minItems": 1
        }
      },
      "required": [
        "Errors"
      ],
      "additionalProperties": false
    },
    "OBEventSubscription1": {
      "type": "object",
      "required": [
        "Data"
      ],
      "properties": {
        "Data": {
          "type": "object",
          "required": [
            "Version"
          ],
          "properties": {
            "CallbackUrl": {
              "description": "Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.",
              "type": "string",
              "format": "uri"
            },
            "Version": {
              "$ref": "#/components/schemas/Version"
            },
            "EventTypes": {
              "type": "array",
              "items": {
                "description": "Array of event types the subscription applies to.",
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "OBEventSubscriptionResponse1": {
      "type": "object",
      "required": [
        "Data"
      ],
      "properties": {
        "Data": {
          "type": "object",
          "required": [
            "EventSubscriptionId",
            "Version"
          ],
          "properties": {
            "EventSubscriptionId": {
              "description": "Unique identification as assigned by the ASPSP to uniquely identify the callback URL resource.",
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            },
            "CallbackUrl": {
              "description": "Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.",
              "type": "string",
              "format": "uri"
            },
            "Version": {
              "$ref": "#/components/schemas/Version"
            },
            "EventTypes": {
              "type": "array",
              "items": {
                "description": "Array of event types the subscription applies to.",
                "type": "string"
              }
            }
          }
        },
        "Links": {
          "$ref": "#/components/schemas/Links"
        },
        "Meta": {
          "$ref": "#/components/schemas/Meta"
        }
      },
      "additionalProperties": false
    },
    "OBEventSubscriptionsResponse1": {
      "type": "object",
      "required": [
        "Data"
      ],
      "properties": {
        "Data": {
          "type": "object",
          "properties": {
            "EventSubscription": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "EventSubscriptionId",
                  "Version"
                ],
                "properties": {
                  "EventSubscriptionId": {
                    "description": "Unique identification as assigned by the ASPSP to uniquely identify the callback url resource.",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40
                  },
                  "CallbackUrl": {
                    "description": "Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.",
                    "type": "string",
                    "format": "uri"
                  },
                  "Version": {
                    "$ref": "#/components/schemas/Version"
                  },
                  "EventTypes": {
                    "type": "array",
                    "items": {
                      "description": "Array of event types the subscription applies to.",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "Links": {
          "$ref": "#/components/schemas/Links"
        },
        "Meta": {
          "$ref": "#/components/schemas/Meta"
        }
      },
      "additionalProperties": false
    },
    "Version": {
      "description": "Version for the event notification.",
      "type": "string",
      "minLength": 1,
      "maxLength": 10
    },
    "OBEventPolling1": {
      "type": "object",
      "properties": {
        "maxEvents": {
          "description": "Maximum number of events to be returned. A value of zero indicates the ASPSP should not return events even if available",
          "type": "integer"
        },
        "returnImmediately": {
          "description": "Indicates whether an ASPSP should return a response immediately or provide a long poll",
          "type": "boolean"
        },
        "ack": {
          "type": "array",
          "items": {
            "description": "An array of jti values indicating event notifications positively acknowledged by the TPP",
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        },
        "setErrs": {
          "type": "object",
          "description": "An object that encapsulates all negative acknowledgements transmitted by the TPP",
          "properties": {},
          "additionalProperties": {
            "type": "object",
            "required": [
              "err",
              "description"
            ],
            "properties": {
              "err": {
                "description": "A value from the IANA \"Security Event Token Delivery Error Codes\" registry that identifies the error as defined here \nhttps://tools.ietf.org/id/draft-ietf-secevent-http-push-03.html#error_codes",
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              },
              "description": {
                "description": "A human-readable string that provides additional diagnostic information",
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "OBEventPollingResponse1": {
      "type": "object",
      "required": [
        "moreAvailable",
        "sets"
      ],
      "properties": {
        "moreAvailable": {
          "description": "A JSON boolean value that indicates if more unacknowledged event notifications are available to be returned.",
          "type": "boolean"
        },
        "sets": {
          "type": "object",
          "description": "A JSON object that contains zero or more nested JSON attributes. If there are no outstanding event notifications to be transmitted, the JSON object SHALL be empty.",
          "properties": {},
          "additionalProperties": {
            "description": "An object named with the jti of the event notification to be delivered. The value is the event notification, expressed as a string.\nThe payload of the event should be defined in the OBEventNotification2 format.",
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "OBExternalStatusReason1Code": {
      "description": "Low level textual error code, for all enum values see `OBExternalStatusReason1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets/)",
      "type": "string",
      "minLength": 4,
      "maxLength": 4,
      "example": "U001"
    }
  }
}