carp_serializable 1.2.0 copy "carp_serializable: ^1.2.0" to clipboard
carp_serializable: ^1.2.0 copied to clipboard

Polymorphic JSON serialization based on json_serializable annotations.

CARP Serialization #

A package for polymorphic serialization to/from JSON build on top of json_serializable.

This package allows for implementing serialization and deserialization to/from JSON. This is done using the json_serializable package, so please study how the json_serializable package works, before using this package.

The key feature of this package is that it extends json_serializable with support for serialization of polymorphic classes, i.e. classes that inherits from each other. This is done by adding type information to the json.

Getting started #

To use this package, add carp_serializable and json_annotation as dependencies in your pubspec.yaml file. Also add build_runner and json_serializable to the dev_dependencies:

    sdk: flutter
  json_annotation: ^latest
  carp_serializable: ^latest

    sdk: flutter
  build_runner: any   # For building json serialization
  json_serializable: any

Usage #

To support polymorphic serialization, each class should:

  • extend from Serializable
  • annotate the class with @JsonSerializable
  • add the three json methods
    • Function get fromJsonFunction => ...
    • factory ...fromJson(...)
    • Map<String, dynamic> toJson() => ...
  • register the classes in the FromJsonFactory() registry.
  • build json function using the flutter pub run build_runner build --delete-conflicting-outputs command

Below is a simple example of two classes A and B where B extends A.

class A extends Serializable {
  int index;

  A() : super();

  Function get fromJsonFunction => _$AFromJson;
  factory A.fromJson(Map<String, dynamic> json) => FromJsonFactory().fromJson(json) as A;
  Map<String, dynamic> toJson() => _$AToJson(this);

class B extends A {
  String str;

  B() : super();

  Function get fromJsonFunction => _$BFromJson;
  factory B.fromJson(Map<String, dynamic> json) => FromJsonFactory().fromJson(json) as B;
  Map<String, dynamic> toJson() => _$BToJson(this);

Note that the naming of the fromJson() and toJson() functions follows the json_serializable package. For example the fromJson function for class A is called _$AFromJson.

The fromJsonFunction must be registered on app startup (before use of de-serialization) in the FromJsonFactory singleton, like this:


For this purpose it is helpful to have an empty constructor, but any constructor will work, since only the fromJsonFunction function is used.

Polymorphic serialization is handled by setting the __type property in the Serializable class. Per default, an object's runtimeType is used as the __type for an object. Hence, the json of object of type A and B would look like this:

  "__type": "A",
  "index": 1
  "__type": "B",
  "index": 2
  "str": "abc"

However, if you want to specify your own class type (e.g., if you get json serialized from another language which uses a package structure like Java, C# or Kotlin), you can specify the json type in the jsonType property of the class.

For example, if the class B above should use a different __type annotation, using the following:

 class B extends A {

   <<as above>>

   String get jsonType => 'dk.cachet.$runtimeType';

In which case the json would look like:

  "__type": "dk.cachet.B",
  "index": 2
  "str": "abc"

Once the serialization code is used as above, run the

flutter pub run build_runner build --delete-conflicting-outputs

command as usual to generate the toJson() and fromJson() methods.

Features and bugs #

Please read about existing issues and file new feature requests and bug reports at the issue tracker.

License #

This software is copyright (c) Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is available 'as-is' under a MIT license.

pub points



Polymorphic JSON serialization based on json_serializable annotations.

Repository (GitHub)
View/report issues


API reference




flutter, json_annotation, meta


Packages that depend on carp_serializable