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.
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-py - Python implementation (GitHub, PyPI, libraries.io)
|"Ben & Jerry's"||Ben+%26+Jerry's|
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.
}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
"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
%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
\ is not allowed in a URL query string.
The JSON→URL specification defines the complete grammar.
The following libraries (written by others) provide similar or related functionality.
- A Python library for serializing and deserializing Python data structures to/from a URL query string.