ValidationResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foretak-dev/json-schema/foretak-dev-validation-result-schema.json",
  "title": "ValidationResult",
  "description": "The answer to \"is this identifier well-formed?\" — no network call.\n\nThe only shape the validation operation returns, on both surfaces\n(``DECISIONS.md`` D-010): REST ``GET /v1/{country}/validate/{id}`` and the\nMCP tool ``validate_company_id``.\n\nNote that an invalid identifier is **not** an error here: this operation\nanswers a question, so it returns ``valid=False`` with a ``reason`` and a\n``hint`` rather than raising. That is the one deliberate exception to\n``DECISIONS.md`` D-007's \"every expected failure is a raised\n``RegistryError``\" — and the reason ``hint`` is carried on this model.\n\nBuild it with ``Registry.validate(id)``; do not construct it in a surface.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foretak-dev-openapi.yml#/components/schemas/ValidationResult",
  "properties": {
    "country": {
      "type": "string",
      "title": "Country",
      "description": "ISO-3166-1 alpha-2, upper-case."
    },
    "registry": {
      "type": "string",
      "title": "Registry",
      "description": "Registry slug, e.g. 'brreg'."
    },
    "id_scheme": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Id Scheme",
      "description": "Name of the identifier scheme, e.g. 'organisasjonsnummer'."
    },
    "input": {
      "type": "string",
      "title": "Input",
      "description": "The identifier exactly as the caller supplied it."
    },
    "valid": {
      "type": "boolean",
      "title": "Valid",
      "description": "True when the identifier passes this country's format and checksum."
    },
    "normalized": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Normalized",
      "description": "Canonical form to pass to lookup, e.g. '923609016'. None when invalid."
    },
    "formatted": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Formatted",
      "description": "The identifier as a local would write it, e.g. '923 609 016'. None when invalid."
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reason",
      "description": "One English sentence saying why it is valid, or what failed."
    },
    "hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hint",
      "description": "What to do next when `valid` is false — the same hint the invalid_id error carries. None when valid: the next call is simply lookup."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "country",
    "registry",
    "input",
    "valid"
  ]
}