{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/datascoop-io/json-schema/datascoop-io-query-result-schema.json",
  "title": "QueryResult",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/datascoop-io-openapi.json#/components/schemas/QueryResult",
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string"
    },
    "plan": {
      "type": "string",
      "enum": [
        "free",
        "pro"
      ]
    },
    "importVersion": {
      "type": [
        "string",
        "null"
      ],
      "description": "Opaque source-import identity, stable across deployments."
    },
    "total": {
      "type": "integer",
      "description": "Rows matching the filters"
    },
    "returned": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    },
    "truncated": {
      "type": "boolean",
      "description": "true when fewer rows than total were returned"
    },
    "ignored": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter keys the dataset does not know"
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      }
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "attribution": {
      "type": "string",
      "description": "Keep this with the data"
    },
    "licence": {
      "type": "string"
    },
    "applied_filters": {
      "type": "object",
      "additionalProperties": {
        "type": [
          "string",
          "number",
          "boolean"
        ]
      },
      "description": "Effective dataset predicates after normalisation. Does not include pagination or request options."
    },
    "provenance": {
      "type": "object",
      "properties": {
        "source_urls": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          },
          "description": "Configured publisher references; not retained versions of imported files"
        },
        "licence_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "imported_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Recorded successful DataScoop import time, not a publisher release date or record update time"
        },
        "coverage": {
          "type": "object",
          "properties": {
            "country": {
              "type": "string"
            },
            "region": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "country",
            "region"
          ],
          "description": "Declared dataset geography; not a guarantee of completeness"
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "source_urls",
        "licence_url",
        "imported_at",
        "coverage",
        "notes"
      ]
    },
    "next_step": {
      "type": "object",
      "description": "May offer a CSV or larger paid pages when total exceeds the free per-call cap. Free offset pagination remains available.",
      "properties": {
        "message": {
          "type": "string"
        },
        "buy_export_url": {
          "type": "string",
          "format": "uri"
        },
        "signup_url": {
          "type": "string",
          "format": "uri"
        },
        "pricing_url": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  },
  "required": [
    "dataset",
    "total",
    "returned",
    "truncated",
    "rows",
    "attribution",
    "applied_filters",
    "provenance"
  ]
}