CountriesResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foretak-dev/json-schema/foretak-dev-countries-response-schema.json",
  "title": "CountriesResponse",
  "description": "The answer to \"which countries can you answer for?\".\n\nThe only shape the discovery operation returns, on both surfaces\n(``DECISIONS.md`` D-012): REST ``GET /v1/countries`` and the MCP tool\n``list_countries``. Before D-012 each surface re-derived this envelope from\n``Registry.describe()`` on its own, which is how the two could have drifted\n— REST validated the dict through a private model that silently *dropped* an\nunrecognised key while MCP passed the raw dict through and *kept* it.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foretak-dev-openapi.yml#/components/schemas/CountriesResponse",
  "properties": {
    "countries": {
      "items": {
        "$ref": "#/$defs/CountryInfo"
      },
      "type": "array",
      "title": "Countries",
      "description": "One row per registry that can answer right now, sorted by country code."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "$defs": {
    "CountryInfo": {
      "properties": {
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO-3166-1 alpha-2, upper-case, e.g. 'NO'."
        },
        "registry": {
          "type": "string",
          "title": "Registry",
          "description": "Registry slug, e.g. 'brreg'."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Human-readable register name."
        },
        "id_scheme": {
          "type": "string",
          "title": "Id Scheme",
          "description": "What the national identifier is called locally, e.g. 'organisasjonsnummer'."
        },
        "id_example": {
          "type": "string",
          "title": "Id Example",
          "description": "A real, valid identifier the caller can use to smoke-test the service."
        },
        "id_description": {
          "type": "string",
          "title": "Id Description",
          "description": "One sentence describing the identifier's format."
        },
        "source_url": {
          "type": "string",
          "title": "Source Url",
          "description": "Base URL of the upstream registry API, for citation."
        },
        "license": {
          "type": "string",
          "title": "License",
          "description": "Licence of the upstream data, e.g. 'NLOD 2.0'."
        },
        "is_stub": {
          "type": "boolean",
          "title": "Is Stub",
          "description": "True for example/template modules, which are hidden from the public list unless stubs are explicitly requested.",
          "default": false
        },
        "requires_api_key": {
          "type": "boolean",
          "title": "Requires Api Key",
          "description": "True when this registry's upstream API needs a credential the operator must supply. A self-hosted deployment that has not set it gets upstream_error on every call to this country (DECISIONS.md D-017).",
          "default": false
        },
        "api_key_env": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Api Key Env",
          "description": "Name of the environment variable holding that credential, e.g. 'COMPANIES_HOUSE_API_KEY'. None when no key is needed. Never the key itself."
        },
        "supported_includes": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Supported Includes",
          "description": "Attachment names this registry declares — the closed set of valid values for `include=[…]` on `lookup_company`, sorted. Empty when this registry offers no attachments today. Lets an agent discover what more it can ask for before it asks (DECISIONS.md D-042(d)); an `include` value outside this list raises `bad_request` naming this same set, never a silently empty block."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "country",
        "registry",
        "name",
        "id_scheme",
        "id_example",
        "id_description",
        "source_url",
        "license"
      ],
      "title": "CountryInfo",
      "description": "One supported country/registry pair, as returned by the discovery operation.\n\nBuilt by ``Registry.country_info()`` from the class attributes of a\n:class:`~registry_mcp.core.registry.Registry` subclass — the same nine\nvalues ``Registry.describe()`` has always emitted, now with a type\n(``DECISIONS.md`` D-012).\n\nThis is the country-neutral half of the contract even though its *values*\nname a country: it carries no report data, so unlike every other returned\nmodel it is a row *about* a registry rather than a document *from* one."
    }
  }
}