Skip to Content
DocsAckAdvancedJSON Schema Integration

JSON Schema Integration

Your Ack schema already describes your data’s shape — so you can import and export JSON Schema (preserving Draft 2020-12 resources for imported schemas and emitting Draft-7 for native schemas) and reuse it to document an API, drive a form library, or define an LLM tool, all from one source of truth.

Importing published schemas

Use strict Ack.fromJsonSchema() to turn a decoded JSON Schema document (a map or boolean, not a JSON string) into an AckSchema<Object, Object>. The input dialect is draft 2020-12 or Draft-7 (http(s)://json-schema.org/draft-07/schema(#)), including when $schema is absent. Other explicitly declared dialects are rejected.

Only the declared $schema string is checked — a document is never matched against a dialect by shape. Draft-7 documents are evaluated under the same supported subset: tuple-form items (a Draft-7 array) is rejected, and $ref siblings are applied as in draft 2020-12. Draft-4 boolean exclusiveMinimum and exclusiveMaximum values are rejected, and Draft-4 integer rejects 1.0 where this importer accepts it.

import 'package:ack/ack.dart'; final AckSchema<Object, Object> schema = Ack.fromJsonSchema({ 'type': 'object', 'properties': { 'name': {'type': 'string'}, 'age': {'type': 'integer', 'minimum': 0}, }, 'required': ['name'], 'additionalProperties': false, }); final user = schema.parse({'name': 'Ada', 'age': 36}); final exported = schema.toJsonSchema();

The returned abstract AckSchema<Object, Object> composes with native Ack schemas; its runtime implementation is internal. It validates JSON values without injecting defaults or applying coercions. Parsing returns a detached, recursively unmodifiable value. Required means key present, not non-null; an omitted type does not implicitly require an object, string, or array. Integral numbers such as 1.0 match integer, and null array elements are supported.

Design: reuse the existing export boundary

AckSchema.toJsonSchema() remains the export API. Imported schemas participate in the same AckSchema → AckSchemaModel → JSON Schema path as native schemas; the builder bridge delegates to that path too. There is no second public exporter or dependency on a Flutter runtime.

You can import an existing export directly:

final document = Ack.object({'name': Ack.string()}).toJsonSchema(); final AckSchema<Object, Object> schema = Ack.fromJsonSchema(document); final exportedAgain = schema.toJsonSchema();

The source document and executable validator are distinct. Ack.fromJsonSchema() is the single import entry point and always imports strictly. The importer preserves supported JSON validation semantics, not the original Dart declaration: JSON cannot recover codecs, Dart model types, custom callbacks, or refinements that were absent from the export. Exports containing unsupported keywords are rejected.

Importing format

By default, Ack.fromJsonSchema() treats format as an annotation (matching JSON Schema Draft 2020-12’s default Core/Applicator/Validation vocabularies). Pass assertFormats: true (or declare the Draft 2020-12 format-assertion vocabulary in $vocabulary) to enable runtime format assertions for the full Draft 2020-12 format suite (date-time, date, time, duration, email, idn-email, hostname, idn-hostname, ipv4, ipv6, uri, uri-reference, iri, iri-reference, uuid, uri-template, json-pointer, relative-json-pointer, regex) as well as standard numeric format bounds (int32, int64, uint32, uint64, float, double):

final timestamp = Ack.fromJsonSchema( {'type': 'string', 'format': 'date-time'}, assertFormats: true, ); timestamp.parse('2024-02-29T12:34:56.123456789+02:00');

Date-time validation uses RFC 3339 syntax, calendar dates, offsets, and the bundled list of announced positive leap-second dates. The list is updated in Ack releases when IERS announces new leap seconds; validation never fetches data at runtime. Parsing preserves the original string, including its fractional precision and offset. It does not convert it to a Dart DateTime.

Hostname and email domain assertions use the complete IANA IDNA2008 derived-property registry pinned to Unicode 12.0.0, with contextual and Bidi checks using matching Unicode data. Disallowed and unassigned code points, including characters assigned after Unicode 12, are rejected after hostname input mapping. The data is bundled; validation does not fetch it at runtime.

Export retains format in imported schemas. External JSON Schema validators may treat format as an annotation unless configured to assert it.

Supported import subset

AreaKeywords
Schemas and typesBoolean schemas, type (including lists and null)
Equalityenum, const, including nested JSON values and empty enums
Objectsproperties, required, boolean/schema additionalProperties, patternProperties, propertyNames, minProperties, maxProperties, dependentRequired, dependentSchemas, unevaluatedProperties
ArraysSingle-schema items, prefixItems, contains, minContains, maxContains, minItems, maxItems, uniqueItems, unevaluatedItems
StringsminLength, maxLength (Unicode code points), pattern (unanchored ECMA-262 search in Unicode mode)
Numbersminimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf (exact decimal division)
CompositionanyOf, allOf, exclusive oneOf, not, if/then/else; sibling assertions are intersected
References$ref, $id, $anchor, $defs, definitions, $dynamicRef, $dynamicAnchor, bundled offline 2020-12 meta-schemas; local/cross-document JSON Pointers and structural recursion
Annotationstitle, description, default, examples, $comment, readOnly, writeOnly, deprecated, contentEncoding, contentMediaType, contentSchema, x-* vendor extensions
FormatFull Draft 2020-12 format suite and standard numeric formats (int32, int64, uint32, uint64, float, double); asserted when assertFormats: true or $vocabulary enables format-assertion

pattern compiles with ECMA-262’s u flag, as the JSON Schema Test Suite requires and Ajv does by default. . matches one code point, so pattern: "^.$" accepts "😀", and \p{...} is a Unicode property escape. A pattern that is invalid in Unicode mode fails import with an invalid_schema diagnostic. For example, an escaped hyphen outside a character class (^\d{3}\-\d{4}$) is invalid; write the hyphen unescaped.

Ack.string().matches() uses Dart’s default RegExp, without u. A native pattern can match differently after export and import, and a native pattern that is invalid in Unicode mode exports a schema that this importer and Ajv reject.

Both native .multipleOf() and imported multipleOf divide exactly on the decimal digits of the number, as the JSON Schema Test Suite requires, so 0.3 and 0.6 are multiples of 0.1, 1e308 is a multiple of 0.5, and an unrounded binary-float sum such as 0.1 + 0.2 (0.30000000000000004) is not.

Unknown keywords, including non-x-* keywords, are accepted as annotations. An unsupported vocabulary marked as required (true) in $vocabulary fails import with unsupported_vocabulary; unsupported optional vocabularies do not.

References, default Draft 2020-12 export, and Draft-7 lowering

Supply decoded documents by retrieval URI. Relative keys and references resolve against baseUri; nested $id values establish new resource scopes. When no base is provided, the importer uses ack-import:///root.json. The importer never reads files or fetches URLs (standard https://json-schema.org/draft/2020-12/... meta-schemas are bundled offline).

final AckSchema<Object, Object> schema = Ack.fromJsonSchema( {r'$ref': r'types.json#/$defs/message'}, baseUri: Uri.parse('https://example.com/protocol/root.json'), documents: { Uri.parse('types.json'): { r'$defs': { 'message': { 'type': 'object', 'properties': {'text': {'type': 'string'}}, 'required': ['text'], }, }, }, }, );

In Ack 2.0, schema.toJsonSchema() and schema.toSchemaModel() preserve imported Draft 2020-12 resources by default ($defs, $dynamicRef, unevaluatedProperties, prefixItems, etc.). When you need a legacy self-contained Draft-7 document with root-scoped definitions and rewritten references, call schema.toJsonSchemaDraft7() or schema.toSchemaModelDraft7() (which throws UnsupportedError if the imported schema relies on 2020-12-only semantics).

Generating Dart models from .schema.json files

With ack_generator, enable the opt-in ack_generator:ack_json_schema builder in build.yaml to compile any lib/**/*.schema.json Draft 2020-12 asset into Dart models:

targets: $default: builders: ack_generator:ack_json_schema: enabled: true generate_for: - lib/**/*.schema.json options: assert_formats: false

ack_generator:ack_json_schema emits <name>.schema.dart (declaring part '<name>.schema.g.dart';), which ack_generator:ack_generator compiles in the same dart run build_runner build pass:

import 'person.schema.dart'; final person = Person.parse({'name': 'Ada', 'age': 36}); print(person.name); // String print(person.toJson()); // {'name': 'Ada', 'age': 36}
  • Typed @Schemable() models are emitted for named non-null objects, $ref definitions, inline objects, string-keyed maps, arrays with non-null items, primitives/bounds, string enums, and simple field unions.
  • Validated value models (wrapping Ack.fromJsonSchema(...)) are emitted automatically for shapes that Dart classes cannot represent faithfully without changing validation semantics (such as regex pattern assertions, named scalar unions, recursive/dynamic $dynamicRef references, oneOf/allOf/not composition, multipleOf, unevaluatedProperties, or assert_formats: true).
  • For programmatic code generation outside build_runner, call generateAckSchemaLibrary() from package:ack_generator/ack_generator.dart.

Validation errors

When a value fails a keyword of an imported schema, the error is a JsonSchemaValidationError. It names the failing keyword and locates it in the source schema, so callers do not parse the message:

final schema = Ack.fromJsonSchema({ 'properties': { 'tags': { 'items': {'enum': ['x', 'y']}, }, }, }); final error = schema.safeParse({'tags': ['x', 'z']}).getError(); if (error is JsonSchemaValidationError) { print(error.keyword); // enum print(error.documentUri); // ack-import:///root.json print(error.pointer); // #/properties/tags/items/enum print(error.keywordLocation); // /properties/tags/items/enum print(error.path); // #/tags/1 }

documentUri and pointer follow $ref into the referenced document, and use the same form as JsonSchemaImportDiagnostic. The pointer starts at the document root, also inside a subschema that declares its own $id. keyword is empty when the failing subschema is false. Only the first failure is reported. A root null that the source schema rejects returns the standard SchemaConstraintsError for a missing value, as other non-nullable Ack schemas do.

keywordLocation is the evaluation path from the root schema to the failing keyword. It includes each $ref it passed through, so two applicators that share a definition report different locations, while their pointer is the same. It uses the plain JSON Pointer form of the Draft 2020-12 keywordLocation output field, with no # and no percent-encoding. It is empty when the root schema is false.

Importing json_schema_builder models

The existing bridge works in both directions:

import 'package:ack/ack.dart'; import 'package:ack_json_schema_builder/ack_json_schema_builder.dart'; import 'package:json_schema_builder/json_schema_builder.dart' as jsb; final AckSchema<Object, Object> ackSchema = jsb.Schema.string(minLength: 2).toAckSchema(); final builderSchema = ackSchema.toJsonSchemaBuilder();

toAckSchema({baseUri, documents, assertFormats}) returns the validator directly and accepts Map<Uri, jsb.Schema> bundles. toJsonSchemaBuilder() preserves imported Draft 2020-12 resources by default; use toJsonSchemaBuilderDraft7() when Draft-7 lowering is required.

A2UI compatibility and verification

Offline regression fixtures pin five representative A2UI v0.9 protocol schemas to upstream commit f5e945a93da36a5d126228f2ad6fbe68809ef8f7. All five A2UI v0.9 schemas (including the basic catalog with unevaluatedProperties, conditionals, and meta-schema references) import and validate cleanly in Ack 2.0, and the full upstream JSON Schema Draft 2020-12 test suite passes offline.

Generating JSON schemas

Call toJsonSchema() on any AckSchema instance. This is the same generic Draft-7 renderer used by schema.toSchemaModel().toJsonSchema().

import 'dart:convert'; import 'package:ack/ack.dart'; enum UserRole { admin, user, guest } final userSchema = Ack.object({ 'id': Ack.integer().positive().describe('Unique user identifier'), 'name': Ack.string() .minLength(2) .maxLength(50) .describe("User's full name"), 'email': Ack.string().email().describe("User's email address"), 'role': Ack.enumValues(UserRole.values).withDefault(UserRole.user), 'isActive': Ack.boolean().withDefault(true), 'tags': Ack.list(Ack.string()).unique().describe('List of user tags').nullable(), 'age': Ack.integer().min(0).max(120).nullable().describe("User's age"), }).describe('Represents a user in the system'); void main() { // Convert the AckSchema to a JSON Schema Object Map final jsonSchemaMap = userSchema.toJsonSchema(); // Pretty print the JSON representation of the JSON Schema final jsonEncoder = JsonEncoder.withIndent(' '); print(jsonEncoder.convert(jsonSchemaMap)); }

Building an adapter package? Most users only need toJsonSchema() (above). To convert Ack schemas to another target format, render from schema.toSchemaModel() (the canonical AckSchemaModel) rather than the JSON Schema map. Start with the adapter quickstart, then use the complete adapter authoring guide for architecture and testing guidance.

Adapter model

Use toSchemaModel() for a reusable, target-independent view of an Ack schema:

final model = userSchema.toSchemaModel(); final jsonSchemaMap = model.toJsonSchema(); for (final warning in model.warnings) { print('${warning.code}: ${warning.message}'); }

AckSchemaModel describes the boundary values a schema accepts and exports, keeping adapter metadata such as property ordering and discriminator info. Its JSON Schema renderer emits only generic Draft-7-compatible output; provider-specific hints belong in adapter renderers.

Output JSON (JSON Schema Object):

{ "type": "object", "description": "Represents a user in the system", "properties": { "id": { "type": "integer", "description": "Unique user identifier", "exclusiveMinimum": 0 }, "name": { "type": "string", "description": "User's full name", "minLength": 2, "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "role": { "type": "string", "enum": [ "admin", "user", "guest" ], "default": "user" }, "isActive": { "type": "boolean", "default": true }, "tags": { "anyOf": [ { "type": "array", "description": "List of user tags", "items": { "type": "string" }, "uniqueItems": true }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "integer", "description": "User's age", "minimum": 0, "maximum": 120 }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "isActive", "tags", "age" ], "additionalProperties": false }

How constraints map to JSON Schema

Ack maps its built-in constraints to corresponding JSON Schema keywords:

Ack Constraint or SchemaJSON Schema KeywordNotes
minLength(n)minLength: nString
maxLength(n)maxLength: nString
matches(p)pattern: pString
email()format: emailString
date()format: dateString
datetime()format: date-timeString
time()format: timeString
uri()format: uriString
uuid()format: uuidString
ipv4()format: ipv4String
ipv6()format: ipv6String
Ack.enumString([...])enum: [...]String
min(n)minimum: nNumber
max(n)maximum: nNumber
greaterThan(n)exclusiveMinimum: nNumber (exclusive)
lessThan(n)exclusiveMaximum: nNumber (exclusive)
multipleOf(n)multipleOf: nNumber
minLength(n)minItems: nList (array)
maxLength(n)maxItems: nList (array)
unique()uniqueItems: trueList (array)
nullable()anyOf: [<schema>, {type: null}]Any schema
withDefault(v)default: vJSON/export-safe defaults only in AckSchemaModel; unsupported defaults are omitted with a warning
describe(d)description: dAny schema
Ack.integer()type: integerType
Ack.double()type: numberType
Ack.string()type: stringType
Ack.boolean()type: booleanType
Ack.list(...)type: array, items: {...}Type
Ack.object(...)type: object, properties: {...}, required: [...]Type
Ack.lazy(...)definitions, $refRecursive type

Shape stability notes

toJsonSchema() renders generic Draft-7 JSON Schema with stable nullability rules:

  • Primitive/object/list/enum schemas marked with .nullable() are emitted as:
    • anyOf: [<base-schema>, { "type": "null" }]
  • Ack.anyOf([...]).nullable() is emitted as anyOf: [{ "anyOf": [...] }, { "type": "null" }]
  • Ack.discriminated(...) is emitted as anyOf with effective object branches. Each branch contains the exact required discriminator const.
  • Ack.discriminated(...).nullable() wraps that anyOf union with a second { "type": "null" } branch.
  • Ack.lazy(name, ...) is emitted as a Draft-7 definitions entry and local $ref values such as { "$ref": "#/definitions/Category" }.
  • Non-null lazy refs that carry metadata such as description use allOf around the $ref so Draft-7 validators do not ignore that metadata as a $ref sibling. Nullable lazy refs keep metadata beside the top-level anyOf.

This means nullable enums are represented as:

{ "anyOf": [ { "type": "string", "enum": ["admin", "user", "guest"] }, { "type": "null" } ] }

And nullable discriminated unions are represented as:

{ "anyOf": [ { "anyOf": [/* effective discriminated object branches */] }, { "type": "null" } ] }

If you build consumers that inspect generated schemas, treat nullability and union composition as separate concerns and don’t assume enum values always live at the top level.

The nested nullable-union shape is intentional for generic Draft-7 output and matches Zod v4’s toJSONSchema() renderer. Don’t flatten it in AckSchema.toJsonSchema(); provider-specific adapters that need a different shape should implement explicit adapter rendering.

Limitations:

  • Custom Constraints: Constraint<T> + Validator<T> instances added via .constrain() are not translated to JSON Schema because there is no standard way to represent arbitrary logic.
  • additionalProperties: Ack.object(..., additionalProperties: false) becomes additionalProperties: false; additionalProperties: true is emitted as the boolean true.
  • Ack.map(valueSchema): Exported as {"type": "object", "additionalProperties": <value schema>}. Map keys are always strings, so no propertyNames keyword is emitted.
  • Ack.any(): Runtime validation accepts non-null JSON-safe values. JSON-like adapter exports represent those JSON-compatible values and attach an ack_any_json_boundary warning to the AckSchemaModel.
  • Ack.lazy() runtime checks: Recursive structure is exported with Draft-7 definitions / $ref. Constraints and refinements added directly to the lazy reference are runtime-only and are reported as schema-model warnings rather than emitted beside $ref.
  • Date/time range constraints: Draft-7 has no standard formatMinimum or formatMaximum keywords. ACK validates .min() and .max() at runtime and records schema-model warnings instead of rendering non-standard keywords.
  • List item nullability: Ack.list(...) does not support nullable item schemas yet. Make the list itself nullable with Ack.list(item).nullable() when the whole field may be null.
  • Discriminated branches: Ack.discriminated(...) owns the discriminator. Branches may omit the discriminator field; compatible Ack.literal(...) or Ack.enumString(...) fields are accepted; generated branches expose the exact branch value as const.

Integrating into API documentation

Use the generated JSON Schema map within a larger API documentation structure.

// Assume you have a function to build the full API spec Map<String, dynamic> buildApiSpecification() { final userJsonSchema = userSchema.toJsonSchema(); return { 'schemas': { 'User': userJsonSchema }, 'endpoints': { '/users': { 'post': { 'summary': 'Create a new user', 'requestBody': { 'required': true, 'content': { 'application/json': { // Reference the generated schema 'schema': { '\$ref': '#/schemas/User' } } } } } } } }; } // Usage final fullApiSpec = buildApiSpecification(); print(JsonEncoder.withIndent(' ').convert(fullApiSpec));

This keeps your validation logic and API documentation in one place.

Advanced JSON Schema features

Schema descriptions and metadata

Add descriptions and metadata to your schemas for better documentation:

final userSchema = Ack.object({ 'id': Ack.string().uuid().describe('Unique user identifier'), 'name': Ack.string().minLength(1).describe('User\'s full name'), 'email': Ack.string().email().describe('User\'s email address'), 'age': Ack.integer().min(0).max(150).describe('User\'s age in years').optional(), }).describe('Represents a user in the system'); final jsonSchema = userSchema.toJsonSchema(); // Output includes description fields

Default values in JSON Schema

Schemas with default values include them in the generated JSON Schema:

enum Theme { light, dark } final configSchema = Ack.object({ 'theme': Ack.enumValues(Theme.values).withDefault(Theme.light), 'notifications': Ack.boolean().withDefault(true), 'maxItems': Ack.integer().min(1).max(100).withDefault(10), }); final jsonSchema = configSchema.toJsonSchema(); // Output includes "default" properties

Complex schema patterns

JSON Schema generation works with all Ack schema types:

// Union types final mixedValueSchema = Ack.anyOf([ Ack.string(), Ack.integer(), Ack.boolean(), ]); // Discriminated unions final shapeSchema = Ack.discriminated( discriminatorKey: 'type', schemas: { 'circle': Ack.object({ 'radius': Ack.double().positive(), }), 'rectangle': Ack.object({ 'width': Ack.double().positive(), 'height': Ack.double().positive(), }), }, ); // Nested arrays and objects final complexSchema = Ack.object({ 'users': Ack.list(userSchema).minLength(1), 'metadata': Ack.object({ 'version': Ack.string(), 'tags': Ack.list(Ack.string()).unique(), }).optional(), }); // All produce valid JSON Schema final mixedJson = mixedValueSchema.toJsonSchema(); final shapeJson = shapeSchema.toJsonSchema(); final complexJson = complexSchema.toJsonSchema();
Last updated on