InsightsSegmentResults

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/silverfin/main/json-schema/silverfin-insights-segment-results-schema.json",
  "title": "InsightsSegmentResults",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/silverfin-api-openapi.yml#/components/schemas/InsightsSegmentResults",
  "allOf": [
    {
      "$ref": "#/$defs/InsightsSegmentRunBase"
    },
    {
      "type": "object",
      "required": [
        "period_selection",
        "columns",
        "matches",
        "pagination",
        "non_match_count"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "finished"
          ]
        },
        "finished_at": {
          "type": "string",
          "format": "date-time"
        },
        "period_selection": {
          "$ref": "#/$defs/InsightsPeriodSelection"
        },
        "columns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InsightsSegmentColumn"
          }
        },
        "matches": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InsightsSegmentMatch"
          }
        },
        "pagination": {
          "$ref": "#/$defs/InsightsPagination"
        },
        "non_match_count": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  ],
  "$defs": {
    "InsightsFilterValue": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "formatted_value",
        "sort_value"
      ],
      "properties": {
        "formatted_value": {
          "description": "Translated display output. Depending on filter type, this is a string, object, number, boolean, or null."
        },
        "sort_value": {
          "description": "Stable sortable representation. Depending on filter type, this is a string, number, boolean, or null."
        },
        "filter_error": {
          "type": "string",
          "description": "Present only when this filter could not be calculated"
        }
      }
    },
    "InsightsPagination": {
      "type": "object",
      "required": [
        "page",
        "per_page",
        "total_matches",
        "total_pages"
      ],
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "per_page": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "total_matches": {
          "type": "integer",
          "minimum": 0
        },
        "total_pages": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "InsightsPeriodSelection": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "financial_year",
            "accounting_period",
            "active_period",
            "completed_period"
          ]
        },
        "date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Present for financial_year and accounting_period selections"
        },
        "locking_type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "locked",
            "permanently_locked"
          ],
          "description": "Present for active_period and completed_period selections"
        }
      }
    },
    "InsightsSegmentColumn": {
      "type": "object",
      "required": [
        "uuid",
        "type",
        "name",
        "settings"
      ],
      "properties": {
        "uuid": {
          "type": "string",
          "format": "uuid",
          "description": "Correlates this column with values in this response only; it is not a stable identifier across runs."
        },
        "type": {
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "settings": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": true
        }
      }
    },
    "InsightsSegmentMatch": {
      "type": "object",
      "required": [
        "company_id",
        "company_name",
        "period_id",
        "period_end_date",
        "values"
      ],
      "properties": {
        "company_id": {
          "type": "integer"
        },
        "company_name": {
          "type": "string"
        },
        "period_id": {
          "type": "integer"
        },
        "period_end_date": {
          "type": "string",
          "format": "date"
        },
        "values": {
          "type": "object",
          "description": "Values keyed by the corresponding column uuid",
          "additionalProperties": {
            "$ref": "#/$defs/InsightsFilterValue"
          }
        }
      }
    },
    "InsightsSegmentRunBase": {
      "type": "object",
      "required": [
        "status",
        "request_ref",
        "started_at",
        "finished_at"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "finished"
          ]
        },
        "request_ref": {
          "type": "string",
          "format": "uuid"
        },
        "started_at": {
          "type": "string",
          "format": "date-time",
          "description": "Run creation time, with millisecond precision"
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Calculation completion time, or null while pending"
        }
      }
    }
  }
}