# JSON Schema validation fails with timeout when resolving remote $ref URIs

- **ID:** `data/json-schema-uri-resolution-timeout`
- **Domain:** data
- **Category:** network_error
- **Error Code:** `ValidationError`
- **Verification:** ai_generated
- **Fix Rate:** 92%

## Root Cause

JSON Schema definitions that use external $ref URIs (e.g., https://json-schema.org/draft/2020-12/schema) cause validation to hang or timeout when the remote server is unreachable or slow, especially in offline or restricted network environments.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| ajv 8.12.0 | active | — | — |
| jsonschema 4.20.0 | active | — | — |
| Python 3.12 | active | — | — |
| Node.js 21 | active | — | — |

## Workarounds

1. **Download the remote schema locally and use a local file reference: `curl -o draft-2020-12.json https://json-schema.org/draft/2020-12/schema; then use $ref: './draft-2020-12.json'`** (95% success)
   ```
   Download the remote schema locally and use a local file reference: `curl -o draft-2020-12.json https://json-schema.org/draft/2020-12/schema; then use $ref: './draft-2020-12.json'`
   ```
2. **Use a schema resolver with caching: `from jsonschema import RefResolver; resolver = RefResolver.from_schema(schema, store={'https://json-schema.org/draft/2020-12/schema': cached_schema})`** (90% success)
   ```
   Use a schema resolver with caching: `from jsonschema import RefResolver; resolver = RefResolver.from_schema(schema, store={'https://json-schema.org/draft/2020-12/schema': cached_schema})`
   ```
3. **Set a short timeout for HTTP requests in the validator: `import urllib.request; urllib.request.urlopen(url, timeout=5)`** (85% success)
   ```
   Set a short timeout for HTTP requests in the validator: `import urllib.request; urllib.request.urlopen(url, timeout=5)`
   ```

## Dead Ends

- **** — This only delays the failure; if the remote server is permanently unreachable, the validation will still fail after the increased timeout. (60% fail)
- **** — Most validators have the same behavior; the issue is the network dependency, not the library implementation. (50% fail)
- **** — Retries cannot fix a fundamentally unreachable remote resource; they only add latency and complexity. (70% fail)