Resource

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-resource-schema.json",
  "title": "Resource",
  "description": "Financial data is added to an Application via one or more Resources.\n\nThe data from multiple resources is compiled into a single aggregate dataset by generating a Report.",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-apply-api-openapi.yml#/components/schemas/Resource",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "_id": {
          "$ref": "#/$defs/DocumentId"
        },
        "_application": {
          "type": "string",
          "pattern": "^application_[a-z0-9]{24,27}$",
          "description": "The application that this document belongs to."
        },
        "type": {
          "type": "string",
          "enum": [
            "document"
          ]
        },
        "status": {
          "$ref": "#/$defs/ResourceStatus"
        },
        "name": {
          "type": "string",
          "maxLength": 255,
          "description": "The filename of this document."
        },
        "failure_reason": {
          "type": "object",
          "properties": {
            "code": {
              "$ref": "#/$defs/DocumentFailureReasonCode"
            },
            "message": {
              "type": "string",
              "default": "Sorry, something went wrong while processing this document. Please try again later."
            }
          },
          "required": [
            "code"
          ],
          "description": "If this document has failed to be processed, this field provides additional detail about what went wrong."
        },
        "channel": {
          "oneOf": [
            {
              "$ref": "#/$defs/DocumentChannelSharingRequest"
            },
            {
              "$ref": "#/$defs/DocumentChannelApi"
            },
            {
              "$ref": "#/$defs/DocumentChannelPortal"
            },
            {
              "$ref": "#/$defs/DocumentChannelReferral"
            }
          ],
          "description": "The channel that was used to create the document along with any relevant metadata for that channel.\n\nThis field can be used to determine whether the document was created via a Sharing Request, API, or the Akahu Apply portal."
        },
        "source": {
          "oneOf": [
            {
              "$ref": "#/$defs/DocumentSourceDirectUpload"
            },
            {
              "$ref": "#/$defs/DocumentSourceOneoffObConnection"
            }
          ],
          "description": "How the document file was ingested by Akahu Apply.\n\nThis field can be used to determine whether the document was uploaded directly from an external source, or sourced from an open banking connection."
        },
        "content_details": {
          "$ref": "#/$defs/DocumentContentDetails"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this document was created."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this document was last updated at."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiry for the document, after which the record will be deleted. Expiry varies as the document progresses through its lifecycle:\n\n - While the document has a status of `pending`, expiry is short lived, ensuring that the record is cleaned up quickly if a file is never uploaded.\n\n - After the document upload has been received, a 1 year expiry is set, after which the document and all associated data will be permanently deleted."
        }
      },
      "required": [
        "_id",
        "_application",
        "type",
        "status",
        "name",
        "channel",
        "source",
        "created_at",
        "updated_at"
      ]
    },
    {
      "type": "object",
      "properties": {
        "_id": {
          "$ref": "#/$defs/DatafileId"
        },
        "_application": {
          "type": "string",
          "pattern": "^application_[a-z0-9]{24,27}$",
          "description": "The application that this datafile belongs to."
        },
        "type": {
          "type": "string",
          "enum": [
            "datafile"
          ]
        },
        "status": {
          "$ref": "#/$defs/ResourceStatus"
        },
        "name": {
          "type": "string",
          "maxLength": 255,
          "description": "The filename of this datafile."
        },
        "content_type": {
          "type": "string",
          "enum": [
            "application/json"
          ],
          "description": "The content type of the datafile."
        },
        "schema": {
          "type": "string",
          "description": "The name of the schema for this datafile."
        },
        "failure_reason": {
          "type": "object",
          "properties": {
            "code": {
              "$ref": "#/$defs/DatafileFailureReasonCode"
            },
            "message": {
              "type": "string",
              "default": "Sorry, something went wrong while processing this datafile. Please try again later."
            }
          },
          "required": [
            "code"
          ],
          "description": "If this datafile has failed to be processed, this field provides additional detail about what went wrong."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this datafile was created."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this datafile was last updated at."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiry for the datafile, after which the record will be deleted. Expiry varies as the datafile progresses through its lifecycle:\n\n - While the datafile has a status of `pending`, expiry is short lived, ensuring that the record is cleaned up quickly if a file is never uploaded.\n\n - After the datafile upload has been received, a 1 year expiry is set, after which the datafile and all associated data will be permanently deleted."
        }
      },
      "required": [
        "_id",
        "_application",
        "type",
        "status",
        "name",
        "content_type",
        "schema",
        "created_at",
        "updated_at"
      ]
    },
    {
      "type": "object",
      "properties": {
        "_id": {
          "$ref": "#/$defs/OneoffOpenBankingConnectionId"
        },
        "_application": {
          "type": "string",
          "pattern": "^application_[a-z0-9]{24,27}$",
          "description": "The application that this open banking connection belongs to."
        },
        "type": {
          "type": "string",
          "enum": [
            "oneoff_ob_connection"
          ]
        },
        "status": {
          "$ref": "#/$defs/ResourceStatus"
        },
        "failure_reason": {
          "type": "object",
          "properties": {
            "code": {
              "$ref": "#/$defs/OneoffOpenBankingConnectionFailureReasonCode"
            },
            "message": {
              "type": "string",
              "default": "Something went wrong while processing this connection."
            }
          },
          "required": [
            "code"
          ],
          "description": "If this open banking connection has failed to complete, this field provides additional detail about what went wrong."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this open banking connection was created."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date that this open banking connection was last updated at."
        }
      },
      "required": [
        "_id",
        "_application",
        "type",
        "status",
        "created_at",
        "updated_at"
      ]
    }
  ],
  "$defs": {
    "DatafileFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "invalid_input",
        "timeout",
        "malware_scan_failed",
        "malware_detected"
      ]
    },
    "DatafileId": {
      "type": "string",
      "pattern": "^dat_[a-z0-9]{24,27}$"
    },
    "DocumentChannelApi": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "api"
          ]
        }
      },
      "required": [
        "type"
      ],
      "description": "The document was uploaded via API."
    },
    "DocumentChannelPortal": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "portal"
          ]
        }
      },
      "required": [
        "type"
      ],
      "description": "The document was uploaded via the Akahu Apply portal."
    },
    "DocumentChannelReferral": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "referral"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^referral_[a-z0-9]{24,27}$",
          "description": "The ID of the referral that was used to add this document."
        },
        "original_channel_type": {
          "type": "string",
          "enum": [
            "sharing_request",
            "api",
            "portal"
          ],
          "description": "The channel that the original document was created through."
        },
        "referrer": {
          "type": "object",
          "properties": {
            "_id": {
              "$ref": "#/$defs/OrgId"
            },
            "name": {
              "type": "string"
            },
            "logo": {
              "type": "string",
              "description": "A URL referencing the org's logo in PNG format."
            }
          },
          "required": [
            "_id",
            "name"
          ],
          "description": "The organisation that referred the document."
        }
      },
      "required": [
        "type",
        "_id"
      ],
      "description": "The document was copied from a referral."
    },
    "DocumentChannelSharingRequest": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "sharing_request"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^sharing_request_[a-z0-9]{24,27}$",
          "description": "The ID of the sharing request that this document was used to add this document."
        }
      },
      "required": [
        "type",
        "_id"
      ],
      "description": "The document was uploaded via sharing request."
    },
    "DocumentContentDetails": {
      "type": "object",
      "properties": {
        "page_count": {
          "type": "number"
        },
        "processed_count": {
          "type": "number"
        },
        "skipped_count": {
          "type": "number"
        },
        "unprocessed_count": {
          "type": "number"
        },
        "ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DocumentContentRange"
          }
        }
      },
      "required": [
        "page_count",
        "processed_count",
        "skipped_count",
        "unprocessed_count",
        "ranges"
      ]
    },
    "DocumentContentRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "number"
        },
        "end": {
          "type": "number"
        },
        "outcome": {
          "$ref": "#/$defs/DocumentRangeOutcome"
        },
        "inferred_content": {
          "$ref": "#/$defs/DocumentContentType"
        }
      },
      "required": [
        "start",
        "end",
        "outcome",
        "inferred_content"
      ],
      "description": "Describes the processing outcome of a range of pages in a document."
    },
    "DocumentContentType": {
      "type": "string",
      "enum": [
        "blank",
        "passport",
        "drivers_license",
        "financial_statement",
        "income_statement",
        "unknown"
      ],
      "description": "The inferred type of content on a given document page:\n\n - `blank`: A blank page\n\n - `financial_statement`: A financial statement\n\n - `passport`: A passport\n\n - `drivers_license`: A drivers license\n\n - `income_statement`: An income summary or statement\n\n - `unknown`: Unknown"
    },
    "DocumentFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "invalid_input",
        "password_protected",
        "timeout",
        "malware_scan_failed",
        "malware_detected"
      ]
    },
    "DocumentId": {
      "type": "string",
      "pattern": "^doc_[a-z0-9]{24,27}$"
    },
    "DocumentRangeOutcome": {
      "type": "string",
      "enum": [
        "processed",
        "unprocessed",
        "skipped"
      ],
      "description": "The outcome from processing a range of pages:\n\n - `processed`: The pages were processed and data has been successfully extracted.\n\n - `skipped`: The pages skipped processing. This usually occurs because any data in the document was not required in the generation of the report (eg. a blank page).\n\n - `unprocessed`: The pages were unable to be processed. This occurs if the content is not supported by Akahu Apply, or if an error occurred during processing."
    },
    "DocumentSourceDirectUpload": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "direct_upload"
          ]
        }
      },
      "required": [
        "type"
      ],
      "description": "The documented was uploaded to Akahu Apply from an external source."
    },
    "DocumentSourceOneoffObConnection": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "oneoff_ob_connection"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^oneoff_ob_connection_[a-z0-9]{24,27}$",
          "description": "The ID of the one-off open banking connection that this document was sourced from."
        }
      },
      "required": [
        "type",
        "_id"
      ],
      "description": "The document was sourced directly from an open banking connection."
    },
    "OneoffOpenBankingConnectionFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "timeout"
      ]
    },
    "OneoffOpenBankingConnectionId": {
      "type": "string",
      "pattern": "^oneoff_ob_connection_[a-z0-9]{24,27}$"
    },
    "OrgId": {
      "type": "string",
      "pattern": "^org_[a-z0-9]{24,27}$"
    },
    "ResourceStatus": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ],
      "description": "The status of a resource:\n\n - `pending` The resource record exists, but has not yet been fully loaded.\n\n - `processing` The data from this record is being extracted and processed.\n\n - `completed` This resource has been successfully processed.\n\n - `failed` This resource has not been successfully processed. See the `failure_reason` for more detail."
    }
  }
}