Swift JSON Schema

Try the live playground · Documentation · Latest release

Quick start

Define a model once, then use its schema to generate JSON Schema, parse valid input, and reject invalid data:

import JSONSchemaBuilder
@Schemable
struct Person {
  @StringOptions(.minLength(1))
  let name: String
@NumberOptions(.minimum(0))
  let age: Int
}
let schema = Person.schema.definition()
print(try schema.jsonValue.serialized(options: .pretty))
let person: Person = try Person.schema.parseAndValidate(
  instance: #"{"name": "Ada", "age": 37}"#
)
print(person.name) // Ada
let result = schema.validate(["name": "Ada", "age": -1])
print(result.isValid) // false

parseAndValidate checks the schema's constraints and returns your Swift type, or throws with parsing and validation details. Use schema.validate when you only need a validation result, without constructing a model. Learn about parsing and validation.

Build schemas directly

Result builders infer their output types from the properties you declare:

let personSchema = JSONObject {
  JSONProperty(key: "name") {
    JSONString().minLength(1)
  }
  .required()
JSONProperty(key: "age") {
    JSONInteger().minimum(0)
  }
  .required()
}
let parsed: (String, Int) = try personSchema.parseAndValidate(
  instance: #"{"name": "Ada", "age": 37}"#
)

The output is a tuple in property declaration order. parseAndValidate returns it directly; parse returns Parsed<(String, Int), ParseIssue>. Add .map(Person.init) to the builder to construct a Person instead.

Builders also support arrays, schema compositions, references, and conditional rules. Explore the DSL.

Validate an existing schema

No Swift model or macro is required when your schema already exists:

import JSONSchema
let externalSchema = try Schema(
  instance: #"{"type": "string", "minLength": 3}"#
)
let validation = try externalSchema.validate(instance: #""hi""#)
print(validation.isValid) // false
let diagnostics = try validation.renderedOutput(level: .basic)
print(try diagnostics.serialized(options: .pretty))

The diagnostics identify the failing keyword and input location. Learn about validation output.

Installation

Add the package in Xcode with File > Add Package Dependencies, or add it to Package.swift:

dependencies: [
  .package(url: "https://github.com/ajevans99/swift-json-schema", from: "0.13.2")
]

from: sets a minimum version and allows compatible updates; it does not pin an exact release. See the latest release for the current version.

Choose the products your target uses. For the quick start:

targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "JSONSchemaBuilder", package: "swift-json-schema")
    ]
  )
]

| Library | Use it for | |---------|------------| | JSONSchema | Loading and validating existing JSON Schema documents, references, formats, and diagnostics. Re-exports OrderedJSON. | | JSONSchemaBuilder | Generating schemas and parsing typed values with result builders and @Schemable. Builds on JSONSchema. | | JSONSchemaConversion | Converting schema-defined strings into UUID, URL, and Date values. Builds on JSONSchemaBuilder. | | OrderedJSON | Order-preserving JSON parsing and serialization, independently of schema validation. |

Requirements: Swift 6.1 or later. Package deployment minimums are macOS 13, iOS 16, Mac Catalyst 16, watchOS 9, tvOS 16, and visionOS 1. Generated schemas and variadic object builders require macOS 14, iOS 17, Mac Catalyst 17, watchOS 10, or tvOS 17 on those platforms. The package also builds on Linux.

Schema-first code generation

Starting with JSON Schema rather than Swift? The companion swift-json-schema-codegen package generates typed builder components from schema documents, completing the other direction: JSON Schema to Swift.

With its separate JSONSchemaCodegen product installed, an inline schema becomes a typed parser:

import JSONSchemaCodegen
@Schema("""
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name", "age"]
}
""")
enum PersonSchema {}
let person = try PersonSchema.schema.parseAndValidate(
  instance: #"{"name": "Ada", "age": 37}"#
)
print(person.name) // Ada

The output fields are inferred from the schema; you do not repeat their Swift types. A CLI and SwiftPM build-tool plugin also generate components from schema files, useful for shared API contracts, configuration formats, and design tokens. See the codegen guide for installation, supported schemas, and file-based workflows.

Explore the capabilities

The guides on Swift Package Index cover the details without requiring you to read generated macro code:

| Guide | What you can do | |-------|-----------------| | Generate schemas from Swift types | Model nested and recursive data, enums, collections, custom coding keys, and nullable properties. | | Build schemas manually | Compose reusable schemas with result builders, references, and dynamic object properties. | | Model conditional rules | Express property dependencies and if/then/else validation. | | Parse into Swift values | Combine parsing and validation, map outputs, and select composition branches. | | Validate existing schemas | Load schema documents, resolve references, and enable built-in or custom formats. | | Inspect validation output | Choose flag, basic, detailed, or verbose diagnostics. | | Convert Foundation types | Parse UUIDs, URLs, and dates using custom property schemas. | | Emit deterministic JSON | Produce reproducible schemas and validation results, and understand the serialization guarantees. |

Ecosystem and integrations

• swift-json-schema-playground (live demo) - an in-browser validation playground running the package as WebAssembly via SwiftWasm.
• swift-mcp-toolkit - strongly typed tools built on the official Model Context Protocol Swift SDK.
• SwiftFunctionToolsExperiment - type-safe OpenAI API function tool calls using schemas built with this library.
• Bowtie - cross-language JSON Schema conformance reports, with a dedicated Swift harness.
• A2UI - agent-generated user interfaces, with Swift core and component-catalog libraries that use this package.

License

Released under the MIT license. See LICENSE for details.