***************
JSON Serializer
***************

Code generators include a JSON serializer which will convert a target
language's representation of Stone data types into JSON. This document explores
how Stone data types, regardless of language, are mapped to JSON.

Primitive Types
===============

========================== ====================================================
Stone Primitive            JSON Representation
========================== ====================================================
Boolean                    Boolean
Bytes                      String: Base64-encoded
Float{32,64}               Number
Int{32,64}, UInt{32,64}    Number
List                       Array
String                     String
Timestamp                  String: Encoded using strftime() based on the
                           Timestamp's format argument.
Void                       Null
========================== ====================================================

Struct
======

A struct is represented as a JSON object. Each specified field has a key in the
object. For example::

    struct Coordinate
        x Int64
        y Int64


converts to::

    {
     "x": 1,
     "y": 2
    }

If an optional (has a default or is nullable) field is not specified, the key
should be omitted. For example, given the following spec::

    struct SurveyAnswer
        age Int64
        name String = "John Doe"
        address String?

If ``name`` and ``address`` are unset and ``age`` is 28, then the struct
serializes to::

    {
     "age": 28
    }

Setting ``name`` or ``address`` to ``null`` is not a valid serialization;
deserializers will raise an error.

An explicit ``null`` is allowed for fields with nullable types. While it's
less compact, this makes serialization easier in some languages. The previous
example could therefore be represented as::

    {
     "age": 28,
     "address": null
    }

Enumerated Subtypes
-------------------

A struct that enumerates subtypes serializes similarly to a regular struct,
but includes a ``.tag`` key to distinguish the type. Here's an example to
demonstrate::

    struct A
        union*
            b B
            c C
        w Int64

    struct B extends A
        x Int64

    struct C extends A
        y Int64

Serializing ``A`` when it contains a struct ``B`` (with values of ``1`` for
each field) appears as::

    {
     ".tag": "b",
     "w": 1,
     "x": 1
    }

If the recipient receives a tag it cannot match to a type, it should fallback
to the parent type if it's specified as a catch-all.

For example::

    {
     ".tag": "d",
     "w": 1,
     "z": 1
    }

Because ``d`` is unknown, the recipient checks that struct ``A`` is a
catch-all. Since it is, it deserializes the message to an ``A`` object.

Union
=====

Similar to an enumerated subtype struct, recipients should check the ``.tag``
key to determine the union variant.

Let's use the following example to illustrate how a union is serialized based
on the selected variant::

    union U
        singularity
        number Int64
        coord Coordinate?
        infinity Infinity

    struct Coordinate
        x Int64
        y Int64

    union Infinity
        positive
        negative

The serialization of ``U`` with tag ``singularity`` is::

    {
     ".tag": "singularity"
    }

For a union member of primitive type (``number`` in the example), the
serialization is as follows::

    {
     ".tag": "number",
     "number": 42
    }

Note that ``number`` is used as the value for ``.tag`` and as a key to hold
the value. This same pattern is used for union members with types that are
other unions or structs with enumerated subtypes.

Union members that are ordinary structs (``coord`` in the example) serialize
as the struct with the addition of a ``.tag`` key. For example, the
serialization of ``Coordinate`` is::

    {
     "x": 1,
     "y": 2
    }

The serialization of ``U`` with tag ``coord`` is::

    {
     ".tag": "coord",
     "x": 1,
     "y": 2
    }

The serialization of ``U`` with tag ``infinity`` is nested::

    {
     ".tag": "infinity",
     "infinity": {
      ".tag": "positive"
     }
    }

The same rule applies for members that are enumerated subtypes.

Nullable
--------

Note that ``coord`` references a nullable type. If it's unset, then the
serialization only includes the tag::

    {
     ".tag": "coord"
    }

You may notice that if ``Coordinate`` was defined to have no fields, it is
impossible to differentiate between an unset value and a value of coordinate.
In these cases, we prescribe that the deserializer should return a null
or unset value.

Compact Form
------------

Deserializers should support an additional representation of void union
members: the tag itself as a string. For example, tag ``singularity`` could
be serialized as simply::

    "singularity"

This is convenient for humans manually entering the argument, allowing them to
avoid typing an extra layer of JSON object nesting.