JSON Minus

Specification

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

Motivation

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.

Interoperability

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.

Examples

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

willconant.com

JSON Minus Specification

4 Good Things About CouchDB

Projects

couchdb-auto-views
zero-setup views and powerful query composition

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

yield-on-promise
consume promises in fibers and fibers as promises

json-minus
validate and prepare JSON Minus documents

Interests

CouchDB

Promises/A+

node-fibers

External Links

http://twitter.com/willconant

http://github.com/willconant

http://npmjs.org/~willconant

Old Blog


© 2013 Will Conant