Latest News

(2009-08-06) We've changed the JSON4Lua and JSONRPC4Lua licence from the GPL to the MIT licence, like Lua itself.

The 0.9.20 release fixes a bug in Lua 5.1 operation, introduces a json.null value to force null values in JSON encodings, improves performance (over 50% faster on some tests), and permits /* comments */ in the JSON string being decoded.


JSON4Lua and JSONRPC4Lua implement JSON (JavaScript Object Notation) encoding and decoding and a JSON-RPC-over-http client for Lua.

JSON is JavaScript Object Notation, a simple encoding of Javascript-like objects that is ideal for lightweight transmission of relatively weakly-typed data. A sub-package of JSON4Lua is JSONRPC4Lua, which provides a simple JSON-RPC-over-http client and server (in a CGILua environment) for Lua. Please seen the documentation below for JSONRPC4Lua.


JSON4Lua is licensed under the MIT Consortium licence like Lua itself. Please see LICENCE.txt for details.


JSON4Lua is a pure-Lua module that is Lua 5.0 compatible (if you have compat-5.1 for Lua 5.0). JSON4Lua also works (perfectly, I hope) under Lua 5.1, which is where I largely use it nowadays. Since Lua is platform independent, so is JSON4Lua.

The JSON4RPC sub-module requires Lua Socket 2.0. It uses socket.http for for the RPC over http connection. Socket 2.0 includes ltn12, which is also used by JSON4RPC.

To use json.rpcserver you need a CGILua enabled webserver. However, a quick patch is required in CGILua 5.0 to support JSON-RPC.


JSON4Lua is hosted on LuaForge.
0.9.306 August 2009 Changed to MIT Licence.
0.9.204 January 2006 Introduction of local Lua functions for private functions (removed _ function prefix).
Fixed Lua 5.1 compatibility issues.
Introduced json.null to have null values in associative arrays.
Performance improvement (more than 50% on some tests) through table.concat rather than .. operator.
json.decode now ignores /* */ comments in the JSON string.
0.9.1020 December 2005 Fixes bug with array representation when nil / null values occur in the array.
Adds content-type header of text/plain to JSON RPC http requests.
Introduces json.rpcserver module with simple JSON RPC enablement for Lua objects.
Moved the json.lua file into the json directory. Ensure, therefore, that your LUA_PATH contains a module-finding form like LUA_PATH = c:\proj\lua\?\?.lua;?.lua.
0.9.01 19 December 2005 Minor corrections to documentation.
0.9.00 19 December 2005 First release


As of version 0.9.10, all the JSON4Lua files are contained in the json subdirectory in the distribution zip.

Simply copy the json subdirectory so that it is in your Lua path.

Ensure that your LUA_PATH variable permits module resolution of the form ?/?.lua.


Using Windows

Under Windows, set your Lua path as (my Lua installation is in c:\proj\lua\):

set LUA_PATH=c:\proj\lua\?.lua;c:\proj\lua\?\?.lua;?.lua

For compat-5.1.lua to start when Lua starts (if you're using Lua 5.0), you also need:

set LUA_INIT=@c:\proj\lua\compat-5.1.lua

You probably also want to set your library path:

set LUA_CPATH=c:\proj\lua\lib\?.dll;?.dll

Usage & Reference

The following functions in JSON4Lua and JSONRPC4Lua are of interest:

string json.encode( lua_object )
Returns the Lua object JSON encoded into a string.


json = require("json")
print (json.encode( { 1, 2, 'fred', {first='mars',second='venus',third='earth'} } ))


[1,2,"fred", {"first":"mars","second":"venus","third","earth"}]

lua_object json.decode( json_string )
Decodes the JSON encoded data structure, and returns a Lua object with the appropriate data.


json = require("json")
testString = [[ { "one":1 , "two":2, "primes":[2,3,5,7] } ]]
o = json.decode(testString)
print ("Primes are:")


one		1
two		2
primes		table: 0032B928
Primes are:
1		2
2		3
3		5
4		7
Returns a unique value that will be encoded as a null in a JSON encoding.

This is necessary in one situation. In Lua, if a key in a table has a nil value, the key is simply discarded (since any non-existent key has a nil value). The encoding of arrays has been built to manage this nil-values in arrays, but associative arrays provide a problem. Consider:

t = { user="test", password=nil }
Since Lua simply discards the password key, JSON4Lua encodes this as the JSON string
If, for some reason, your JSON RPC Server requires a defined null value, use the following code:
t = { user="test", password=json.null }
This will now correctly encode to:
Incidentally, json.null is simply a function that returns itself, so that you can use either json.null or json.null() as you fancy.
result, error json.rpc.call ( url, method, ...)
Calls the named method on the given url with the arg parameters. Returns the result and the error. If error is nil, no error occurred.


require ("json.rpc")
result, error = json.rpc.call("http://jsolait.net/testj.py","echo","Test echo!")


Test echo!
proxyServer = json.rpc.proxy (url)
Creates a proxy server object on which JSON-RPC calls can be made. Each call will return the result, error. If error is nil, no error occurred.


require ("json.rpc")
server = json.rpc.proxy("http://jsolait.net/testj.py")
result, error  = server.echo('Test echo!')


Test echo!
json.rpcserver.serve(object[, packReturn])
Handles an incoming CGILua request as a JSON RPC request and serves the request from the given object.

The optional packReturn parameter, if set true, will, if the requested method returns more than one value, pack these returned values into an array. If only a single value is returned, it is not packed into an array. If packReturn is false (or not set), only the first return value from the requested method will be returned. This is necessitated since the JSON protocol does not permit a method call to return more than a single value.

serve returns nothing.


-- jsonrpc.lua
-- Installed in a CGILua webserver environment (with necessary CGI Lua 5.0 patch)
require ('json.rpcserver')

-- The Lua class that is to serve JSON RPC requests
local myServer = {
  echo = function (msg) return msg end,
  average = function(...)
    local total=0
    local count=0
    for i=1, table.getn(arg) do
      total = total + arg[i]
      count = count + 1
    return { average= total/count, sum = total, n=count }

An example of using this JSON RPC server from a Lua file:
require ('json.rpc')
local server = json.rpc.proxy('http://www.myserver.com/jsonrpc.lua')
table.foreach(server.average(10,15,23), print)
average	16
sum	48
n	3

History & Roadmap

The downloads sections details the versions and their related histories. I will wait for Lua 5.1 to be final (expected late January) before making the JSON4Lua module beta. If no serious bugs or objections are encountered, I will make the module 1.0 on 1 April 2006 (to coincide with April Fool's day!)