Generate JSON Schema from Swift types, validate JSON against Draft 2020-12 schemas, and parse validated input into typed Swift values.
Use the @Schemable macro or a composable result-builder DSL to define your schemas, or load existing schema documents with the standalone validator. The package also provides structured validation diagnostics, Foundation type conversions, and deterministic JSON serialization.
Try the live playground · Documentation · Latest release
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) // falseparseAndValidate 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.
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.
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.
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.
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) // AdaThe 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.
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. |
- 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.
Have a project to share? Open a PR to add it here.
Released under the MIT license. See LICENSE for details.