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 grammar, but the basic concept can be understood by applying the following rules to JSON text.

Browser Address Bar

Special consideration should be taken when using JSON→URL in a browser address bar. Some browsers may change ' to %x27, which interferes with the string literal syntax described above. To sidestep this problem JSON→URL can optionally use escape sequences in string literals, rather than relying on quotes and encoding. An escape sequence begins with !, because \ is not allowed in a URL query string.

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.
lz-string
A JavaScript library for compressing any content using an LZ-based approach. The result can be base64 encoded, which is then safe to store in a URL.