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
| Area | Keywords |
|---|---|
| Schemas and types | Boolean schemas, type (including lists and null) |
| Equality | enum, const, including nested JSON values and empty enums |
| Objects | properties, required, boolean/schema additionalProperties, patternProperties, propertyNames, minProperties, maxProperties, dependentRequired, dependentSchemas, unevaluatedProperties |
| Arrays | Single-schema items, prefixItems, contains, minContains, maxContains, minItems, maxItems, uniqueItems, unevaluatedItems |
| Strings | minLength, maxLength (Unicode code points), pattern (unanchored ECMA-262 search in Unicode mode) |
| Numbers | minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf (exact decimal division) |
| Composition | anyOf, 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 |
| Annotations | title, description, default, examples, $comment, readOnly, writeOnly, deprecated, contentEncoding, contentMediaType, contentSchema, x-* vendor extensions |
| Format | Full 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: falseack_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,$refdefinitions, 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 regexpatternassertions, named scalar unions, recursive/dynamic$dynamicRefreferences,oneOf/allOf/notcomposition,multipleOf,unevaluatedProperties, orassert_formats: true). - For programmatic code generation outside
build_runner, callgenerateAckSchemaLibrary()frompackage: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 fromschema.toSchemaModel()(the canonicalAckSchemaModel) 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 Schema | JSON Schema Keyword | Notes |
|---|---|---|
minLength(n) | minLength: n | String |
maxLength(n) | maxLength: n | String |
matches(p) | pattern: p | String |
email() | format: email | String |
date() | format: date | String |
datetime() | format: date-time | String |
time() | format: time | String |
uri() | format: uri | String |
uuid() | format: uuid | String |
ipv4() | format: ipv4 | String |
ipv6() | format: ipv6 | String |
Ack.enumString([...]) | enum: [...] | String |
min(n) | minimum: n | Number |
max(n) | maximum: n | Number |
greaterThan(n) | exclusiveMinimum: n | Number (exclusive) |
lessThan(n) | exclusiveMaximum: n | Number (exclusive) |
multipleOf(n) | multipleOf: n | Number |
minLength(n) | minItems: n | List (array) |
maxLength(n) | maxItems: n | List (array) |
unique() | uniqueItems: true | List (array) |
nullable() | anyOf: [<schema>, {type: null}] | Any schema |
withDefault(v) | default: v | JSON/export-safe defaults only in AckSchemaModel; unsupported defaults are omitted with a warning |
describe(d) | description: d | Any schema |
Ack.integer() | type: integer | Type |
Ack.double() | type: number | Type |
Ack.string() | type: string | Type |
Ack.boolean() | type: boolean | Type |
Ack.list(...) | type: array, items: {...} | Type |
Ack.object(...) | type: object, properties: {...}, required: [...] | Type |
Ack.lazy(...) | definitions, $ref | Recursive 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 asanyOf: [{ "anyOf": [...] }, { "type": "null" }]Ack.discriminated(...)is emitted asanyOfwith effective object branches. Each branch contains the exact required discriminatorconst.Ack.discriminated(...).nullable()wraps thatanyOfunion with a second{ "type": "null" }branch.Ack.lazy(name, ...)is emitted as a Draft-7definitionsentry and local$refvalues such as{ "$ref": "#/definitions/Category" }.- Non-null lazy refs that carry metadata such as
descriptionuseallOfaround the$refso Draft-7 validators do not ignore that metadata as a$refsibling. Nullable lazy refs keep metadata beside the top-levelanyOf.
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)becomesadditionalProperties: false;additionalProperties: trueis emitted as the booleantrue.Ack.map(valueSchema): Exported as{"type": "object", "additionalProperties": <value schema>}. Map keys are always strings, so nopropertyNameskeyword is emitted.Ack.any(): Runtime validation accepts non-null JSON-safe values. JSON-like adapter exports represent those JSON-compatible values and attach anack_any_json_boundarywarning to theAckSchemaModel.Ack.lazy()runtime checks: Recursive structure is exported with Draft-7definitions/$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
formatMinimumorformatMaximumkeywords. 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 withAck.list(item).nullable()when the whole field may be null. - Discriminated branches:
Ack.discriminated(...)owns the discriminator. Branches may omit the discriminator field; compatibleAck.literal(...)orAck.enumString(...)fields are accepted; generated branches expose the exact branch value asconst.
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 fieldsDefault 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" propertiesComplex 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();