WireFormat

FlatPack JSON Wire Format

The FlatPack wire format is intended to be platform-agnostic and humane to developers building clients. While the main FlatPack server implementation is Java-based, there exist iOS, JavaScript, and Ruby clients that can read and write FlatPack-encoded graphs. The wire format is JSON-based, however the depth of the JSON parse tree is constant, regardless of the complexity of the encoded graph.

Here is a sample JSON payload entity that shows two objects, a merchant and a merchantLocation.

{
  // The data section is a map of types to arrays of property bags
  data : {
    // The property key define the type of the values in the array value
    merchant : [ {
      // Each object is identified by a UUID.
      uuid : "5ade6c3d-8ee4-4cc0-8077-80f46af2bb00",
      // Name is a simple property, and is encoded as a string
      name : "YoChoice Yogurt",
      // Reference properties are identified in the wire format by a Uuid suffix.
      // This allows simple clients to just apply a heuristic to re-link graphs.
      merchantLocationsUuid : [ "9d8d1975-3fac-48fe-abaa-e68ffe1fd430" ]
    } ],
    merchantLocation : [ {
      uuid : "9d8d1975-3fac-48fe-abaa-e68ffe1fd430",
      phone : "503-894-9179",
      // A circular reference back to the merchant
      merchantUuid : "5ade6c3d-8ee4-4cc0-8077-80f46af2bb00",
      combinedAddress : "4941 NE Fremont St",
      // Most numeric values are encoded as numbers
      distanceInMeters : 0,
      latitude : 45.5483809,
      longitude : -122.61163729999998,
      neighborhoodName : "Beaumont",
      address2 : "",
      city : "Portland",
      zip : "97213",
      address : "4941 NE Fremont St",
      state : "OR"
    } ]
  },
  // A payload may have a "root" value, in this case it's the merchantLocation
  value : "9d8d1975-3fac-48fe-abaa-e68ffe1fd430",
  // The metadata section is optional and provides an extension point for
  // adding synthetic properties to entities. Clients should not need to understand
  // the metadata contents in order to correctly interpret the data section above.
  metadata : [
    {
      "uuid" : "5ade6c3d-8ee4-4cc0-8077-80f46af2bb00",
      // The persisted flag indicates that a client may send only mutated properties
      "persistent" : true
    }
  ],
  errors : {
    "Some key" : "Some message"
  },
  warnings : {
    "Some key" : "Some message"
  }
}

A more complicated example is the ApiDescriptor in the demo-server project.