JSON Minus


A JSON Minus document is a JSON encoded object with the following structure:

  1. The top-level object may contain any number of properties
  2. Each property key must match /^\w+$/
  3. Each top-level property value must be a string, a number, a boolean, or an array
  4. Top-level property values must not be null
  5. Top-level array values must contain zero or more object values (sub-objects)
  6. Every sub-object in the same array must have the same property keys
  7. Each sub-object property key must match /^\w+$/
  8. Each sub-object property value must be a string, a number, or a boolean
  9. Sub-object property values must not be null


Design Consistency

JSON is very expressive. Two different people are unlikely to come up with the same JSON structure given the same data to model. JSON Minus documents conform to a narrower set of rules that promote design convergence but still allow complex data to be expressed.


While all JSON structures are easy to manipulate in JavaScript, some are unweildy in other languages. Languages like Go and Java don't allow numbers to be null. They also have clumsy support for heterogenous arrays. JSON Minus documents will always fit nicely into Go's structs and Java's classes.

Human Interface

Arbitrarily complex JSON structures are not easily mapped to user interface. JSON editors like the one in CouchDB's Futon work well for top-level properties but become clumsy for any nested data. JSON Minus documents map much more directly to a typical user interface. Top-level strings, numbers, and booleans can be presented as simple fields and checkboxes. Top-level arrays may only contain homogenous sub-objects, so they can always be presented as tables. Sub-object properties may only be strings, numbers, and booleans, so there is no need for a recursive user interface.


A Contact With Custom Fields

    "firstName" : "Will",
    "lastName"  : "Conant,
    "email"     : "will.conant@gmail.com",
    "phone"     : "801 123 1234",
    "address1"  : "123 Place",
    "address2"  : "",
    "city"      : "Salt Lake City",
    "state"     : "UT",
    "zip"       : "84000",
    "custom"    : [
            "field" : "hometown",
            "value" : "Los Angeles"
            "field" : "diet",
            "value" : "pescetarian"

An Order With Nested Transactions

    "productID"    : "9e001cd9",
    "productName"  : "Red Shoes",
    "productCost"  : "19.95",
    "refunded"     : true,
    "transactions" : [
            "id"     : "9e002125",
            "date"   : 1368393048964,
            "type"   : "payment",
            "amount" : "19.95",
            "ref"    : ""
            "id"     : "9e00296e",
            "date"   : 1368393236871,
            "type"   : "refund",
            "amount" : "19.95",
            "ref"    : "9e002125"

comments powered by Disqus


JSON Minus Specification

4 Good Things About CouchDB


zero-setup views and powerful query composition

promise-based CouchDB library for node with no surprises (in a good way)

consume promises in fibers and fibers as promises

validate and prepare JSON Minus documents






External Links




Old Blog

© 2013 Will Conant