ValidationError data network_error ai_generated true

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

ID: data/json-schema-uri-resolution-timeout

Also available as: JSON · Markdown · 中文
92%Fix Rate
86%Confidence
1Evidence
2024-03-12First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
ajv 8.12.0 active — — —
jsonschema 4.20.0 active — — —
Python 3.12 active — — —
Node.js 21 active — — —

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.

generic

中文

使用外部$ref URI（例如https://json-schema.org/draft/2020-12/schema）的JSON Schema定义，在远程服务器不可达或响应缓慢时会导致验证挂起或超时，特别是在离线或受限网络环境中。

Official Documentation

https://json-schema.org/understanding-json-schema/structuring.html

Workarounds

  1. 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'` 
    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. 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})` 
    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. 85% success Set a short timeout for HTTP requests in the validator: `import urllib.request; urllib.request.urlopen(url, timeout=5)` 
    Set a short timeout for HTTP requests in the validator: `import urllib.request; urllib.request.urlopen(url, timeout=5)`

中文步骤

  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'`
  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})`
  3. Set a short timeout for HTTP requests in the validator: `import urllib.request; urllib.request.urlopen(url, timeout=5)`

Dead Ends

Common approaches that don't work:

  1. 60% fail

    This only delays the failure; if the remote server is permanently unreachable, the validation will still fail after the increased timeout.

  2. 50% fail

    Most validators have the same behavior; the issue is the network dependency, not the library implementation.

  3. 70% fail

    Retries cannot fix a fundamentally unreachable remote resource; they only add latency and complexity.