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
| Target | Starting point | Responsibility |
|---|---|---|
| Accepts JSON Schema maps | schema.toJsonSchema() | Preserve the rendered document and check target dialect support. |
| Requires legacy Draft-7 | schema.toJsonSchemaDraft7() | Handle unsupported lowering explicitly. |
| Uses a different schema language | schema.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.
| Model | Mapping to consider |
|---|---|
AckStringSchemaModel | String literals/enums, length, pattern, and format |
AckIntegerSchemaModel, AckNumberSchemaModel | Bounds, exclusivity, and numeric constraints |
AckBooleanSchemaModel, AckNullSchemaModel | Boolean and null support |
AckObjectSchemaModel | Properties, required keys, extra-property policy, and metadata |
AckArraySchemaModel | Item schema and collection constraints |
AckAnyOfSchemaModel, AckOneOfSchemaModel, AckAllOfSchemaModel | Branch semantics, discriminator metadata, and compositions |
AckRefSchemaModel | Definitions, reference identity, and recursive resolution |
AckRawSchemaModel | Imported 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.