JSON Converters API

JsonConverter<T> Interface

abstract interface class JsonConverter<T> {
  T fromJson(dynamic json);
  dynamic toJson(T value);
  T get defaultValue;
}

Method	Description
fromJson(json)	Convert JSON to typed value
toJson(value)	Convert typed value to JSON
defaultValue	Default value for the type

BaseJsonConverter<T>

Abstract base class with error handling. Subclasses override convertFromJson and convertToJson instead of fromJson/toJson directly.

abstract base class BaseJsonConverter<T> implements JsonConverter<T> {
  const BaseJsonConverter();
  T convertFromJson(dynamic json);      // implement this
  dynamic convertToJson(T value);       // implement this
}

Errors are wrapped in JsonConversionException.

JsonConversionException

final class JsonConversionException implements Exception {
  final String message;
  final dynamic json;
  final Type targetType;
  final Object? cause;
}

Built-in Converters

StringJsonConverter

Aspect	Value
Type	String
Default	''
fromJson	null returns '', non-strings converted via .toString()
toJson	Returns the string as-is

IntJsonConverter

Aspect	Value
Type	int
Default	0
fromJson	Parses int, double (truncated), or String
toJson	Returns the integer as-is

DoubleJsonConverter

Aspect	Value
Type	double
Default	0.0
fromJson	Parses double, int (promoted), or String
toJson	Returns the double as-is

BoolJsonConverter

Aspect	Value
Type	bool
Default	false
fromJson	Parses bool, int (0/1), or String ('true'/'false')
toJson	Returns the boolean as-is

DateTimeJsonConverter

Aspect	Value
Type	DateTime
Default	DateTime(0)
fromJson	Parses ISO 8601 string or DateTime instance
toJson	Returns ISO 8601 string via .toIso8601String()

NullableJsonConverter

Wraps another converter to handle nullable values.

final class NullableJsonConverter<T> implements JsonConverter<T?> {
  final JsonConverter<T> innerConverter;
  const NullableJsonConverter(this.innerConverter);
}

Aspect	Value
Default	null
fromJson	Returns null if input is null, delegates to inner converter otherwise
toJson	Returns null if value is null, delegates to inner converter otherwise

EnumJsonConverter

For Dart enum types (requires T extends Enum).

final class EnumJsonConverter<T extends Enum> extends BaseJsonConverter<T> {
  final List<T> values;
  const EnumJsonConverter(this.values);
}

Aspect	Value
Default	First value in the list
fromJson	Matches by .name, .toString(), or index
toJson	Returns .name

EnumOptionsJsonConverter

For any type T using EnumOption<T> for matching. Auto-registered by EnumProperty.

final class EnumOptionsJsonConverter<T> extends BaseJsonConverter<T> {
  final List<EnumOption<T>> options;
  const EnumOptionsJsonConverter(this.options);
}

Aspect	Value
Default	First option's value
fromJson	Matches by Enum.name, .toString(), or index
toJson	Returns .name for enums, .toString() for others

ListJsonConverter

Converts lists by delegating each item to an inner converter.

final class ListJsonConverter<T> extends BaseJsonConverter<List<T>> {
  final JsonConverter<T> itemConverter;
  const ListJsonConverter(this.itemConverter);
}

Aspect	Value
Default	<T>[]
fromJson	null returns empty list. Single item wrapped in list.
toJson	Maps each item through itemConverter.toJson()

UnionJsonConverter

For UnionProperty's selected key string. The full union JSON structure is handled by UnionProperty.toJson()/fromJson().

final class UnionJsonConverter extends BaseJsonConverter<String> {
  const UnionJsonConverter();
}

Aspect	Value
Default	''
fromJson	Extracts selectedKey from map, or converts to string
toJson	Returns the string as-is

Auto-Registered Defaults

PropertySystem auto-registers these on first access:

Type	Converter	Editor
String	StringJsonConverter	TextPropertyEditor
int	IntJsonConverter	IntPropertyEditor
double	DoubleJsonConverter	DoublePropertyEditor
bool	BoolJsonConverter	BoolPropertyEditor
DateTime	DateTimeJsonConverter	DateTimePropertyEditor
String?	NullableJsonConverter<String>	OptionalStringPropertyEditor
int?	NullableJsonConverter<int>	OptionalIntPropertyEditor
double?	NullableJsonConverter<double>	OptionalDoublePropertyEditor
bool?	NullableJsonConverter<bool>	OptionalBoolPropertyEditor
DateTime?	NullableJsonConverter<DateTime>	OptionalDateTimePropertyEditor

Custom key registrations:

Key	Converter	Editor
readonly:string	--	ReadOnlyPropertyEditor<String>
readonly:int	--	ReadOnlyPropertyEditor<int>
readonly:double	--	ReadOnlyPropertyEditor<double>
readonly:bool	--	ReadOnlyPropertyEditor<bool>
readonly:datetime	--	ReadOnlyPropertyEditor<DateTime>
union	UnionJsonConverter	--

Next Steps

• Validators API -- Validator reference
• Glossary -- Terms and definitions
• JSON Serialization Guide -- Converters in practice