The Most Powerful Way to Automatically Generate Model Objects from JSON Files ⚡

---

---

• 1. Guide 🌎
  • 1.1. Features 💎
    • 1.1.1. From
    • 1.1.2. To
  • 1.2. Getting Started 🏄
    • 1.2.1. Prerequisite
    • 1.2.2. Install Library
    • 1.2.3. Create a JSON File
    • 1.2.4. Execute Command
  • 1.3. Reference for Identifiers
    • 1.3.1. Make Specific Fields Required
      • 1.3.1.1. From
      • 1.3.1.2. To
    • 1.3.2. Assign an Alias for Objects
      • 1.3.2.1. From
      • 1.3.2.2. To
    • 1.3.3. Assign an Alias for Fields
      • 1.3.3.1. From
      • 1.3.3.2. To
  • 1.4. Advanced Usage
    • 1.4.1. Enum Generation and Mapping
    • 1.4.2. External Directory Reference
  • 1.5. Contribution 🏆
  • 1.6. Support ❤️
  • 1.7. License 🔑
  • 1.8. More Information 🧐

1. Guide 🌎

This library was built on the foundation of the json_serializable and freezed libraries.

This library provides the ability to automatically generate class objects supported by the freezed library directly from JSON files.

Show some ❤️ and star the repo to support the project.

Note
Many of the specifications in this library are still in development. Your contributions are very welcome!

1.1. Features 💎

• Generate model objects on a JSON basis.
• Synchronize model design and implementation on a JSON basis.
• JSON from API can be converted directly into model objects.
• Aliases and other useful identifiers.
• Supports automatic Enum generation and mapping with model objects.
• The automatically generated model objects are based on the freezed library.
• Very easy to install.
• etc...

And all you have to do is prepare a JSON file defining the structure of the model object to be generated and run the command dart run freezer:main in a terminal.

You can see the following example.

1.1.1. From

{
  "shop": {
    "name.!required": "My Fancy Shop",
    "products.!as:product.!name:my_products": [
      {
        "name": "Chocolate",
        "price": 5.99
      },
      {
        "name": "Gummy",
        "price": 8.99
      }
    ],
    "location": [-122.4194, 37.7749],
    "closed": false,
    "$name": "This is a comment for name field.",
    "$products": "This is a comment for product field.",
    "$$products": "This is a comment for product object."
  }
}

1.1.2. To

// GENERATED CODE - DO NOT MODIFY BY HAND
// ignore_for_file: invalid_annotation_target

import 'package:freezed_annotation/freezed_annotation.dart';

import 'product.dart';

part 'shop.freezed.dart';
part 'shop.g.dart';

// **************************************************************************
// FreezerGenerator
// **************************************************************************

@freezed
class Shop with _$Shop {
  const factory Shop({
    /// This is a comment for name field.
    required String name,

    /// This is a comment for product field.
    @JsonKey(name: 'products') List<Product>? myProducts,
    List<double>? location,
    bool? closed,
  }) = _Shop;

  /// Returns [Shop] based on [json].
  factory Shop.fromJson(Map<String, Object?> json) => _$ShopFromJson(json);
}

// GENERATED CODE - DO NOT MODIFY BY HAND

import 'package:freezed_annotation/freezed_annotation.dart';

part 'product.freezed.dart';
part 'product.g.dart';

// **************************************************************************
// FreezerGenerator
// **************************************************************************

/// This is a comment for product object.
@freezed
class Product with _$Product {
  const factory Product({
    String? name,
    double? price,
  }) = _Product;

  /// Returns [Product] based on [json].
  factory Product.fromJson(Map<String, Object?> json) =>
      _$ProductFromJson(json);
}

And .freezed.dart and .g.dart files are automatically generated at the same time.
So, there is even no need to run build_runner yourself!

1.2. Getting Started 🏄

1.2.1. Prerequisite

The codes automatically generated by this library depend on annotations from json_serializable and freezed.

So, let's add the prerequisite libraries to pubspec.yaml as follows.

dependencies:
  freezed_annotation: ^latest

dev_dependencies:
  json_serializable: ^latest
  freezed: ^latest

1.2.2. Install Library

Next, let's install the libraries to use the freezer functionality.

Simply add freezer: ^latest to your pubspec.yaml's dev_dependencies.

Or you can add by command as follows.

With Dart:

dart pub add freezer

With Flutter:

flutter pub add freezer

1.2.3. Create a JSON File

freezer interprets JSON files as design information and automatically generates object classes supported by the freezed library.

And you need to note following rules when you use the freezer.

1. freezer parses files with the .freezer.json extension.
2. freezer parses JSON files stored in the .design folder.

So, now let's create a JSON file with the following structure as a trial.

{
  "shop": {
    "name.!required": "My Fancy Shop",
    "products.!as:product.!name:my_products": [
      {
        "name": "Chocolate",
        "price": 5.99
      },
      {
        "name": "Gummy",
        "price": 8.99
      }
    ],
    "location": [-122.4194, 37.7749],
    "closed": false,
    "$name": "This is a comment for name field.",
    "$products": "This is a comment for product field.",
    "$$products": "This is a comment for product object."
  }
}

And then store this JSON file in the .design folder of the root of project.

.
├── analysis_options.yaml
├── design
│   └── sample
│       └── shop.freezer.json
├── lib
├── pubspec.lock
└── pubspec.yaml

1.2.4. Execute Command

Now let's execute the following command and see what happens!

dart run freezer:main

Then, this trial is successful if the following output is obtained.

Started process for 1 files

[INFO] Reading cached asset graph completed, took 28ms
[INFO] Checking for updates since last build completed, took 297ms
[INFO] Running build completed, took 4.0s
[INFO] Caching finalized dependency graph completed, took 19ms
[INFO] Succeeded after 4.1s with 0 outputs (3 actions)

┏━━ Generated dart files
┃  ┣━━ 🎉 /Users/user/freezer/lib/sample/product.dart
┃  ┣━━ 🎉 /Users/user/freezer/lib/sample/product.freezed.dart
┃  ┣━━ 🎉 /Users/user/freezer/lib/sample/product.g.dart
┃  ┣━━ 🎉 /Users/user/freezer/lib/sample/shop.dart
┃  ┣━━ 🎉 /Users/user/freezer/lib/sample/shop.freezed.dart
┃  ┗━━ 🎉 /Users/user/freezer/lib/sample/shop.g.dart
┗━━ 6 files in 5.5022 seconds

And you can see generated dart codes in the .lib folder like below.

.
├── analysis_options.yaml
├── design
│   └── sample
│       └── shop.freezer.json
├── lib
│   └── sample
│       ├── product.dart
│       ├── product.freezed.dart
│       ├── product.g.dart
│       ├── shop.dart
│       ├── shop.freezed.dart
│       └── shop.g.dart
├── pubspec.lock
└── pubspec.yaml

1.3. Reference for Identifiers

freezer provides useful identifiers for creating model objects from JSON files.

These identifiers can be used to automatically create classes and fields with names that differ from the field names defined in the JSON file without directly editing the model object source.

Identifier	Description	Example
.!required	The field with this identifier shall be a required field.	name.!required
.!as:	Assign an alias to a specific object defined in JSON.	product.!as:my_product
.!name:	Assign an alias to a specific field in object defined in JSON.	product.!name:my_product
.!toDateTime	Treat this field as DateTime type.	datetime.!toDateTime
.!field:	Assign an alias to specific field in enum object with value. The default field name is value.	product_type.!field:code
$	A dartdoc can be created for a specific field by tying it to a field name defined in JSON.	"$field_name": "This is a comment for field."
$$	A dartdoc can be created for a specific object by tying it to an object name defined in JSON.	"$$object_name": "This is a comment for a object (class)."

Also, you can combine multiple identifiers for specific fields and objects like below.

{
  "shop": {
    "products.!as:product.!name:my_products": [
      {
        "name": "Chocolate",
        "price": 5.99
      }
    ]
  }
}

1.3.1. Make Specific Fields Required

With !required identifier, you can make specific fields required
And fields without this identifier are output as nullable, such as int? and String?.

1.3.1.1. From

{
  "shop": {
    "name.!required": "My Fancy Shop"
  }
}

1.3.1.2. To

import 'package:freezed_annotation/freezed_annotation.dart';

part 'shop.freezed.dart';
part 'shop.g.dart';

@freezed
class Shop with _$Shop {
  const factory Shop({
    required String name,
  }) = _Shop;

  factory Shop.fromJson(Map<String, Object?> json) => _$ShopFromJson(json);
}

1.3.2. Assign an Alias for Objects

With .!as: identifier, you can assign an alias to a specific object defined in JSON.

This identifier is useful when you want to rename an object defined in JSON that has a list structure.
The field names in JSON are often plural when the JSON object has a list structure, but it's more convenient to use the singular form when representing it as a class.

When this identifier is used, only the object name is assigned an alias, and the original name is used for the field name. If you want to change the name of the fields, use in combination with the !name: identifier.

1.3.2.1. From

{
  "shop": {
    "products.!as:product": [
      {
        "name": "Chocolate",
        "price": 5.99
      }
    ]
  }
}

1.3.2.2. To

import 'package:freezed_annotation/freezed_annotation.dart';

import 'product.dart';

part 'shop.freezed.dart';
part 'shop.g.dart';

@freezed
class Shop with _$Shop {
  const factory Shop({
    List<Product>? products,
  }) = _Shop;

  factory Shop.fromJson(Map<String, Object?> json) => _$ShopFromJson(json);
}

import 'package:freezed_annotation/freezed_annotation.dart';

part 'product.freezed.dart';
part 'product.g.dart';

@freezed
class Product with _$Product {
  const factory Product({
    String? name,
    double? price,
  }) = _Product;

  factory Product.fromJson(Map<String, Object?> json) =>
      _$ProductFromJson(json);
}

1.3.3. Assign an Alias for Fields

With .!name: identifier, you can assign an alias to a specific field in object defined in JSON.

When this identifier is used, only the field name is assigned an alias, and the original name of the object or file is used. If you want to change the name of the object, use in combination with the !as: identifier.

1.3.3.1. From

{
  "shop": {
    "products.!as:product.!name:my_products": [
      {
        "name": "Chocolate",
        "price": 5.99
      }
    ]
  }
}

1.3.3.2. To

// ignore_for_file: invalid_annotation_target

import 'package:freezed_annotation/freezed_annotation.dart';

import 'product.dart';

part 'shop.freezed.dart';
part 'shop.g.dart';

@freezed
class Shop with _$Shop {
  const factory Shop({
    @JsonKey(name: 'products') List<Product>? myProducts,
  }) = _Shop;

  factory Shop.fromJson(Map<String, Object?> json) => _$ShopFromJson(json);
}

1.4. Advanced Usage

1.4.1. Enum Generation and Mapping

It would be very convenient if constants with certain regularities could be grouped together and held as an Enum.
And fortunately, freezer supports automatic generation of Enums based on JSON files and automatic mapping to model objects.

Don't worry, it's very easy!

At first, in addition to the model object definition on JSON, one must add a hierarchy to represent Enum.

As shown in the following JSON file, the "models" object in the root should be the JSON object of the model object you are familiar with so far. Then, define the enums to be generated in the root "enums" object like following.

{
  "models": {
    "shop": {
      "name.!required": "My Fancy Shop",
      "products.!as:product": [
        {
          "name": "Chocolate",
          "price": 5.99,
          "product_type": "sweet",
          "country": "belgium"
        }
      ]
    }
  },
  "enums": {
    "product_type": [
      {
        "$": "It represents the sweet product.",
        "name": "sweet",
        "value": 0
      },
      {
        "$": "It represents the juice product.",
        "name": "juice",
        "value": 1
      }
    ],
    "country": ["germany", "belgium"],
    "$$country": "It represents the countries.",
  }
}

In the above example, the two Enums are defined. It's product_type and country. The principle of mapping a field in a model object to an Enum is very simple: simply match the name of the field in the model object with the name of the Enum.

$ and $$country are fields representing dartdocs, respectively. $ is a dartdoc for a specific element of Enum, and fields beginning with $$ are dartdoc for a specific Enum object by name.

For example, the product_type field of the "products" object in the "models" object will automatically map to the "product_type" Enum in the "enums" object.

Then let's run the dart run freezer:main command using this example JSON! You can get following results.

import 'package:json_annotation/json_annotation.dart';

enum ProductType {
  /// It represents the sweet product.
  @JsonValue(0)
  sweet(0),

  /// It represents the juice product.
  @JsonValue(1)
  juice(1);

  /// The value of this enum element.
  final int value;

  const ProductType(this.value);
}

/// It represents the countries.
enum Country {
  germany,
  belgium,
}

import 'package:freezed_annotation/freezed_annotation.dart';

import 'country.dart';
import 'product_type.dart';

part 'product.freezed.dart';
part 'product.g.dart';

@freezed
class Product with _$Product {
  const factory Product({
    String? name,
    double? price,
    ProductType? productType,
    Country? country,
  }) = _Product;

  factory Product.fromJson(Map<String, Object?> json) =>
      _$ProductFromJson(json);
}

1.4.2. External Directory Reference

For example, there may be situations where you want to generate common objects in an external directory and reuse the common objects generated in that external directory.

In such cases, references feature is very useful. By defining a "references" object in the root of the JSON file, you can refer to objects in external directories.

For example, consider the following structure.

.
├── design
│   └── sample
│       ├── common
│       │   └── common.freezer.json
│       └── shop.freezer.json
└── lib

And common.freezer.json has json structure like below.

{
  "models": {
    "manager": {
      "id": 12345,
      "name": "Jason"
    }
  },
  "enums": {
    "country": ["germany", "belgium"]
  }
}

And shop.freezer.json has json structure like below.

{
  "models": {
    "shop": {
      "name.!required": "My Fancy Shop",
      "products.!as:product.!name:my_products": [
        {
          "name": "Chocolate",
          "price": 5.99,
          "country": "belgium"
        }
      ],
      "manager": {
        "id": 12345,
        "name": "Jason"
      }
    }
  }
}

You can find common terms in the fields defined in common.freezer.json and in shop.freezer.json. Yes, it's manager object and country enum.

Then, you can link these objects between different files by using "references". Let's add "references" in shop.freezer.json like below.

{
  "models": {
    "shop": {
      "name.!required": "My Fancy Shop",
      "products.!as:product.!name:my_products": [
        {
          "name": "Chocolate",
          "price": 5.99,
          "country": "belgium"
        }
      ],
      "manager": {
        "id": 12345,
        "name": "Jason"
      }
    }
  },
  "references": {
    "manager": "./common",
    "country": "./common/"
  }
}

You can see outputs like below if you run dart run freezer:main.

.
├── design
│   └── sample
│       ├── common
│       │   └── common.freezer.json
│       └── shop.freezer.json
└── lib
    └── sample
        ├── common
        │   ├── country.dart
        │   ├── manager.dart
        │   ├── manager.freezed.dart
        │   └── manager.g.dart
        ├── product.dart
        ├── product.freezed.dart
        ├── product.g.dart
        ├── shop.dart
        ├── shop.freezed.dart
        └── shop.g.dart

import 'package:freezed_annotation/freezed_annotation.dart';

import './common/manager.dart';
import 'product.dart';

part 'shop.freezed.dart';
part 'shop.g.dart';

@freezed
class Shop with _$Shop {
  const factory Shop({
    required String name,
    @JsonKey(name: 'products') List<Product>? myProducts,
    Manager? manager,
  }) = _Shop;

  factory Shop.fromJson(Map<String, Object?> json) => _$ShopFromJson(json);
}

import 'package:freezed_annotation/freezed_annotation.dart';

import './common/country.dart';

part 'product.freezed.dart';
part 'product.g.dart';

@freezed
class Product with _$Product {
  const factory Product({
    String? name,
    double? price,
    String? productType,
    Country? country,
  }) = _Product;

  factory Product.fromJson(Map<String, Object?> json) =>
      _$ProductFromJson(json);
}

1.5. Contribution 🏆

If you would like to contribute to freezer, please create an issue or create a Pull Request.

There are many ways to contribute to the OSS. For example, the following subjects can be considered:

• There are request parameters or response fields that are not implemented.
• Documentation is outdated or incomplete.
• Have a better way or idea to achieve the functionality.
• etc...

You can see more details from resources below:

• Contributor Covenant Code of Conduct
• Contribution Guidelines
• Style Guide

Or you can create a discussion if you like.

Feel free to join this development, diverse opinions make software better!

1.6. Support ❤️

The simplest way to show us your support is by giving the project a star at GitHub and Pub.dev.

You can also support this project by becoming a sponsor on GitHub:

1.7. License 🔑

All resources of freezer is provided under the BSD-3 license.

Copyright 2022 Kato Shinya. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided the conditions.

Note
License notices in the source are strictly validated based on .github/header-checker-lint.yml. Please check header-checker-lint.yml for the permitted standards.

1.8. More Information 🧐

freezer was designed and implemented by Kato Shinya (@myConsciousness).

• Creator Profile
• License
• API Document
• Release Note
• Bug Report