JSON→URL

About

RFC8259 describes the JSON data model and interchange format, which is widely used in application-level protocols including RESTful APIs. It is common for applications to request resources via the HTTP POST method, with JSON entities. However, POST is suboptimal for requests which do not modify a resource's state. JSON→URL defines a text format for the JSON data model suitable for use within a URL/URI.

Code

JSON→URL is language agnostic. A formal specification defines the grammar, and class/function libraries implement an idiomatic interface.

Examples

A picture is worth 1e3 words
JSONJSON→URL
truetrue
falsefalse
nullnull
{"Hello":"World!"}(Hello:World!)
[1,2.0,-3e7](1,2.0,-3e7)
{"key":"value","nested":["array","of","strings"]} (key:value,nested:(array,of,strings))
"Ben & Jerry's"Ben+%26+Jerry's
"true"'true'

Basic Rules

The primary goal of JSON→URL is to make the resulting URL readable — or at least as readable as possible — and therefore meaningful to the user.

The spec outlines the complete format, which includes a number of optimizations to increase readability and decrease size, but the basic concept can be understood by applying the following rules to JSON text.

Specification

The JSON→URL specification defines the complete grammar.

Related Work

The following libraries (written by others) provide similar or related functionality.

jsurl
A JavaScript library similar in goal to JSON→URL. It uses tilde as an escape sequence for literals and to differentiate between open object and open array.
json-url
A JavaScript library to serialize/deserialize arbitrary JSON text to/from a clob suitable for use in a URL query string. The primary goal is to optimize for size rather than readability. It offers several compression options and looks quite complete.
json2url
A JavaScript library for encoding and decoding JavaScript objects to/from a URL compatible string. The format appears to be compatible with classic CGI query strings (i.e. x-www-form-unlencoded).
jsonurl
A Python library for serializing and deserializing Python data structures to/from a URL query string.
JSONCrush
A JavaScript library for compressing URI encoded JSON text.
Rison
A specification similar in goal to JSON→URL. The original website is defunct, however, an archived copy is available via archive.org. The original JavaScript implementation is no longer maintained, however, there are some forks.