Report

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-report-schema.json",
  "title": "Report",
  "description": "Once your Application has been populated with the required data Resources, a Report can be created. A Report combines the data from all Application Resources into an aggregate, enriched dataset.",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-reports-api-openapi.yml#/components/schemas/Report",
  "type": "object",
  "properties": {
    "_id": {
      "$ref": "#/$defs/ReportId"
    },
    "report_type": {
      "$ref": "#/$defs/ReportType"
    },
    "status": {
      "$ref": "#/$defs/ReportStatus"
    },
    "failure_reason": {
      "$ref": "#/$defs/ReportFailureReason"
    },
    "resources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ReportResource"
      },
      "description": "The resources that were used to generate this report."
    },
    "generated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The date that this report completed synthesis."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "The date that this report expires. After this date the report will no longer be accessible."
    },
    "spending_categories": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SpendingCategory"
      },
      "description": "When this report is `completed`, this field will hold a list of all spending categories used in this report."
    },
    "income_categories": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IncomeCategory"
      },
      "description": "When this report is `completed`, this field will hold a list of all income categories used in this report."
    },
    "insights": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/InsightCategoryCode"
      },
      "description": "When this report is `completed`, this field will hold a list of all insights used in this report."
    }
  },
  "required": [
    "_id",
    "report_type",
    "status",
    "resources",
    "expires_at"
  ],
  "$defs": {
    "DatafileId": {
      "type": "string",
      "pattern": "^dat_[a-z0-9]{24,27}$"
    },
    "DocumentId": {
      "type": "string",
      "pattern": "^doc_[a-z0-9]{24,27}$"
    },
    "IncomeCategory": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^income:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this income category."
        },
        "name": {
          "type": "string",
          "description": "The name of this income category."
        }
      },
      "required": [
        "code",
        "name"
      ],
      "description": "The income category for this transaction"
    },
    "InsightCategoryCode": {
      "type": "string",
      "pattern": "^insight:[0-9]{3}/[a-z0-9-]*$"
    },
    "OneoffOpenBankingConnectionId": {
      "type": "string",
      "pattern": "^oneoff_ob_connection_[a-z0-9]{24,27}$"
    },
    "ReportFailureReason": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/ReportFailureReasonCode"
        },
        "message": {
          "type": "string",
          "default": "Sorry, something went wrong while processing this report. Please try again later."
        }
      },
      "required": [
        "code"
      ],
      "description": "If a report has failed to be synthesized, this field provides additional information about what went wrong."
    },
    "ReportFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "timeout"
      ]
    },
    "ReportId": {
      "type": "string",
      "pattern": "^report_[a-z0-9]{24,27}$"
    },
    "ReportResource": {
      "oneOf": [
        {
          "$ref": "#/$defs/ReportResourceDocument"
        },
        {
          "$ref": "#/$defs/ReportResourceDatafile"
        },
        {
          "$ref": "#/$defs/ReportResourceOneoffOpenBankingConnection"
        }
      ]
    },
    "ReportResourceDatafile": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "datafile"
          ]
        },
        "_id": {
          "$ref": "#/$defs/DatafileId"
        }
      },
      "required": [
        "type",
        "_id"
      ]
    },
    "ReportResourceDocument": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "document"
          ]
        },
        "_id": {
          "$ref": "#/$defs/DocumentId"
        }
      },
      "required": [
        "type",
        "_id"
      ]
    },
    "ReportResourceOneoffOpenBankingConnection": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "oneoff_ob_connection"
          ]
        },
        "_id": {
          "$ref": "#/$defs/OneoffOpenBankingConnectionId"
        }
      },
      "required": [
        "type",
        "_id"
      ]
    },
    "ReportStatus": {
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed"
      ],
      "description": "The status of a report:\n\n - `processing` This report is currently being synthesized.\n\n - `completed` This report has successfully been synthesized and data can now be retrieved from it.\n\n - `failed` This report has failed to be synthesized. See `failure_reason` for more information."
    },
    "ReportType": {
      "type": "string",
      "enum": [
        "standard",
        "income"
      ],
      "description": "The type of report generated for an application:\n\n - `standard` A full report covering accounts, income, expenses and transactions.\n\n - `income` A report focused on income."
    },
    "SpendingCategory": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^spending:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this spending category."
        },
        "name": {
          "type": "string",
          "description": "The name of this spending category."
        }
      },
      "required": [
        "code",
        "name"
      ],
      "description": "The high-level spending category for this transaction."
    }
  }
}