{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/arkrel-com/json-schema/arkrel-com-tax-report-schema.json",
  "title": "TaxReport",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/arkrel-com-openapi.yaml#/components/schemas/TaxReport",
  "type": "object",
  "required": [
    "year",
    "income_total",
    "total_expenses",
    "net_profit",
    "schedule_c_expenses",
    "schedule_c_net_profit",
    "schedule_c_lines",
    "deductible_expenses",
    "uncategorized_transactions",
    "excluded_transactions",
    "equipment_needs_review",
    "likely_needs_1099",
    "form_1099",
    "balance_sheet"
  ],
  "properties": {
    "year": {
      "type": "integer"
    },
    "income_total": {
      "type": "number"
    },
    "total_expenses": {
      "type": "number",
      "description": "Cash P&L view: the full cash amount spent across all expense categories, with no deductible-percentage limitations applied."
    },
    "net_profit": {
      "type": "number",
      "description": "Cash P&L view: income_total minus total_expenses."
    },
    "schedule_c_expenses": {
      "type": "number",
      "description": "Schedule C view: the sum of schedule_c_lines' totals, i.e. with any deductible-percentage limitations (such as the 50% meals limit) already applied. Differs from total_expenses whenever a limited category has spend."
    },
    "schedule_c_net_profit": {
      "type": "number",
      "description": "Schedule C view: income_total minus schedule_c_expenses."
    },
    "schedule_c_lines": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ScheduleCLine"
      }
    },
    "deductible_expenses": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DeductibleExpense"
      }
    },
    "uncategorized_transactions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UncategorizedTransaction"
      }
    },
    "excluded_transactions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExcludedTransaction"
      }
    },
    "equipment_needs_review": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EquipmentReviewItem"
      }
    },
    "likely_needs_1099": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/LikelyPayee"
      }
    },
    "form_1099": {
      "$ref": "#/$defs/Form1099Reconciliation"
    },
    "balance_sheet": {
      "$ref": "#/$defs/BalanceSheet"
    }
  },
  "$defs": {
    "BalanceSheet": {
      "type": "object",
      "required": [
        "as_of_year_end",
        "lines",
        "cash_total",
        "credit_card_owed",
        "note"
      ],
      "description": "A cash-basis account-balances SNAPSHOT (each account's latest\nstatement closing balance at or before December 31), not a\nformal accrual balance sheet. See `note`.\n",
      "properties": {
        "as_of_year_end": {
          "type": "integer"
        },
        "lines": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BalanceSheetLine"
          }
        },
        "cash_total": {
          "type": "number",
          "description": "Sum of every bank-type line's closing_balance: cash the person has. Never combined with credit_card_owed."
        },
        "credit_card_owed": {
          "type": "number",
          "description": "Sum of every credit_card-type line's closing_balance, as a signed amount: positive means debt, negative means a credit balance. A line with account_type null counts toward neither total."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "BalanceSheetLine": {
      "type": "object",
      "required": [
        "account_number",
        "label",
        "as_of_date",
        "closing_balance",
        "document_id",
        "account_type"
      ],
      "properties": {
        "currency": {
          "type": [
            "string",
            "null"
          ],
          "description": "Source currency. Only USD balances count in USD totals."
        },
        "account_number": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "as_of_date": {
          "type": "string",
          "format": "date"
        },
        "closing_balance": {
          "type": "number"
        },
        "document_id": {
          "type": "string"
        },
        "account_type": {
          "$ref": "#/$defs/BankStatementAccountType"
        }
      }
    },
    "BankStatementAccountType": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "bank",
        "credit_card"
      ],
      "description": "From the statement's own extraction. Null when the statement doesn't make it determinable, or predates this field: never guessed from the balance's sign. Distinct from the categorization feature's own AccountType (asset/liability/equity/income/expense/ personal), this one is \"which KIND of statement did this come from,\" never a chart-of-accounts classification."
    },
    "DeductibleExpense": {
      "type": "object",
      "required": [
        "document_id",
        "row_index",
        "date",
        "description",
        "amount",
        "category",
        "category_label",
        "overridden",
        "confidence",
        "confidence_label",
        "reconciled",
        "source_page"
      ],
      "properties": {
        "document_id": {
          "type": "string",
          "description": "Drill-down target: GET /v1/documents/{id} (or the app's /app/documents/{id} viewer) for the statement this transaction came from."
        },
        "row_index": {
          "type": "integer"
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "description": {
          "type": "string"
        },
        "amount": {
          "type": "number",
          "description": "Positive for an ordinary debit (money spent); negative for a refund/credit in the same category, so the direction a refund actually moved is never lost."
        },
        "category": {
          "$ref": "#/$defs/TaxReportCategory"
        },
        "category_label": {
          "type": "string"
        },
        "overridden": {
          "type": "boolean",
          "description": "True only when the person saved their own correction for this transaction."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "How sure the CATEGORY guess is. A separate signal from `reconciled`. Never merge the two into one \"verified\" indicator."
        },
        "confidence_label": {
          "type": "string",
          "description": "The ready-to-render label for this transaction's confidence: \"You set this\" for a person's own saved correction, \"Standard rule\" (or, once a real per-org rule exists, \"Your rule\") for a deterministic keyword-rule match, and \"Category confidence: NN%\" only for a genuine low-confidence fallback guess. Always show this verbatim; never recompute a percentage from `confidence`. A rule match or a saved correction is never a probabilistic guess."
        },
        "reconciled": {
          "type": "boolean",
          "description": "True only when this transaction's source statement reached `succeeded` (every verification check passed). Independent of `confidence`."
        },
        "source_page": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Always null today. No per-transaction-row page number is extracted yet. Never fabricated; `document_id` is the real drill-down target in the meantime."
        }
      }
    },
    "EquipmentReviewItem": {
      "type": "object",
      "required": [
        "document_id",
        "row_index",
        "date",
        "description",
        "amount",
        "note"
      ],
      "description": "A large one-time purchase routed to review instead of an automatic deduction, not included in total_expenses until resolved.",
      "properties": {
        "document_id": {
          "type": "string"
        },
        "row_index": {
          "type": "integer"
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "description": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ExcludedTransaction": {
      "type": "object",
      "required": [
        "document_id",
        "row_index",
        "date",
        "description",
        "amount",
        "reason",
        "reason_label"
      ],
      "description": "A transfer between the person's own accounts, or spending that looks personal (an owner draw), excluded from every total, shown here so nothing is silently dropped.",
      "properties": {
        "document_id": {
          "type": "string"
        },
        "row_index": {
          "type": "integer"
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "description": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "enum": [
            "transfer",
            "personal",
            "balance_sheet"
          ]
        },
        "reason_label": {
          "type": "string"
        }
      }
    },
    "Form1099Entry": {
      "type": "object",
      "required": [
        "id",
        "tax_year",
        "form_type",
        "payer_name",
        "amount",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "tax_year": {
          "type": "integer"
        },
        "form_type": {
          "type": "string",
          "enum": [
            "NEC",
            "K"
          ]
        },
        "payer_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "amount": {
          "type": "number"
        },
        "document_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "Form1099Reconciliation": {
      "type": "object",
      "required": [
        "tax_year",
        "entries",
        "total_reported",
        "gross_receipts",
        "difference",
        "citation"
      ],
      "properties": {
        "tax_year": {
          "type": "integer"
        },
        "entries": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Form1099Entry"
          }
        },
        "total_reported": {
          "type": "number"
        },
        "gross_receipts": {
          "type": "number"
        },
        "difference": {
          "type": [
            "number",
            "null"
          ],
          "description": "gross_receipts minus total_reported. Null while entries is empty: before at least one 1099 has been entered there is nothing to compare yet."
        },
        "citation": {
          "type": "string"
        }
      }
    },
    "LikelyPayee": {
      "type": "object",
      "required": [
        "payee_label",
        "total",
        "transaction_count",
        "threshold",
        "threshold_tax_year"
      ],
      "description": "A vendor this org paid at or above the year's 1099 threshold in a service-like category, a \"likely,\" never a determination (no verified payee identity/TIN).",
      "properties": {
        "payee_label": {
          "type": "string"
        },
        "total": {
          "type": "number"
        },
        "transaction_count": {
          "type": "integer"
        },
        "threshold": {
          "type": "integer",
          "description": "Published service-payment reporting threshold applied to this report. 600 through 2025 and 2000 for 2026. Later report years use the most recent published entry."
        },
        "threshold_tax_year": {
          "type": "integer",
          "description": "Tax year of the published IRS threshold applied. The 2025 entry also covers earlier report years; later report years use the most recent published entry."
        }
      }
    },
    "ScheduleCLine": {
      "type": "object",
      "required": [
        "category",
        "label",
        "line",
        "line_label",
        "total",
        "full_amount",
        "note"
      ],
      "properties": {
        "category": {
          "$ref": "#/$defs/TaxReportCategory"
        },
        "label": {
          "type": "string"
        },
        "line": {
          "type": "string",
          "description": "The exact Schedule C (Form 1040) 2025 line number, e.g. \"8\" or \"24b\"."
        },
        "line_label": {
          "type": "string",
          "description": "The form's own printed label for that line."
        },
        "total": {
          "type": "number",
          "description": "The amount actually reportable on this Schedule C line. For a category with a deductible limitation (e.g. meals at 50% under IRC section 274(n)(1) and the Instructions for Schedule C, line 24b), this is the DEDUCTIBLE amount, not the full cash spend, see full_amount."
        },
        "full_amount": {
          "type": [
            "number",
            "null"
          ],
          "description": "The full cash amount spent in this category before any deductible-percentage limitation was applied. Present (and different from total) only for categories with a limitation, such as meals; null otherwise."
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "TaxReportCategory": {
      "type": "string",
      "enum": [
        "business_income",
        "transfer_excluded",
        "balance_sheet_excluded",
        "advertising",
        "car_and_truck",
        "commissions_and_fees",
        "contract_labor",
        "depletion",
        "depreciation",
        "employee_benefit_programs",
        "mortgage_interest",
        "pension_and_profit_sharing",
        "rent_or_lease_vehicles_equipment",
        "insurance",
        "interest",
        "legal_and_professional",
        "office_expense",
        "rent_or_lease",
        "repairs_and_maintenance",
        "supplies",
        "taxes_and_licenses",
        "travel",
        "meals",
        "utilities",
        "wages",
        "other_expenses",
        "personal_not_deductible",
        "uncategorized",
        "equipment_needs_review"
      ]
    },
    "UncategorizedTransaction": {
      "type": "object",
      "required": [
        "document_id",
        "row_index",
        "date",
        "description",
        "amount",
        "confidence",
        "confidence_label",
        "reconciled",
        "source_page"
      ],
      "properties": {
        "currency": {
          "type": [
            "string",
            "null"
          ],
          "description": "Source currency. Non-USD amounts do not count in USD totals."
        },
        "review_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "What needs to be resolved before this amount can count in totals."
        },
        "document_id": {
          "type": "string"
        },
        "row_index": {
          "type": "integer"
        },
        "date": {
          "type": "string",
          "description": "Transaction date as YYYY-MM-DD, or an empty string when unknown. Unknown dates never count in year totals."
        },
        "description": {
          "type": "string"
        },
        "amount": {
          "type": [
            "number",
            "null"
          ],
          "description": "Signed amount, or null when our reading missed the amount. Resolve the review item before including it in totals."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "confidence_label": {
          "type": "string",
          "description": "Same ready-to-render label as DeductibleExpense.confidence_label."
        },
        "reconciled": {
          "type": "boolean"
        },
        "source_page": {
          "type": [
            "integer",
            "null"
          ]
        }
      }
    }
  }
}