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.
- jsonurl-java - Java implementation (GitHub, Maven)
- jsonurl-js - JavaScript implementation (GitHub, NPM, libraries.io)
- jsonurl-py - Python implementation (GitHub, PyPI, libraries.io)
Examples
| JSON | JSON→URL |
|---|---|
| true | true |
| false | false |
| null | null |
| {"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.
- JSON→URL text is limited to a subset of the characters allowed in a URL query string. All other characers must be percent encoded.
- The
[,],{, and}characters are not allowed in a URL query string so objects and arrays both begin with(and end with). - The true, false, null, and number literals look exactly like they do in JSON.
- A string literal is quoted between two
'characters, because"is not allowed in a URL query string. A string only needs to be quoted if it is true, false, null, or looks like a number. - Literal whitespace is not allowed in a URL query string. A single
space may be encoded with a
+character. Spaces may only appear where a string literal is allowed, and they are always meaningful.
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.