About
RFC8259 describes theJSON data model and interchange format, which iswidely used inapplication-levelprotocols includingRESTfulAPIs. It iscommon for applications to request resources via theHTTP POST method,with JSONentities.However, POST is suboptimal for requests which do not modify a resource'sstate. JSON→URL defines a text format for the JSONdata model suitable for use within aURL/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.
