Creating Immutable Functional Style Dart Model Objects based on JSON or JSON schemas

Flutter is opinionated about using a functional programming model that includes immutable data objects.  I've found that we tend to ignore that whole immutable thing when dealing with JSON data.  

Projects can be loose when handling incoming JSON data and how it is accessed, sprinkling string-style map keys across the codebase.  We can reduce that tendency by providing models to eliminate the string keys and mutable models to stop people from directly manipulating maps of strings.

Some languages are functional only.  Other languages have no way of generating immutable objects. In those cases, we just end up with objects that can be easily converted into and out of JSON structures and strings.

I'm working in Dart right now so the rest of this will be Dart samples

Modeling Longitude and Latitude Using the JSON Schema

Let's pick something simple as an example.  We're going to use this Latitude and Longitude JSON Schema that follows the schema definition style from http://json-schema.org/draft-06/schema#.  A coordinate on the earth's surface is represented by a longitude and a latitude.

{
    "id": "http://json-schema.org/geo",
    "$schema": "http://json-schema.org/draft-06/schema#",
    "description": "A geographical coordinate",
    "type": "object",
    "properties": {
      "latitude": {
        "type": "number"
      },
      "longitude": {
        "type": "number"
      }
    }
  }

Watch the video

Incrementally creating the right kind of Dart Model Class

I generated these files using https://app.quicktype.io/ sourced from this GitHub repository  I have no interest in the tool other than it saved me a few days of coding.

Starting with just property definitions


Enabling just Types Only results in
class Coordinate {
    double latitude;
    double longitude;

    Coordinate({
        this.latitude,
        this.longitude,
    });
}

Making the objects immutable, unchangeable after creation.

We want to operate in a Functional Programming model with immutable objects. Enabling Make all properties required and Make all properties final results in. Note the added final and required.

class Coordinate {
    final double latitude;
    final double longitude;

    Coordinate({
        required this.latitude,
        required this.longitude,
    });

}

Simplify creating mutated copies of the data.

Information changes.  This means we need a way of creating new model objects that have one or more property differences from the object they were created from.

We want to make it easy on the programmer so we enable Generate CopyWith that creates a new instance by making a copy with the requested changes applied. Note the added CopyWith() method.

class Coordinate {
    final double latitude;
    final double longitude;

    Coordinate({
        required this.latitude,
        required this.longitude,
    });

    Coordinate copyWith({
        double? latitude,
        double? longitude,
    }) =>
        Coordinate(
            latitude: latitude ?? this.latitude,
            longitude: longitude ?? this.longitude,
        );
}

We're all about serializing and deserializing our model with JSON

The next step is to add JSON serialization and deserialization support.  quicktype can generate global functions or static methods on the class. I'm a classy sort of person so I'll do the latter by turning off the Types only selector.  We get a class that can 

  1. Create a model instance from a JSON string.
  2. Create a model instance from a Map<String, dynamic>
  3. Create a JSON data structure from a model object instance.
  4. Create a JSON string from a model object instance.

import 'dart:convert';

class Coordinate {
    final double latitude;
    final double longitude;

    Coordinate({
        required this.latitude,
        required this.longitude,
    });

    Coordinate copyWith({
        double? latitude,
        double? longitude,
    }) =>
        Coordinate(
            latitude: latitude ?? this.latitude,
            longitude: longitude ?? this.longitude,
        );

    factory Coordinate.fromRawJson(String str) => Coordinate.fromJson(json.decode(str));

    String toRawJson() => json.encode(toJson());

    factory Coordinate.fromJson(Map<String, dynamic> json) => Coordinate(
        latitude: json["latitude"]?.toDouble(),
        longitude: json["longitude"]?.toDouble(),
    );

    Map<String, dynamic> toJson() => {
        "latitude": latitude,
        "longitude": longitude,
    };
}

Using Annotations to Generate Serialization Code

As an alternative... We can reduce the boiler-plate code by using annotations to help us generate the serialization code as part of the build process. 

import 'package:meta/meta.dart'; import 'package:json_annotation/json_annotation.dart'; import 'dart:convert'; part 'coordinate.g.dart'; @JsonSerializable() class Coordinate { @JsonKey(name: "latitude") final double latitude; @JsonKey(name: "longitude") final double longitude; Coordinate({ required this.latitude, required this.longitude, }); Coordinate copyWith({ double? latitude, double? longitude, }) => Coordinate( latitude: latitude ?? this.latitude, longitude: longitude ?? this.longitude, ); factory Coordinate.fromJson(Map<String, dynamic> json) => _$CoordinateFromJson(json); Map<String, dynamic> toJson() => _$CoordinateToJson(this); }

Endgame

Real-world JSON schemas and modeling are a lot more complicated than this simple example.  There are a variety of tools out there.  At the time of this article, I'd recommend exploring JSON modeling including functional programming if your language supports it.  I used https://app.quicktype.io but there are other tools out there.

Revision History

Created 2023/09

Popular posts from this blog

A full context breaks three local models, each in a different way - 7

Image
In freemansoft/Flutter-AdaptiveCards a demonstration Dart chat server hands a question to a local Ollama model. It asks for the answer as Adaptive Card JSON, a strict, closed-vocabulary schema that a Flutter client renders as interactive UI rather than as text. A set of probes in that repository puts identical questions to different local models. Probe context_fill_probe.dart  produced every figure in this article. It runs 25 test cases, one question each. A test case passes only if the reply used an element type that would answer the question. Every other probe in that set had been asking into a nearly empty window. That window holds a system prompt, one question, and at most a short canned exchange showing the model the shape of a card. The literature documents that a long context degrades model behavior. What it does to a model's adherence to an output format is measured less often. The test probe simulates a long conversation by filling three q...
Read more

Installing the RNDIS driver on Windows 11 to use USB Raspberry Pi as network attached

Image
I do a lot of my development and configuration via ssh into my Raspberry Pi Zero over the RNDIS connection. Some models of the Raspberry PIs can be configured with  gadget drivers  that let the Raspberry pi emulate different devices when plugged into computers via USB. My favorite gadget  is the network profile that makes a Raspberry Pi look like an RNDIS-attached network device.  All types of network services travel over an RNDIS device without knowing it is a USB hardware connection. A Raspberry Pi shows up as a Remote NDIS (RNDIS) device when you plug the Pi into a PC or Mac via a USB cable. The gadget  in the Windows Device Manager picture shows this RNDIS Gadget connectivity between a Windows machine and a Raspberry Pi. The Problem Windows 11 and Windows 10 no longer auto-installs the RNDIS driver that makes magic happen. Windows recognizes that the Raspberry Pi is some type of generic USB COM device. Manually running W indows Update  or  Upd...
Read more

We tried 14 levers to get reliable SDUI card JSON from a local LLM model - 2

Image
In freemansoft/Flutter-AdaptiveCards a demonstration Dart chat server hands a question to a local Ollama model, asks for the answer as Adaptive Card JSON, and a Flutter client app renders the reply. Everything below is an attempt to make that card generation more reliable and more faithful to what was asked. The figures are transcribed from ModelBehavior.md , a lab notebook in that repository. Terms used in this article The first two describe the ledger, the rest name what the levers changed and how each was scored. Probe and flag names are the repository's own. Term What it means here Lever One change tried against the card failures, recorded in the notebook's tuning ledger with its outcome and evidence. Fourteen are counted here. Kind The layer of the system a lever touches: context assembly, meaning what precedes the question in the mes...
Read more