# JSON Schema validation fails: format 'iri-reference' is not recognized

- **ID:** `data/json-schema-format-iri-reference`
- **Domain:** data
- **Category:** schema_error
- **Error Code:** `JsonSchemaFormatValidationError`
- **Verification:** ai_generated
- **Fix Rate:** 82%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| JSON Schema 2020-12 | active | — | — |
| ajv 8.12+ | active | — | — |
| jsonschema 4.20+ | active | — | — |
| OpenAPI 3.1 | active | — | — |

## Workarounds

1. **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']);`** (90% success)
   ```
   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']);`
   ```
2. **Replace 'iri-reference' with a custom regex pattern in the schema: `"pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*:.*$"` to approximate IRI-reference validation.** (75% success)
   ```
   Replace 'iri-reference' with a custom regex pattern in the schema: `"pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*:.*$"` to approximate IRI-reference validation.
   ```
3. **Use a validator that natively supports 'iri-reference', such as `@cfworker/json-schema` version 2.0+ or `jsonschema` with the `rfc3987` package installed.** (80% success)
   ```
   Use a validator that natively supports 'iri-reference', such as `@cfworker/json-schema` version 2.0+ or `jsonschema` with the `rfc3987` package installed.
   ```

## Dead Ends

- **** — This bypasses validation for all formats, potentially allowing invalid data that should be caught by other format checks. (60% fail)
- **** — 'iri-reference' allows relative IRIs and fragment-only IRIs, which 'uri' does not. This will reject valid data. (85% fail)
- **** — Format validation is often disabled by default; upgrading alone does not enable it. (70% fail)