ReportInsight

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-report-insight-schema.json",
  "title": "ReportInsight",
  "description": "An insight derived from data in the report.",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-reports-api-openapi.yml#/components/schemas/ReportInsight",
  "oneOf": [
    {
      "$ref": "#/$defs/ReportInsightCompleted"
    },
    {
      "$ref": "#/$defs/ReportInsightFailed"
    }
  ],
  "$defs": {
    "CounterpartyId": {
      "type": "string",
      "pattern": "^counterparty_[a-z0-9]{24,27}$"
    },
    "IncomeCategoryCode": {
      "type": "string",
      "pattern": "^income:[0-9]{3}/[a-z0-9-]*$"
    },
    "InsightFailureReason": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/InsightFailureReasonCode"
        },
        "message": {
          "type": "string",
          "default": "Sorry, something went wrong while processing this insight."
        }
      },
      "required": [
        "code"
      ],
      "description": "If a report has failed to be synthesized, this field provides additional information about what went wrong."
    },
    "InsightFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "timeout",
        "insufficient_data"
      ],
      "description": "The reason for an insight's failure to be calculated:\n\n - `internal_error` An unhandled internal error prevented the calculation from completing.\n\n - `timeout` The calculation took too long and was cancelled.\n\n - `insufficient_data` The report does not contain the relevant data to calculate this insight."
    },
    "InsightScopeAccount": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "account"
          ],
          "description": "The insight was calculated for a specific account."
        },
        "identifier": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "description": "The name of the account"
        },
        "account_number": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label",
        "account_number"
      ]
    },
    "InsightScopeCounterparty": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "counterparty"
          ],
          "description": "The insight was calculated for a specific counterparty."
        },
        "identifier": {
          "$ref": "#/$defs/CounterpartyId"
        },
        "label": {
          "type": "string",
          "description": "The name of the counterparty"
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label"
      ]
    },
    "InsightScopeIncomeCategory": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "income_category"
          ],
          "description": "The insight was calculated for a specific income category."
        },
        "identifier": {
          "$ref": "#/$defs/IncomeCategoryCode"
        },
        "label": {
          "type": "string",
          "description": "The name of the income category"
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label"
      ]
    },
    "InsightScopeReport": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "report"
          ],
          "description": "The insight was calculated for the entire report."
        },
        "identifier": {
          "$ref": "#/$defs/ReportId"
        },
        "label": {
          "type": "string",
          "description": "The application reference"
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label"
      ]
    },
    "InsightScopeSpendingCategory": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "spending_category"
          ],
          "description": "The insight was calculated for a specific spending category."
        },
        "identifier": {
          "$ref": "#/$defs/SpendingCategoryCode"
        },
        "label": {
          "type": "string",
          "description": "The name of the spending category"
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label"
      ]
    },
    "InsightScopeStream": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "enum": [
            "stream"
          ],
          "description": "The insight was calculated for a specific transaction stream."
        },
        "identifier": {
          "$ref": "#/$defs/StreamId"
        },
        "label": {
          "type": "string",
          "description": "A description of the transaction stream"
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ]
        }
      },
      "required": [
        "dimension",
        "identifier",
        "label",
        "direction"
      ]
    },
    "InsightUnit": {
      "type": "string",
      "enum": [
        "count",
        "currency",
        "percentage",
        "days"
      ],
      "description": "The unit of an insight value:\n\n - `count` The value is a count. This will always be an integer greater than or equal to 0.\n\n - `currency` The value is a quantity of currency in NZD.\n\n - `percentage` The value is a percentage.\n\n - `days` The value is a number of days."
    },
    "ReportId": {
      "type": "string",
      "pattern": "^report_[a-z0-9]{24,27}$"
    },
    "ReportInsightCompleted": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        },
        "code": {
          "type": "string",
          "pattern": "^insight:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this insight."
        },
        "scope": {
          "oneOf": [
            {
              "$ref": "#/$defs/InsightScopeReport"
            },
            {
              "$ref": "#/$defs/InsightScopeAccount"
            },
            {
              "$ref": "#/$defs/InsightScopeCounterparty"
            },
            {
              "$ref": "#/$defs/InsightScopeStream"
            },
            {
              "$ref": "#/$defs/InsightScopeIncomeCategory"
            },
            {
              "$ref": "#/$defs/InsightScopeSpendingCategory"
            }
          ],
          "description": "The scope under which this insight was calculated."
        },
        "description": {
          "type": "string",
          "description": "A description of this insight."
        },
        "value": {
          "type": "number",
          "description": "The quantity measured by the insight"
        },
        "unit": {
          "$ref": "#/$defs/InsightUnit"
        },
        "formatted": {
          "type": "string",
          "description": "The value formatted for display"
        }
      },
      "required": [
        "status",
        "code",
        "scope",
        "description",
        "value",
        "formatted"
      ],
      "description": "An insight that has been successfully calculated."
    },
    "ReportInsightFailed": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "failed"
          ]
        },
        "code": {
          "type": "string",
          "pattern": "^insight:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this insight."
        },
        "scope": {
          "oneOf": [
            {
              "$ref": "#/$defs/InsightScopeReport"
            },
            {
              "$ref": "#/$defs/InsightScopeAccount"
            },
            {
              "$ref": "#/$defs/InsightScopeCounterparty"
            },
            {
              "$ref": "#/$defs/InsightScopeStream"
            },
            {
              "$ref": "#/$defs/InsightScopeIncomeCategory"
            },
            {
              "$ref": "#/$defs/InsightScopeSpendingCategory"
            }
          ],
          "description": "The scope under which this insight was calculated."
        },
        "description": {
          "type": "string",
          "description": "A description of this insight."
        },
        "failure_reason": {
          "$ref": "#/$defs/InsightFailureReason"
        }
      },
      "required": [
        "status",
        "code",
        "scope",
        "description",
        "failure_reason"
      ],
      "description": "An insight that has not been calculated."
    },
    "SpendingCategoryCode": {
      "type": "string",
      "pattern": "^spending:[0-9]{3}/[a-z0-9-]*$"
    },
    "StreamId": {
      "type": "string",
      "pattern": "^stream_[a-z0-9]{24,27}$"
    }
  }
}