json2object 2.3.0

Initialize object directly from json with macro

Released 2017-04-23.

To install, run:

haxelib install json2object 2.3.0

See using Haxelib in Haxelib documentation for more information.

Current version2.3.0
StatisticsInstalled 67 times
Tags cross, json, macro


Build Status

json2object - intialized object directly from json

This library uses macro and a typed position aware JSON parsing (hxjsonast : https://github.com/nadako/hxjsonast/) to create a parser from json to every supportable object.

Incorrect json files or mismatched between the object and the json will yield warnings or exceptions, with information on the position of the problematic parts.

Requires at least haxe 3.3.0-rc.1.


haxelib install json2object


Using the parser

var parser = new json2object.JsonParser<Cls>(); // Creating a parser for Cls class
parser.fromJson(jsonString, filename); // Parsing a string. A filename is specified for errors management
var data:Cls = parser.data; // Access the parsed class
var warnings:Array<json2object.Error> = parser.warnings; // Access the potential warnings

It is also possible to populate an existing Array with the warnings

var warnings = new Array<json2object.Error>();
var data:Cls = new json2object.JsonParser<Cls>(warnings).fromJson(jsonString, filename);

To print the warnings you can do


Constraints in the parsing

  • Variables defined with the @:jignored metadata will be ignored by the parser.
  • Variables defined with the @:optional metadata wont trigger warnings if missing.
  • Private variables are ignored.

Supported types

  • Basic types (Int, Float, Bool, String)
  • Null and Array
  • Map with Int or String keys
  • Class (generics are supported)
  • Anonymous structure
  • Typedef alias of supported types
  • Enum values
  • Abstract over a supported type
  • Abstract enum of String, Int, Float or Bool


  • Anonymous structure variables can be defined to be loaded with a default value if none is specified in the json using the @:default metadata
typedef Struct = {
	var normal:String;

	@:default(new Map<Int, String>())
	var map:Map<Int,String>;

	@:default(-1) @:optional
	var id:Int;
  • No parser will be generated for the types String, Int, Float and Bool.

  • Variable defined as (default, null) may have unexpected behaviour on some extern classes.

  • You can alias a field from the json into another name, for instance if the field name isn't a valid haxe identifier.

typedef Struct = {
	@:alias("public") var isPublic:Bool;
class Main {
	static function main() {
		var parser = new JsonParser<Struct>();
		var data = parser.fromJson('{"public": true }', "file.json");

If multiple alias metadata are on the variable only the last one is taken into account.


With an anonymous structure:

import json2object.JsonParser;

class Main {
	static function main() {
		var parser = new JsonParser<{ name : String, quantity : Int }>();
		var data = parser.fromJson('{"name": "computer", "quantity": 2 }', "file.json");
		trace(data.name, data.quantity);

A more complex example with a class and subclass:

import json2object.JsonParser;

class Data {
	public var a:String;
	public var b:SubData;
	public var d:Array<Int>;
	public var e:Array<Map<String, String>>;
	public var f:Array<Float>;
	public var g:Array<Bool>;
	public var h:Math;

	public function new() {

class SubData {
	public var c:String;

	public function new() {

class Main {
	static function main() {
		var parser = new JsonParser<Data>();
		var data = parser.fromJson('{"a": "a", "b": {"c": "c"}, "e": [ { "c": "1" }, { "c": "2" } ], "f": [], "g": [ true ] }', "file.json");
		var warnings = parser.warnings;


		for (e in data.e) {


		for (g in data.g) {

		for (w in warnings) {
			switch(w) {
				case IncorrectType(variable, expected, pos):
				case UninitializedVariable(variable, pos):
				case UnknownVariable(variable, pos):