json_driven_dynamic_form #

Generate fully dynamic, validated Flutter forms from JSON — no manual widget wiring.

Version: 1.0.0 · SDK: Dart ^3.5.0 · Flutter >=3.24.0
Dependencies: Flutter SDK only (no hard deps on image_picker, geolocator, etc.)
Pub name: json_driven_dynamic_form · GitHub: flutter-dynamic-form

This document is the end-to-end reference for the package: schema format, every field type, validators, conditions, controller API, plugins, theming, localization, values shape, and common pitfalls — so you should not need to reverse-engineer the source later.

Table of contents #

1. What this package solves
2. Installation
3. Quick start
4. How it works
5. Schema JSON reference
6. Field types
7. Validators
8. Conditional visibility & enabled
9. Nested groups & repeatable sections
10. Schema validation (pre-render)
11. DynamicForm widget API
12. DynamicFormController API
13. Submitted values shape
14. Media fields & injectable services
15. Custom field renderers (plugins)
16. Theming
17. Localization
18. Accessibility
19. Responsive / platform notes
20. Example app
21. Public API checklist
22. Troubleshooting
23. Docs & license

What this package solves #

You describe a form once as JSON (or a Dart Map / FormSchema). The package:

1. Validates the schema structure (paths like fields[0].key)
2. Renders Material fields for 25+ types
3. Tracks values, dirty state, sync/async errors
4. Evaluates visibleWhen / enabledWhen
5. Submits a plain Map<String, dynamic> you can send to an API

Use it when forms are configured by a backend, CMS, or product team without shipping a new app build for every layout change.

Not included by design: native pickers. Media types use injectable interfaces so the package stays dependency-light and pub-friendly. Wire image_picker / file_picker / geolocator (or mocks) in your app.

Installation #

dependencies:
  json_driven_dynamic_form: ^1.0.0

import 'package:json_driven_dynamic_form/json_driven_dynamic_form.dart';

Quick start #

final controller = DynamicFormController();

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: DynamicForm(
      json: {
        'title': 'User Registration',
        'description': 'Create your account',
        'submitLabel': 'Continue',
        'fields': [
          {
            'type': 'text',
            'key': 'name',
            'label': 'Full Name',
            'required': true,
            'validators': [
              {'type': 'length', 'min': 2, 'max': 80},
            ],
          },
          {'type': 'email', 'key': 'email', 'required': true},
          {
            'type': 'password',
            'key': 'password',
            'label': 'Password',
            'required': true,
            'validators': [
              {'type': 'length', 'min': 8},
            ],
          },
          {
            'type': 'password',
            'key': 'confirmPassword',
            'label': 'Confirm password',
            'required': true,
            'validators': [
              {
                'type': 'compare',
                'field': 'password',
                'operator': 'equals',
                'message': 'Passwords must match',
              },
            ],
          },
        ],
      },
      controller: controller,
      onSubmit: (values) {
        // values == { name, email, password, confirmPassword }
        debugPrint('$values');
      },
      onSchemaInvalid: (result) {
        // Prefer fixing JSON; SchemaErrorView is already shown in the UI.
        debugPrint(result.errors.join('\n'));
      },
    ),
  );
}

json accepts:

How it works #

JSON / Map
   │
   ▼
FormSchemaValidator  ──fail──►  SchemaErrorView (paths + messages)
   │ pass
   ▼
FormSchemaParser  ──►  FormSchema + FormFieldSchema tree
   │
   ▼
DynamicFormController.bind()
   │
   ▼
FieldBuilder  ──►  Material widgets (or custom FieldRenderer)
   │
   ▼
validate / validateAsync / submit  ──►  Map values (+ optional nested groups)

• Sync validators run on change / validate() / before async on submit.
• Async / server validators run via validateAsync() and inside submit().
• Conditions re-evaluate when values change; fields animate show/hide when themed.

Schema JSON reference #

Root (FormSchema) #

Minimal valid document:

{
  "fields": [
    { "type": "text", "key": "name" }
  ]
}

Field object (FormFieldSchema) — common keys #

Type-specific keys are listed under Field types.

Options #

Accepted shapes for each option entry:

"US"

{ "value": "US", "label": "United States", "enabled": true }

Also accepts text / title as label aliases. Numbers and booleans are allowed as bare values.

Field types #

Aliases are case-insensitive after trim. Prefer the canonical name in new schemas.

Text & numbers #

{
  "type": "number",
  "key": "age",
  "label": "Age",
  "min": 18,
  "max": 120,
  "required": true
}

Boolean #

Selection #

Date & time #

Values are stored as formatted strings matching the field format.

Structure #

Media (requires plugins) #

Without configured media services, UI shows a localized “not configured” message.

Advanced #

Unknown type strings become FieldType.unknown (placeholder) and may surface as a schema warning.

Validators #

Declaring rules #

"validators": [
  "required",
  { "type": "length", "min": 2, "max": 50, "message": "Name length invalid" },
  { "type": "regex", "pattern": "^[A-Za-z ]+$" },
  { "type": "compare", "field": "password", "operator": "equals" },
  { "type": "async", "name": "uniqueEmail" },
  { "type": "server", "url": "/api/validate-email" }
]

Auto-injected (you don’t need to repeat them):

• required: true → required rule
• field-level regex / pattern
• number min / max
• email / phone field types

Built-in rule types #

Shared optional keys on rule maps: type/name, message, pattern/regex, min/minimum, max/maximum, value, field, operator/op, url/endpoint, params.

Async & server (app code) #

controller.registerAsyncValidator('uniqueEmail', (value, ctx) async {
  final ok = await api.isEmailFree(value as String?);
  return ok ? null : 'Email already registered';
});

controller.setServerValidator((value, ctx, rule) async {
  return api.validateRemote(rule.url!, value); // return String? error
});

// Sync only — skips async/server rules
final okSync = controller.validate();

// Includes async + server
final ok = await controller.validateAsync();
final submitted = await controller.submit(); // validateAsync then onSubmit

Important: sync validate() intentionally skips async / server rules. Always use validateAsync() or submit() when those rules matter.

Conditional visibility & enabled #

Keys #

Both schema flags (visible / enabled) and conditions must pass. readOnly: true forces disabled.

Condition shapes #

{ "field": "hasPet", "operator": "equals", "value": true }

{ "field": "age", "op": "gte", "value": 18 }

{ "field": "age", "gte": 18 }

{ "country": "IN" }

{
  "all": [
    { "field": "role", "operator": "equals", "value": "other" },
    { "field": "age", "operator": "gte", "value": 18 }
  ]
}

{
  "any": [
    { "field": "plan", "op": "equals", "value": "pro" },
    { "field": "plan", "op": "equals", "value": "enterprise" }
  ]
}

• { "all": [...] } / { "and": [...] } → all must match
• { "any": [...] } / { "or": [...] } → any may match
• Bare list → treated as AND

Field key aliases: field, when, key, dependsOn, depends_on.

Operators (ConditionOperator) #

Hidden fields are not shown; their values remain in the controller until cleared/reset (design choice — strip them in your submit handler if the API requires it).

Nested groups & repeatable sections #

Group #

{
  "type": "group",
  "key": "address",
  "label": "Address",
  "fields": [
    { "type": "text", "key": "line1", "label": "Line 1", "required": true },
    { "type": "text", "key": "city", "label": "City", "required": true }
  ]
}

• Flat values (controller.values): child keys live at the root (line1, city). Child keys must be unique across the form (including other groups).
• Nested values (controller.nestedValues or submit(nestGroups: true)): nested under the group key:

{ "address": { "line1": "...", "city": "..." } }

Repeatable #

{
  "type": "repeatable",
  "key": "references",
  "label": "References",
  "minItems": 1,
  "maxItems": 5,
  "fields": [
    { "type": "text", "key": "name", "label": "Name", "required": true },
    { "type": "email", "key": "email", "label": "Email", "required": true }
  ]
}

Value shape:

{
  "references": [
    { "name": "Ada", "email": "ada@example.com" },
    { "name": "Grace", "email": "grace@example.com" }
  ]
}

Controller helpers:

controller.addRepeatableItem('references');
controller.removeRepeatableItem('references', 0);
controller.updateRepeatableItemField('references', 0, 'name', 'Ada');

Schema validation (pre-render) #

By default (validateSchema: true), invalid schema JSON never renders the form. Users/devs see SchemaErrorView with:

• JSON path (e.g. fields[2].key)
• Message, expected, actual
• Copy-all errors
• Warnings (e.g. unknown type) may still allow render with a banner

final result = const FormSchemaValidator().validate(rawJson);
if (!result.isValid) {
  for (final issue in result.errors) {
    print('${issue.path}: ${issue.message}');
  }
}

DynamicForm(
  json: rawJson,
  validateSchema: true,
  onSchemaInvalid: (result) { /* analytics */ },
);

Pass a pre-built FormSchema to skip map validation (you already own the model).

DynamicForm widget API #

DynamicFormController API #

Create #

final controller = DynamicFormController(
  customValidators: { 'myRule': (value, ctx) => null },
  asyncValidators: { 'uniqueEmail': (value, ctx) async => null },
  serverValidator: (value, ctx, rule) async => null,
);

State #

Methods #

Wire widget callbacks either on DynamicForm(...) or by assigning controller.onSubmit = ... before bind.

Submitted values shape #

Typical flat map:

{
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "age": "36",
  "plan": "pro",
  "tags": ["a", "b"],
  "agree": true,
  "startDate": "2026-07-23",
  "score": 4.0,
  "color": "#2196F3",
  "avatar": {
    "path": "/tmp/a.jpg",
    "name": "a.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 12345,
    "source": "gallery"
  },
  "location": {
    "latitude": 37.77,
    "longitude": -122.41,
    "accuracy": 10.0,
    "address": null
  },
  "references": [
    { "name": "Grace", "email": "grace@example.com" }
  ]
}

MediaFileValue #

LocationValue #

Signature value is a list of stroke maps (not a PNG). Convert to an image in your app if needed.

Media fields & injectable services #

class MyImagePicker implements FormImagePicker {
  @override
  Future<MediaFileValue?> pickFromGallery() async {
    // Use image_picker, file_picker, etc.
    return MediaFileValue(path: '...', name: 'photo.jpg');
  }
}

final plugins = DynamicFormPluginRegistry(
  mediaServices: FormMediaServices(
    imagePicker: MyImagePicker(),
    camera: MyCamera(),
    filePicker: MyFilePicker(),
    location: MyLocation(),
  ),
);

DynamicForm(json: schema, plugins: plugins, controller: controller);

Interfaces:

For demos/tests:

plugins: DynamicFormPluginRegistry(mediaServices: mockMediaServices()),

Custom field renderers (plugins) #

final plugins = DynamicFormPluginRegistry();

plugins.registerRenderer('badge', (FieldRenderContext ctx) {
  return TextField(
    decoration: InputDecoration(labelText: ctx.field.label),
    onChanged: (v) => ctx.controller.updateField(ctx.field.key, v),
  );
});

DynamicForm(
  json: {
    'fields': [
      {
        'type': 'custom',
        'customType': 'badge',
        'key': 'code',
        'label': 'Badge code',
      },
    ],
  },
  plugins: plugins,
);

• Lookup order: customType / custom_type / renderer, else built-in type name.
• You can also override a built-in type by registering a renderer under that type name (e.g. 'text').
• FieldRenderContext exposes context, field, controller, theme.

Theming #

DynamicForm(
  json: schema,
  theme: const DynamicFormTheme(
    fieldSpacing: 20,
    borderRadius: 12,
    maxContentWidth: 640, // null = full width
    dense: false,
    animateFields: true,
    showResetButton: true,
    groupDecoration: true,
  ),
);

Use DynamicFormThemeProvider.of(context) inside custom renderers.

Localization #

DynamicForm(
  json: schema,
  localizations: const DynamicFormLocalizations(
    submitLabel: 'Enviar',
    resetLabel: 'Restablecer',
    requiredMessage: '{label} es obligatorio',
    emailMessage: 'Correo inválido',
    addItemLabel: 'Añadir',
    removeItemLabel: 'Quitar',
    pickImageLabel: 'Elegir imagen',
    takePhotoLabel: 'Tomar foto',
    pickFileLabel: 'Elegir archivo',
    getLocationLabel: 'Obtener ubicación',
    mediaNotConfigured: 'Servicio multimedia no configurado',
    itemLabel: 'Ítem {index}',
  ),
);

Templates support {label}, {min}, {max}, {field}, {index} via DynamicFormLocalizations.format.

Note: Built-in sync validator default English strings are currently hardcoded in the validator engine. Prefer per-rule "message" in JSON for production copy, and use DynamicFormLocalizations for chrome (buttons, media, repeatable).

Accessibility #

• Fields wrap interactive controls with Semantics.
• Set semanticLabel / semantic_label on any field for a custom a11y name.
• SchemaErrorView is a live region so screen readers announce schema failures.

Responsive / platform notes #

Package environment:

sdk: ^3.5.0
flutter: ">=3.24.0"

Example app #

cd example
flutter run

Bundled schemas under example/assets/schemas/:

Public API checklist #

Import once:

import 'package:json_driven_dynamic_form/json_driven_dynamic_form.dart';

Troubleshooting #

Validate only schema (CI / backend) #

test('registration schema is valid', () {
  final json = jsonDecode(File('schemas/registration.json').readAsStringSync());
  final result = const FormSchemaValidator().validate(json);
  expect(result.isValid, isTrue, reason: result.errors.join('\n'));
});

Docs & license #

flutter analyze
flutter test
dart pub publish --dry-run

MIT © contributors — see LICENSE.