Schema reference
Start with a factory, then add checks and compose it into larger shapes. Import these APIs from package:acanthis/acanthis.dart. Top-level factories are also available through the Acanthis facade.
final email = string().trim().email();
final account = object({'email': email, 'tags': string().list()});Types
| Schema | Parsed output | Reference |
|---|---|---|
string() | String | Strings |
number(), integer(), doubleType() | num, int, double | Numbers |
boolean() | bool | Booleans |
date() | DateTime | Dates |
object({...}) | Map<String, Object?> | Objects |
record(keys, values) | Map<K, V> | Records |
list(element) or element.list() | List<T> | Lists |
tuple([...]) | Heterogeneous list | Tuples |
schema.nullable() | T? | Nullable values |
literal(value) | The declared literal type | Literals |
union<T>([...]) | T | Unions |
variant<T>(guard: ..., schema: ...) | T | Guarded branches |
template([...]) | String | Templates |
lazy((parent) => ...) | The bound child output | Recursive objects |
instance<T>() | Existing T | Instances |
classSchema<I, T>()...build() | Constructed T | Classes |
Objects do not infer Dart classes from field names. The child schemas define parsed values; class schemas provide explicit mapping into domain types.
Composition
final name = string().min(2);
final shortName = name.max(12);
final names = name.list();
final nullableName = name.nullable();
final nameOrId = name.or<Object?>([integer()]);
final nameAndAge = name.and([integer()]);Native fluent methods return new schemas. A check or transform added to shortName does not modify name. Modifier order matters: .nullable().list() permits null elements; .list().nullable() permits a null list.
Operations
| Task | API and guide |
|---|---|
| Parse input or check validity | parse, tryParse, validate |
| Change optional fields, defaults, or PATCH behavior | Presence and defaults |
| Add a predicate or several issues | Custom validation |
| Change values or output types | Transforms, coercion, and pipes |
| Compare parsed object fields | Cross-field rules |
| Revalidate incremental edits | Live validation |
| Attach descriptions | Metadata |
| Share schemas through typed keys | Registries |
| Generate validated samples | Mock data |
| Export or import a JSON contract | JSON Schema and OpenAPI |
Custom schemas
Extend Schema<Input, Output> when defining a new schema implementation. Implement raw-value parse(Object?) and outcome-returning tryParse(Object?). Capabilities such as checks, defaults, lists, and nullability are opt-in mixins. The factory alias AcanthisType is not a generic schema base.
See the repository's docs/v2/ reference notes for implementation contracts. Most application schemas can be built from native types and pipes.