SearchResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foretak-dev/json-schema/foretak-dev-search-result-schema.json",
  "title": "SearchResult",
  "description": "Envelope returned by ``search`` — hits plus what the agent needs next.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foretak-dev-openapi.yml#/components/schemas/SearchResult",
  "properties": {
    "country": {
      "type": "string",
      "title": "Country",
      "description": "ISO-3166-1 alpha-2, upper-case."
    },
    "registry": {
      "type": "string",
      "title": "Registry",
      "description": "Registry slug."
    },
    "query": {
      "type": "string",
      "title": "Query",
      "description": "The name that was searched for."
    },
    "hits": {
      "items": {
        "$ref": "#/$defs/SearchHit"
      },
      "type": "array",
      "title": "Hits",
      "description": "Best matches, best first: always sorted by `confidence` descending. Hits that score equally keep the order the upstream register returned them in."
    },
    "total": {
      "type": "integer",
      "minimum": 0.0,
      "title": "Total",
      "description": "Total matches upstream, which may exceed len(hits).",
      "default": 0
    },
    "truncated": {
      "type": "boolean",
      "title": "Truncated",
      "description": "True when `total` exceeds the returned hits.",
      "default": false
    },
    "cached": {
      "type": "boolean",
      "title": "Cached",
      "description": "Served from cache.",
      "default": false
    },
    "fetched_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Fetched At",
      "description": "UTC timestamp of the fetch."
    },
    "hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hint",
      "description": "What to do next, e.g. 'call lookup_company with the id of the right hit'."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "country",
    "registry",
    "query"
  ],
  "$defs": {
    "CompanyStatus": {
      "type": "string",
      "enum": [
        "active",
        "under_liquidation",
        "under_compulsory_liquidation",
        "bankrupt",
        "dissolved",
        "deleted",
        "unknown"
      ],
      "title": "CompanyStatus",
      "description": "Normalised lifecycle status of a registered entity.\n\nThe mapping from national flags to these values is the registry module's\njob; the values themselves are country-neutral so an agent can branch on\nthem without knowing which country it is looking at.\n\nPrecedence when several national flags are true is defined per registry\n(for Norway: ``deleted`` > ``bankrupt`` > ``under_compulsory_liquidation``\n> ``under_liquidation`` > ``active``)."
    },
    "SearchHit": {
      "properties": {
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO-3166-1 alpha-2, upper-case."
        },
        "registry": {
          "type": "string",
          "title": "Registry",
          "description": "Registry slug."
        },
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Canonical national identifier — feed this to lookup."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Registered name."
        },
        "legal_form_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Legal Form Code",
          "description": "National legal-form code."
        },
        "legal_form": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Legal Form",
          "description": "English legal-form label."
        },
        "status": {
          "$ref": "#/$defs/CompanyStatus",
          "description": "Normalised lifecycle status.",
          "default": "unknown"
        },
        "city": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "City",
          "description": "Post town of the business address."
        },
        "municipality": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Municipality",
          "description": "Municipality of the business address."
        },
        "registered_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Registered At",
          "description": "Date entered in the register."
        },
        "is_subunit": {
          "type": "boolean",
          "title": "Is Subunit",
          "description": "True for branches / sub-units.",
          "default": false
        },
        "confidence": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Confidence",
          "description": "Match confidence for this hit (D-005).",
          "default": 0.5
        },
        "confidence_basis": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Confidence Basis",
          "description": "Why that confidence."
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url",
          "description": "Upstream record URL."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "country",
        "registry",
        "id",
        "name"
      ],
      "title": "SearchHit",
      "description": "One candidate from a name search.\n\nDeliberately thin: enough for an agent to pick the right entity and then\ncall ``lookup_company`` with ``id`` for the full report."
    }
  }
}