{
  "id": "data/json-schema-format-iri-reference",
  "signature": "JSON Schema validation fails: format 'iri-reference' is not recognized",
  "signature_zh": "JSON Schema验证失败：格式 'iri-reference' 未被识别",
  "regex": "format.*iri-reference.*not recognized|format.*iri-reference.*not supported",
  "domain": "data",
  "category": "schema_error",
  "subcategory": null,
  "root_cause": "The JSON Schema specification defines 'iri-reference' as a format that requires opt-in validation; many validators (e.g., older versions of ajv or jsonschema) do not support it by default.",
  "root_cause_type": "generic",
  "root_cause_zh": "JSON Schema规范将 'iri-reference' 定义为需要选择性加入验证的格式；许多验证器（如旧版ajv或jsonschema）默认不支持它。",
  "versions": [
    {
      "version": "JSON Schema 2020-12",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "ajv 8.12+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "jsonschema 4.20+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "OpenAPI 3.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "This bypasses validation for all formats, potentially allowing invalid data that should be caught by other format checks.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "'iri-reference' allows relative IRIs and fragment-only IRIs, which 'uri' does not. This will reject valid data.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Format validation is often disabled by default; upgrading alone does not enable it.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Enable format validation explicitly in the validator. For ajv: `const ajv = new Ajv({ formats: { 'iri-reference': true } });` or use `ajv-formats` plugin: `import addFormats from 'ajv-formats'; addFormats(ajv, ['iri-reference']);`",
      "success_rate": 0.9,
      "how": "Enable format validation explicitly in the validator. For ajv: `const ajv = new Ajv({ formats: { 'iri-reference': true } });` or use `ajv-formats` plugin: `import addFormats from 'ajv-formats'; addFormats(ajv, ['iri-reference']);`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Replace 'iri-reference' with a custom regex pattern in the schema: `\"pattern\": \"^[a-zA-Z][a-zA-Z0-9+.-]*:.*$\"` to approximate IRI-reference validation.",
      "success_rate": 0.75,
      "how": "Replace 'iri-reference' with a custom regex pattern in the schema: `\"pattern\": \"^[a-zA-Z][a-zA-Z0-9+.-]*:.*$\"` to approximate IRI-reference validation.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a validator that natively supports 'iri-reference', such as `@cfworker/json-schema` version 2.0+ or `jsonschema` with the `rfc3987` package installed.",
      "success_rate": 0.8,
      "how": "Use a validator that natively supports 'iri-reference', such as `@cfworker/json-schema` version 2.0+ or `jsonschema` with the `rfc3987` package installed.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在验证器中显式启用格式验证。对于ajv：`const ajv = new Ajv({ formats: { 'iri-reference': true } });` 或使用`ajv-formats`插件：`import addFormats from 'ajv-formats'; addFormats(ajv, ['iri-reference']);`",
    "在模式中将'iri-reference'替换为自定义正则表达式模式：`\"pattern\": \"^[a-zA-Z][a-zA-Z0-9+.-]*:.*$\"` 以近似IRI-reference验证。",
    "使用原生支持'iri-reference'的验证器，例如`@cfworker/json-schema` 2.0+版本或安装了`rfc3987`包的`jsonschema`。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://json-schema.org/understanding-json-schema/reference/string.html#format",
  "official_doc_section": null,
  "error_code": "JsonSchemaFormatValidationError",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-11-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}