zto 0.1.3 copy "zto: ^0.1.3" to clipboard
zto: ^0.1.3 copied to clipboard

Published 2 months ago • verified publisherartizansoftwares.com
SDKDartFlutter
PlatformAndroidiOSLinuxmacOSwebWindows
→

Metadata

Annotation-based DTO validation and OpenAPI schema generation for Dart server-side.

More...

ZTO Banner

ZTO - Zero Friction DTO Validation #

Simple and powerful DTO validation for Dart backend applications. Write your DTOs once, get validation and OpenAPI documentation for free.

📖 Read skill — agent skill with the conventions, annotations, and production patterns for working with zto.

Features #

  • Simple DTOs — Write DTOs with annotations for validation
  • Automatic Validation — Type checking + custom validators run at parse time
  • Schema Generation — Auto-generated schemas with zto_generator
  • OpenAPI Ready — Convert DTOs to OpenAPI 3.0 specs for Swagger/OpenAPI docs
  • Business Rules — Chain .refine() for complex validations
  • Type Safe — Full type safety with Dart generics

Ecosystem #

zto is the core of a three-package toolchain. You write annotated DTOs once and the companion packages do the rest:

Package Role
zto This package. Annotations (@ZDto, @ZString, validators…) + the runtime Zto.parse() / ZtoSchema validation engine.
zto_generator build_runner code generator. Reads your annotated classes and emits the ZtoSchema constants (e.g. $CreateUserDtoSchema) used at runtime. Run it with dart run build_runner build.
dart_frog_open_api OpenAPI/Swagger spec generator for Dart Frog. Consumes your ZtoSchemas to document routes — see OpenAPI Integration. 
@ZDto annotated class
        │  zto_generator (build_runner)
        ▼
  $CreateUserDtoSchema  (ZtoSchema)
        │                         │
        │ zto                     │ dart_frog_open_api
        ▼                         ▼
  Zto.parse() validation    OpenAPI / Swagger docs

Quick Start (3 Steps) #

Step 1: Define Your DTO #

Create a file lib/domain/dtos/user_dto.dart:

import 'package:zto/zto.dart';

part 'user_dto.g.dart';  // Generated validation code

@ZDto(description: 'Request to create a user')
class CreateUserDto {
  @ZString(description: 'User full name', example: 'John Doe')
  @ZMinLength(2)
  @ZMaxLength(100)
  final String name;

  @ZString(description: 'User email address', example: 'john@example.com')
  @ZEmail()
  final String email;

  @ZInt(description: 'User age', example: 25)
  @ZMin(18)
  @ZMax(120)
  final int age;

  @ZString(description: 'Optional phone number')
  final String? phone;  // Nullability from `?` suffix

  const CreateUserDto({
    required this.name,
    required this.email,
    required this.age,
    this.phone,
  });

  factory CreateUserDto.fromMap(Map<String, dynamic> map) {
    return CreateUserDto(
      name: map['name'] as String,
      email: map['email'] as String,
      age: map['age'] as int,
      phone: map['phone'] as String?,
    );
  }
}

Step 2: Generate Schemas #

Run the code generator:

dart run build_runner build

This creates user_dto.g.dart with the schema constant $CreateUserDtoSchema.

Step 3: Validate in Your Route #

// In your route handler:
final body = await request.json() as Map<String, dynamic>;

try {
  final dto = $CreateUserDtoSchema.parse(body, CreateUserDto.fromMap).refine(
    (d) => d.age < 150,
    field: 'age',
    message: 'Age is unrealistic',
  );

  // dto is now validated and safe to use
  print('User: ${dto.name}, Email: ${dto.email}');
} on ZtoException catch (e) {
  // Handle validation errors
  return Response.json(
    statusCode: 422,
    body: {
      'errors': e.issues
          .map((issue) => {
            'field': issue.field,
            'message': issue.message,
          })
          .toList(),
    },
  );
}

Done! You now have:

  • ✅ Type validation (string, int, email, etc.)
  • ✅ Custom validators (min length, email format, etc.)
  • ✅ Null safety
  • ✅ Clear error messages

Class Annotations: @ZDto, @ZEntity, @ZModel #

A class becomes a Zto schema by annotating it with one of three semantically equivalent annotations. All three generate the exact same ZtoSchema — the only difference is intent, so the annotation documents which layer the type belongs to:

Annotation Use for Typical layer
@ZDto Data transfer objects — transport/contract shapes (request & response bodies) API boundary
@ZEntity Domain entities with business rules Domain
@ZModel Persistable aggregates (not necessarily a database table) Persistence

They share the same parameters:

Parameter Type Default Description
description String required Shown in OpenAPI / Swagger UI
parseType ParseType ParseType.camelCase How field names map to JSON keys (see below)
deprecated bool false Marks the schema as deprecated in OpenAPI 
@ZDto(description: 'Create user request')
class CreateUserDto { ... }

@ZEntity(description: 'User domain entity')
class UserEntity { ... }

@ZModel(description: 'Persistable user aggregate')
class UserModel { ... }

Because the three are equivalent, a field whose type is annotated with any of them is auto-detected as a nested object — no @ZObject() needed.

ParseType — Field Name Mapping #

parseType controls how Dart field names are converted to JSON map keys when a field doesn't set an explicit mapKey. Declare it once on the class annotation and it applies to every field of that class:

ParseType Transformation firstName becomes
camelCase (default) none — used as-is firstName
snakeCase camelCase → snake_case first_name
pascalCase uppercases the first letter FirstName
kebabCase camelCase → kebab-case first-name 
@ZDto(description: 'User', parseType: ParseType.snakeCase)
class UserDto {
  @ZString()
  final String firstName;   // JSON key: first_name

  @ZString()
  final String lastName;    // JSON key: last_name
}

An explicit mapKey always wins over parseType inference:

@ZDto(description: 'User', parseType: ParseType.snakeCase)
class UserDto {
  @ZString(mapKey: 'email_address')  // overrides snake_case inference
  final String email;                // JSON key: email_address
}

Field Types #

Annotate one type per field. Every type annotation shares these params: mapKey (explicit JSON key), description and example (shown in OpenAPI/Swagger), failMessage (custom type-mismatch message), and deprecated.

Annotation Dart type Example
@ZString String @ZString(description: 'Full name', example: 'Alice')
@ZInt int @ZInt(description: 'Age in years', example: 25)
@ZDouble double @ZDouble(description: 'Unit price', example: 9.99)
@ZNum num @ZNum(description: 'Score', example: 87.5)
@ZBool bool @ZBool(description: 'Whether active', example: true)
@ZDate DateTime @ZDate(description: 'Created at', example: '2024-03-15T10:00:00Z')
@ZFile upload @ZFile(description: 'Profile image')
@ZEnum enum / String @ZEnum(values: ['admin', 'editor', 'viewer'], description: 'Role')
@ZMap Map<String, dynamic> @ZMap(description: 'Raw metadata')
@ZMetaData Map<String, dynamic> @ZMetaData(description: 'User metadata', example: {'plan': 'pro'})
@ZList List<primitive> @ZList(itemType: ZString, description: 'List of tags')
@ZListOf List<NestedDto> @ZListOf(dtoType: AddressDto, description: 'Addresses')
@ZObj nested DTO (explicit) @ZObj(dtoType: AddressDto, description: 'Billing address')
@ZObject nested DTO (inferred) @ZObject(description: 'Address') — type read from the field
  • @ZEnum — on an enum-typed field the generator infers values from the enum; pass values: [...] explicitly for a plain String field.
  • @ZList takes a ZtoField type in itemType (e.g. ZString, ZInt) — for a list of nested DTOs use @ZListOf instead.
  • @ZListOf / @ZObj take either dtoSchema: (the generated $Schema) or dtoType: (the DTO class, looked up from the registry). For a single nested field, prefer @ZObject — it infers the type from the declaration, so no dtoType/dtoSchema is needed.

Validators #

Stack validators below the type annotation. They run at parse time and collect all failures (they don't stop at the first). Every validator accepts an optional message: to override the default error. The build fails with a clear error if a validator is incompatible with the field type (e.g. @ZEmail on a @ZDouble).

String (under @ZString):

Validator Passes ✓ / Fails ✗
@ZMinLength(2) 'abc' ✓ / 'a' ✗
@ZMaxLength(10) 'hello' ✓ / 'hello world!' ✗
@ZLength(5) '12345' ✓ / '1234' ✗
@ZEmail() 'a@b.com' ✓ / 'invalid' ✗
@ZUuid() '550e8400-e29b-41d4-a716-446655440000' ✓ / 'x' ✗
@ZUrl() 'https://example.com' ✓ / 'not-a-url' ✗
@ZHttpUrl() 'https://x.com' ✓ / 'ftp://x.com' ✗
@ZPattern(r'^[a-z]+$') 'abc' ✓ / 'Abc' ✗
@ZStartsWith('https://') 'https://x.com' ✓ / 'http://x.com' ✗
@ZEndsWith('.com') 'site.com' ✓ / 'site.org' ✗
@ZIncludes('foo') 'hello foo' ✓ / 'hello bar' ✗
@ZBase64() 'SGVsbG8=' ✓ / '!!!' ✗
@ZHex() 'deadbeef' ✓ / 'ghijk' ✗
@ZIpv4() '192.168.1.1' ✓ / '256.1.1.1' ✗
@ZIpv6() '2001:0db8::1' ✓ / 'invalid' ✗
@ZJwt() 'a.b.c' ✓ / 'a.b' ✗
@ZIsoDate() '2024-03-15' ✓ / '2024-13-01' ✗
@ZIsoDateTime() '2024-03-15T10:00:00Z' ✓ / '2024-03-15' ✗
@ZUppercase() 'ABC' ✓ / 'Abc' ✗
@ZLowercase() 'abc' ✓ / 'Abc' ✗
@ZSlug() 'my-blog-post' ✓ / 'Invalid Slug!' ✗
@ZAlphanumeric() 'abc123' ✓ / 'abc-123' ✗

Numeric (under @ZInt / @ZDouble / @ZNum; @ZMin/@ZMax also work on @ZDate):

Validator Passes ✓ / Fails ✗
@ZMin(18) 18, 25 ✓ / 17 ✗
@ZMax(120) 100, 120 ✓ / 121 ✗
@ZPositive() 1 ✓ / 0, -1 ✗
@ZNegative() -5 ✓ / 5 ✗
@ZNonNegative() 0, 1 ✓ / -1 ✗
@ZNonPositive() 0, -5 ✓ / 1 ✗
@ZMultipleOf(5) 10, 15 ✓ / 12 ✗
@ZInteger() 10 ✓ / 9.99 ✗
@ZFinite() 42 ✓ / infinity, nan ✗
@ZSafeInt() 9007199254740991 ✓ / 9007199254740992 ✗

Advanced Usage #

Custom Validation with .refine() #

final dto = $CreateUserDtoSchema.parse(body, CreateUserDto.fromMap)
    .refine(
      (user) => user.age >= 18,
      field: 'age',
      message: 'Must be an adult',
    )
    .refine(
      (user) => !user.email.contains('+'),
      field: 'email',
      message: 'Email aliases not allowed',
    );

Parse Multiple Items #

final users = $CreateUserDtoSchema.parseList(
  jsonArray,
  CreateUserDto.fromMap,
);

Alternate Factories #

Use any factory method you want:

// All work the same way
final dto1 = $CreateUserDtoSchema.parse(data, CreateUserDto.fromMap);
final dto2 = $CreateUserDtoSchema.parse(data, CreateUserDto.fromJson);
final dto3 = $CreateUserDtoSchema.parse(data, CreateUserDto.fromApi);

Error Handling #

try {
  final dto = $CreateUserDtoSchema.parse(body, CreateUserDto.fromMap);
} on ZtoException catch (e) {
  // e.issues contains all validation errors
  for (final issue in e.issues) {
    print('Field: ${issue.field}, Message: ${issue.message}');
  }
}

Common Patterns #

Create vs Update DTOs #

Use optional fields for update operations:

@ZDto(description: 'Create a new user')
class CreateUserDto {
  @ZString()
  @ZMinLength(2)
  final String name;
  
  @ZString()
  @ZEmail()
  final String email;
  
  const CreateUserDto({required this.name, required this.email});
}

@ZDto(description: 'Update an existing user')
class UpdateUserDto {
  @ZString()
  @ZMinLength(2)
  final String? name;  // Optional
  
  @ZString()
  @ZEmail()
  final String? email;  // Optional
  
  const UpdateUserDto({this.name, this.email});
}

Response DTOs #

@ZDto(description: 'User response')
class UserResponseDto {
  @ZString(description: 'Unique user ID')
  final String id;
  
  @ZString(description: 'User name')
  final String name;
  
  @ZString(description: 'User email')
  final String email;
  
  @ZDate(description: 'Account creation date')
  final DateTime createdAt;
  
  const UserResponseDto({
    required this.id,
    required this.name,
    required this.email,
    required this.createdAt,
  });
}

Ergonomic Features #

Nullability from Dart's ? Suffix #

Nullability is inferred directly from the Dart ? type suffix — there is no annotation for it:

// This is nullable (optional)
@ZString()
final String? nickname;

// This is required
@ZString()
final String name;

Enum Values Auto-Detection #

If you don't specify values, they're read from the enum:

enum Color { red, green, blue }

@ZEnum()  // Automatically becomes: values: ['red', 'green', 'blue']
final Color color;

Nested DTO Auto-Detection #

Fields whose type is annotated with @ZDto, @ZEntity, or @ZModel are automatically treated as objects:

@ZObject()  // Not needed anymore
final Address address;

// Just use:
final Address address;  // Type is @ZDto, so automatically an object

Testing #

test('validates user creation', () {
  final schema = $CreateUserDtoSchema;
  
  // Valid data passes
  final validUser = schema.parse(
    {'name': 'John', 'email': 'john@example.com', 'age': 25},
    CreateUserDto.fromMap,
  );
  expect(validUser.name, 'John');
  
  // Invalid data throws
  expect(
    () => schema.parse(
      {'name': 'J', 'email': 'invalid', 'age': 15},  // Too short, invalid email, too young
      CreateUserDto.fromMap,
    ),
    throwsA(isA<ZtoException>()),
  );
});

OpenAPI Integration #

Every ZtoSchema can be converted to an OpenAPI 3.0 schema with DtoToOpenApi:

import 'package:zto/zto.dart';

final openApiSchema = DtoToOpenApi.convert($CreateUserDtoSchema);
// Use in your OpenAPI spec builder

With Dart Frog — dart_frog_open_api #

For Dart Frog apps, the dart_frog_open_api package does this end-to-end: pass a ZtoSchema straight into its fluent route builder and it generates the full OpenAPI/Swagger document (request/response bodies, nested DTOs, validators) for you — no manual schema wiring.

import 'package:dart_frog_open_api/dart_frog_open_api.dart';

// Describe a route using the zto schema as the request body contract:
Api.path().post((op) => op
    .summary('Create user')
    .body($CreateUserDtoSchema)   // ← your zto schema
    .response(201));

Under the hood it calls DtoToOpenApi.convert (and OpenApiSchema.fromZto) on the same schemas you already validate with, so your docs never drift from your validation rules.

Complete Example #

File: lib/dtos/user_dto.dart

import 'package:zto/zto.dart';

part 'user_dto.g.dart';

@ZDto(description: 'Create a new user')
class CreateUserDto {
  @ZString(description: 'Full name', example: 'Alice Smith')
  @ZMinLength(2)
  final String name;

  @ZString(description: 'Email address', example: 'alice@example.com')
  @ZEmail()
  final String email;

  const CreateUserDto({
    required this.name,
    required this.email,
  });

  factory CreateUserDto.fromMap(Map<String, dynamic> map) {
    return CreateUserDto(
      name: map['name'] as String,
      email: map['email'] as String,
    );
  }
}

File: lib/routes/users.dart

import 'package:dart_frog/dart_frog.dart';
import 'package:myapp/dtos/user_dto.dart';

Future<Response> onRequest(RequestContext context) async {
  if (context.request.method == HttpMethod.post) {
    final body = await context.request.json();
    
    try {
      final newUser = $CreateUserDtoSchema.parse(
        body as Map<String, dynamic>,
        CreateUserDto.fromMap,
      );
      
      // Save to database
      return Response.json(
        statusCode: 201,
        body: {'id': '123', 'name': newUser.name, 'email': newUser.email},
      );
    } on ZtoException catch (e) {
      return Response.json(
        statusCode: 422,
        body: {
          'errors': e.issues
              .map((i) => {'field': i.field, 'message': i.message})
              .toList(),
        },
      );
    }
  }
  
  return Response(statusCode: 405);
}

FAQ #

Q: Do I need to write fromMap?
A: Yes, you write the deserialization logic yourself. ZTO only handles validation.

Q: Can I use ZTO with JSON serialization?
A: Yes! Use any factory method (fromMap, fromJson, fromApi, etc.). ZTO validates the same way.

Q: What if my API uses snake_case but Dart uses camelCase?
A: Use @ZDto(parseType: ParseType.snakeCase) on the class to auto-convert.

Q: How do I handle optional fields?
A: Use Dart's ? suffix:

@ZString()
final String? nickname;  // Optional field

Q: Can I validate across multiple fields?
A: Yes, use .refine():

final dto = $DtoSchema.parse(data, Dto.fromMap)
    .refine((d) => d.password == d.confirmPassword, message: 'Passwords must match');

Performance #

  • Code generation: Run once with dart run build_runner build
  • Runtime: Validation is O(n) where n = number of fields
  • No reflection: Everything is compiled ahead of time

Production Recommendations #

In production, never let validation details reach the client. The issues inside a ZtoException expose your internal field names, map keys, and business rules — that's information disclosure that helps an attacker probe your API. Treat the detailed ZtoException as a backend-only signal: it should flow exclusively to your logs / analytics, never into the HTTP response body.

Rule of thumb: the client always gets the same generic error message; the full detail goes only to your observability pipeline.

import 'dart:io';
import 'package:dart_frog/dart_frog.dart';
// import your logger (talker) / analytics client

Future<Response> onRequest(RequestContext context) async {
  final body = await context.request.json() as Map<String, dynamic>;

  try {
    final dto = $CreateUserDtoSchema.parse(body, CreateUserDto.fromMap);
    // ... use dto
    return Response.json(body: {'ok': true});
  } on ZtoException catch (e, stack) {
    // ✅ Detailed issues go ONLY to logs / analytics — never to the client.
    talker.warning('Validation failed', e, stack);
    analytics.track('validation_failed', {
      'route': context.request.uri.path,
      'issues': e.issues.map((i) => i.toMap()).toList(),
    });

    // ✅ Client receives a generic message with no internal detail.
    return Response.json(
      statusCode: HttpStatus.unprocessableEntity, // 422
      body: {'message': 'Invalid request.'},
    );
  }
}

Do

  • Return one fixed, generic message (e.g. 'Invalid request.') for every validation failure.
  • Forward e.issues (or e.toMap()) only to logs / analytics on the backend.
  • Use a single shared error handler / middleware so no route accidentally leaks issues.

Don't

  • Serialize e.issues / e.toMap() into the response sent to the client.
  • Echo back field names, regex patterns, or the offending value.
  • Configure Zto.errorFormatter to build a client-facing payload from issues — keep that formatter for your internal logging only.

The defaults (ZtoException.toMap() / _defaultFormat) include the full errors list precisely so you can pipe it to logging. Make the conscious choice to strip it before responding to the client.

License #

MIT

← Metadata

0
likes
150
points
156
downloads

Documentation

Documentation
API reference

Publisher

verified publisherartizansoftwares.com

Weekly Downloads

Metadata

Annotation-based DTO validation and OpenAPI schema generation for Dart server-side.

Homepage
Repository (GitHub)
View/report issues

Topics

#dto #validation #openapi #codegen

License

MIT (license)

More

Packages that depend on zto

Back