URL-friendly JSON
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
examples added demo page Sep 4, 2013
lib added tryParse Dec 7, 2016
test added tryParse Dec 7, 2016
.gitignore publishing again because of invalid .gitignore Nov 6, 2015
.travis.yml Update .travis.yml Nov 13, 2015
AUTHORS first commit Nov 4, 2011
README.md added tryParse Dec 7, 2016
bower.json add bower.json Sep 17, 2013
index.js beautified Sep 4, 2013
package.json publish 0.1.4 - IE 6-8 compat May 23, 2016



JSURL is an alternative to JSON + URL encoding (or JSON + base64 encoding). It makes it handy to pass complex values via URL query parameters.

JSURL has been designed to be:

  • Compact: its output is much more compact than JSON + URL encoding (except in pathological cases). It is even often slightly more compact than regular JSON!
  • Readable: its output is much more readable than JSON + URL encoding.
  • Foolproof: its output only contains characters that are unaffected by URL encoding/decoding. There is no risk of missing a URL encoding/decoding pass, or of messing up a JSURL string by applying an extra URL encoding or decoding pass.
  • Easy to generate and parse


Think of it as JSON with the following changes:

  • Curly braces ({ and }) replaced by parentheses (( and ))
  • Square brackets ([ and ]) replaced by (~ and )
  • Property names unquoted (but escaped -- see below).
  • String values prefixed by a single quote (') and escaped
  • All other JSON punctuation (colon : and comma ,) replaced by tildes (~)
  • An extra tilde (~) at the very beginning.

Property names and string values are escaped as follows:

  • Letters, digits, underscore (_), hyphen (-) and dot (.) are preserved.
  • Dollar sign ($) is replaced by exclamation mark (!)
  • Other characters with UNICODE value <= 0xff are encoded as *XX
  • Characters with UNICODE value > 0xff are encoded as **XXXX



{"name":"John Doe","age":42,"children":["Mary","Bill"]}

JSON + URL encoding:





var JSURL = require("jsurl");

str = JSURL.stringify(obj);
obj = JSURL.parse(str);

// return def instead of throwing on error
obj = JSURL.tryParse(str[, def]);


The easiest way to install jsurl is with NPM:

npm install jsurl


This work is licensed under the MIT license.