DevToolbox

URI and URL Format Validation in JSON Schema

Validate URIs and URLs in JSON Schema using format keywords. Learn the difference between uri, uri-reference, iri, and how to enforce HTTPS schemes.

String Constraints

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "homepage": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://"
    },
    "profileImage": {
      "type": "string",
      "format": "uri"
    },
    "callbackPath": {
      "type": "string",
      "format": "uri-reference"
    }
  },
  "required": ["homepage"]
}

Test Data

{
  "homepage": "https://example.com/about",
  "profileImage": "https://cdn.example.com/images/avatar.png",
  "callbackPath": "/api/callback?code=abc123"
}

Detailed Explanation

URI Validation in JSON Schema

JSON Schema provides several format keywords for validating Uniform Resource Identifiers (URIs). Understanding the differences between them is essential for building correct API schemas.

URI Format Keywords

Format Accepts Example
uri Absolute URI (with scheme) https://example.com/path
uri-reference URI or relative reference /api/callback, https://x.com
iri Internationalized URI https://例え.jp/パス
iri-reference IRI or relative reference /données/résultat

Key Differences

  • uri requires a scheme (https:, ftp:, etc.) — relative paths like /about are invalid.
  • uri-reference accepts both absolute URIs and relative references — it is more permissive.
  • iri and iri-reference extend their counterparts to allow non-ASCII Unicode characters in the path and query.

How the Example Schema Works

The schema models a user profile with three URL-like fields:

  1. homepage must be an absolute URI starting with http:// or https://. The format: "uri" keyword validates the URI structure, and the pattern keyword further restricts the scheme to HTTP or HTTPS.
  2. profileImage must be an absolute URI. Any scheme is accepted by default.
  3. callbackPath uses format: "uri-reference", so it accepts both absolute URIs and relative paths like "/api/callback?code=abc123".

Enforcing HTTPS

The uri format alone accepts any scheme, including ftp:, mailto:, and file:. To restrict to web URLs, combine format with a pattern:

{
  "type": "string",
  "format": "uri",
  "pattern": "^https://"
}

This ensures only HTTPS URLs pass validation — critical for security-sensitive fields like webhook endpoints and OAuth callback URLs.

Practical Considerations

  • Trailing slashes: Both https://example.com and https://example.com/ are valid URIs. If your application treats them differently, add normalization logic outside the schema.
  • Query strings and fragments: URIs may include query parameters (?key=value) and fragments (#section). The uri format validates the overall structure but does not constrain individual query parameters.
  • Encoding: Spaces and special characters must be percent-encoded (%20). Most validators reject unencoded spaces in URIs.

Use Case

Use URI validation for webhook registration endpoints, OAuth callback URLs, social profile links, image URLs in CMS APIs, and any field that must contain a valid web address. Combine with a pattern constraint to enforce HTTPS-only for security-sensitive applications.

Try It — JSON Schema Validator

Open full tool →

Related Topics

Email Format Validation with JSON Schema

String Constraints

Date and Date-Time Format Validation in JSON Schema

String Constraints

String Type Validation with JSON Schema

Basic Types

Pattern Validation with Regular Expressions in JSON Schema

String Constraints

Required Properties Validation in JSON Schema

Object Constraints