{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/stat-fi/json-schema/stat-fi-search-response-schema.json",
  "title": "SearchResponse",
  "description": "Response envelope for metadata search results, including query echo and paging information.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stat-fi-pxapi-beta-openapi.yml#/components/schemas/SearchResponse",
  "required": [
    "pagingInfo",
    "query",
    "results"
  ],
  "type": "object",
  "properties": {
    "query": {
      "$ref": "#/$defs/SearchQueryInfo"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchResultItem"
      },
      "description": "The search result items matching the query."
    },
    "pagingInfo": {
      "$ref": "#/$defs/PagingInfo"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "DimensionInfo": {
      "required": [
        "name",
        "size"
      ],
      "type": "object",
      "properties": {
        "name": {
          "minLength": 1,
          "type": "string",
          "description": "Localized display name of the dimension."
        },
        "size": {
          "type": "integer",
          "description": "Number of values in the dimension.",
          "format": "int32"
        }
      },
      "additionalProperties": false,
      "description": "Represents summary information about a dimension: its name and the number of values it contains."
    },
    "Link": {
      "required": [
        "href",
        "method",
        "rel"
      ],
      "type": "object",
      "properties": {
        "href": {
          "minLength": 1,
          "type": "string",
          "description": "Absolute or relative URI of the target resource."
        },
        "rel": {
          "minLength": 1,
          "type": "string",
          "description": "Relation type describing how the target resource relates to the current resource (e.g., self, data, metadata)."
        },
        "method": {
          "minLength": 1,
          "type": "string",
          "description": "HTTP method to use when following the link (e.g., GET, POST)."
        }
      },
      "additionalProperties": false,
      "description": "Represents a link to a related resource (HATEOAS)."
    },
    "MatchInfo": {
      "required": [
        "matchedText",
        "matchType",
        "path"
      ],
      "type": "object",
      "properties": {
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Machine-friendly identifier of the matched field (e.g. \"table.name\", \"dimension.unit.label\")."
        },
        "matchType": {
          "$ref": "#/$defs/MatchType"
        },
        "matchedText": {
          "type": [
            "string",
            "null"
          ],
          "description": "The text that matched the search query."
        }
      },
      "additionalProperties": false,
      "description": "Describes where and how a search hit occurred within a result."
    },
    "MatchType": {
      "enum": [
        "Contains",
        "Exact"
      ],
      "type": "string",
      "description": "Describes how the search query matched the target text."
    },
    "MetricInfo": {
      "required": [
        "name",
        "unit"
      ],
      "type": "object",
      "properties": {
        "name": {
          "minLength": 1,
          "type": "string",
          "description": "Localized name of the metric (e.g., \"Population\", \"GDP\")."
        },
        "unit": {
          "minLength": 1,
          "type": "string",
          "description": "Localized unit of measurement (e.g., \"persons\", \"EUR\")."
        }
      },
      "additionalProperties": false,
      "description": "Represents a metric with its name and unit of measurement."
    },
    "PagingInfo": {
      "required": [
        "currentPage",
        "pageSize",
        "totalItems"
      ],
      "type": "object",
      "properties": {
        "currentPage": {
          "maximum": 2147483647,
          "minimum": 1,
          "type": "integer",
          "description": "The current page number, starting from 1.",
          "format": "int32"
        },
        "pageSize": {
          "maximum": 100,
          "minimum": 1,
          "type": "integer",
          "description": "The number of items per page.",
          "format": "int32"
        },
        "totalItems": {
          "maximum": 2147483647,
          "minimum": 0,
          "type": "integer",
          "description": "The total number of items that can be paged through.",
          "format": "int32"
        }
      },
      "additionalProperties": false,
      "description": "Represents paging information for a list of items."
    },
    "SearchDatabaseRef": {
      "required": [
        "id",
        "name"
      ],
      "type": "object",
      "properties": {
        "id": {
          "minLength": 1,
          "type": "string",
          "description": "Unique identifier of the database."
        },
        "name": {
          "minLength": 1,
          "type": "string",
          "description": "Display name of the database."
        }
      },
      "additionalProperties": false,
      "description": "Reference to a database returned with a search result."
    },
    "SearchQueryInfo": {
      "required": [
        "lang",
        "q",
        "target"
      ],
      "type": "object",
      "properties": {
        "q": {
          "minLength": 1,
          "type": "string",
          "description": "The search query string that was used."
        },
        "target": {
          "$ref": "#/$defs/SearchTarget"
        },
        "lang": {
          "minLength": 1,
          "type": "string",
          "description": "The language code that was used for the search."
        }
      },
      "additionalProperties": false,
      "description": "Echo of the effective query parameters used for the search request."
    },
    "SearchResultItem": {
      "required": [
        "database",
        "table"
      ],
      "type": "object",
      "properties": {
        "score": {
          "type": [
            "number",
            "null"
          ],
          "description": "Optional numeric relevance score used for ordering results.",
          "format": "double"
        },
        "database": {
          "$ref": "#/$defs/SearchDatabaseRef"
        },
        "table": {
          "$ref": "#/$defs/TableSummary"
        },
        "matches": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/MatchInfo"
          },
          "description": "Describes where and how the search hit occurred."
        },
        "links": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/Link"
          },
          "description": "HATEOAS-style links to related resources."
        }
      },
      "additionalProperties": false,
      "description": "A single search result representing a table. Each table appears at most once."
    },
    "SearchTarget": {
      "enum": [
        "Content",
        "Dimension",
        "Value",
        "Geo",
        "All"
      ],
      "type": "string",
      "description": "Specifies which fields the search engine should match against."
    },
    "TableSummary": {
      "required": [
        "dimensions",
        "lastUpdated",
        "metrics",
        "tableId",
        "timeRange",
        "title"
      ],
      "type": "object",
      "properties": {
        "tableId": {
          "minLength": 1,
          "type": "string",
          "description": "Unique identifier for the table (e.g., TABLEID from PX metadata)."
        },
        "title": {
          "minLength": 1,
          "type": "string",
          "description": "Localized display title of the table."
        },
        "metrics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MetricInfo"
          },
          "description": "Metric names and their units of measurement."
        },
        "timeRange": {
          "$ref": "#/$defs/TimeRange"
        },
        "dimensions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DimensionInfo"
          },
          "description": "Names and sizes of all dimensions, excluding the metric and time dimensions."
        },
        "lastUpdated": {
          "type": "string",
          "description": "Last update timestamp (UTC) derived from the metric values.",
          "format": "date-time"
        }
      },
      "additionalProperties": false,
      "description": "Contains essential summary information about a statistical table, including\r\nits identification, metrics, time range, dimensions, and update timestamp."
    },
    "TimeRange": {
      "required": [
        "from",
        "to"
      ],
      "type": "object",
      "properties": {
        "from": {
          "minLength": 1,
          "type": "string",
          "description": "Name of the first time period value (e.g., \"2000\")."
        },
        "to": {
          "minLength": 1,
          "type": "string",
          "description": "Name of the last time period value (e.g., \"2024\")."
        }
      },
      "additionalProperties": false,
      "description": "Represents the time range of a table's time dimension."
    }
  }
}