Skip to Content
DocsAckAdvancedCreating Adapter Packages

Creating Adapter Packages

An adapter exports an Ack boundary contract to another schema system. Choose the export surface according to the target, and reject semantics you cannot preserve. See Ecosystem Integrations to use an existing adapter.

Choose the export surface

TargetStarting pointResponsibility
Accepts JSON Schema mapsschema.toJsonSchema()Preserve the rendered document and check target dialect support.
Requires legacy Draft-7schema.toJsonSchemaDraft7()Handle unsupported lowering explicitly.
Uses a different schema languageschema.toSchemaModel()Translate the canonical model and its metadata, or reject unsupported cases.

Native Ack schemas render as Draft-7. Imported Draft 2020-12 resources retain their dialect and resource semantics by default. Do not silently lower them or strip keywords to make a target accept the document.

Non-JSON adapters should consume AckSchemaModel, rather than walking runtime AckSchema subclasses or reverse-engineering rendered JSON. That keeps wrapper, codec, default, and discriminator handling in Ack’s export layer.

JSON-map adapters

If the target accepts Ack’s rendered JSON Schema, the conversion can be small:

import 'package:ack/ack.dart'; extension TargetJsonSchemaExtension on AckSchema { Map<String, Object?> toTargetJsonSchema() => toJsonSchema(); }

This is the approach used by ack_firebase_ai for the map-based GenerationConfig.responseJsonSchema field. It does not convert to Firebase’s native Schema class or normalize a provider-specific subset. The ack_json_schema_builder bridge similarly wraps the rendered map in jsb.Schema.fromMap(...) and offers a separate Draft-7 lowering method.

A response schema guides generation; validate returned data with Ack as well. A target may not enforce refinements or every keyword it accepts. Make that boundary explicit in the adapter’s documentation.

Non-JSON targets

Route on the sealed model variants, then implement the semantics needed by the target. A type-name match alone is not a complete conversion.

ModelMapping to consider
AckStringSchemaModelString literals/enums, length, pattern, and format
AckIntegerSchemaModel, AckNumberSchemaModelBounds, exclusivity, and numeric constraints
AckBooleanSchemaModel, AckNullSchemaModelBoolean and null support
AckObjectSchemaModelProperties, required keys, extra-property policy, and metadata
AckArraySchemaModelItem schema and collection constraints
AckAnyOfSchemaModel, AckOneOfSchemaModel, AckAllOfSchemaModelBranch semantics, discriminator metadata, and compositions
AckRefSchemaModelDefinitions, reference identity, and recursive resolution
AckRawSchemaModelImported resource dialect and vocabulary semantics

Apply the same checks recursively. A supported object can contain an unsupported raw import or reference. Rejecting only unsupported roots is insufficient.

Presence, nullability, and additional properties

Required-key membership and nullability are separate. A required nullable field must still be present. Do not infer key presence from the field’s Dart type or map nullability onto a target’s required marker without checking its semantics.

AckObjectSchemaModel.additionalProperties can allow extras, disallow them, or specify a schema for their values. Preserve that distinction. Ack.map(...) uses object-model metadata without a fixed list of declared properties.

For targets such as GraphQL, nullable values and non-null field markers need explicit mapping. Reject structures the target cannot express rather than silently replacing them with a string or unrestricted object.

Codecs, defaults, and warnings

The model describes boundary values. A DateTime codec exports its string wire shape; runtime constraints are projected only when their meaning survives that mapping. One-way transforms do not give an adapter a reverse conversion.

Inspect warnings on model nodes, including nested nodes. For example, a default that cannot be exported safely produces a warning. Runtime refinements are not represented in the exported schema; a refinement on Ack.string() is omitted without emitting a warning. Decide which warnings the adapter can return to callers and which require an explicit failure. Do not promise that exporting a schema preserves arbitrary runtime validation.

Keep descriptions, export-safe defaults, and discriminator metadata when the target supports them. A strict conversion mode can reject unsupported metadata or semantics; document precisely what it checks.

References and imported resources

A native lazy schema can produce AckRefSchemaModel. Supporting it means resolving and emitting its definitions, not just copying a reference name. Recursive graphs also need cycle handling; an unbounded recursive traversal is not a reference implementation.

An imported resource can produce AckRawSchemaModel directly or inside a composition. It may use custom dialects, $dynamicRef, or vocabularies that cannot be translated to the target. Implement those semantics or throw a clear unsupported-conversion error. For JSON Schema targets, prefer the complete renderer so definitions and resource identities remain intact.

Test the exported contract

Use meaningful assertions against real Ack schemas. For the JSON-map extension above, a small fixture can verify required keys, constraints, and codec boundaries:

import 'package:ack/ack.dart'; import 'package:test/test.dart'; // Import the adapter library defining TargetJsonSchemaExtension here. void main() { test('exports the wire contract', () { final schema = Ack.object({ 'name': Ack.string().minLength(2), 'when': Ack.datetime(), 'nickname': Ack.string().optional().nullable(), }); final json = schema.toTargetJsonSchema(); final properties = json['properties'] as Map<String, Object?>; expect(properties['name'], containsPair('minLength', 2)); expect(properties['when'], containsPair('type', 'string')); expect(properties['when'], containsPair('format', 'date-time')); expect(json['required'], containsAll(['name', 'when'])); expect(json['required'], isNot(contains('nickname'))); expect(json, containsPair('additionalProperties', false)); }); }

For a non-JSON adapter, test the actual target representation and its validation behavior where a target validator is available. Include nullable and optional fields, enums, compositions, extra-property rules, omitted runtime semantics, and unsupported raw/reference cases. Test both nested and root cases. For recursive/reference support, include a fixture with repeated and cyclic references, not only an inline schema.

When claiming imported JSON Schema compatibility, test a representative bundled resource and its exported dialect. Do not treat a non-null conversion result as proof that validation semantics survived.

Add an adapter to this repository

Use an ack_<target> package name and follow the nearest existing package’s layout and SDK constraints. Workspace membership lives in the root pubspec.yaml; this repository has no melos.yaml package list. Keep hosted sibling dependency constraints suitable for publishing.

Follow CONTRIBUTING.md  for checks, and PUBLISHING.md  for coordinated versions and tag-only publishing. A new adapter needs a reviewed integration before publication; the first package upload has a documented manual bootstrap exception. Do not publish from a package-template checklist.

Document the target’s supported schema shapes, dialects, and explicit failures in its README. Keep target-specific SDK examples in the adapter package instead of copying a general package scaffold into every guide.

Last updated on