agnes API

agnes is a mature javascript library for converting between json and csv.

Include agnes in your page like this.

<script type="text/javascript" src="agnes.js"></script>

If you're very clever then you might use a loader or something.

Get agnes here:

free source code!

She hasn't been minified: I leave that as an exercise for the reader.

Her unit tests are here, and a demonstration of her prowess is here. Her API is described below.

The girl herself is comprised of the following functions, which are documented (with executable examples) below.

function purpose
csvToJson Convert csv into an array of json objects.
jsonToCsv Convert a json object (or json array) into csv.
rowDelimiter Detect the line separator used by the current browser


agnes expects you to know these terms:

function: csvToJson

agnes.csvToJson(csvString, rowDelim, fieldDelim)

Parameters: csvString, [rowDelim,] [fieldDelim,] [qualifier]

Converts a piece of separated text into an array of Json objects. Assumes the first row of the csv is the name of the properties to create (i.e. assumes the csv includes a row of column headers).

Standard escaping rules are applied:

The first parameter, csvString, is the separated text you wish to translate into Json.

The last three parameters (rowDelimiter, fieldDelimiter and qualifier) are optional. If you don't provide them, agnes is crafty when she works out what you want.

If no rowDelimiter is provided she will use whatever the current browser uses as a line separator. She performs a little feature detection to make sure she gets it right. You can use agnes's rowDelimiter() function to see what delimiter she will use by default on a given browser.

If you don't provide a field delimiter, agnes assumes you want a comma. You do want a comma don't you?

And for a qualifying character, agnes assumes you want a double-quote.


var csvData, jsonData;
csvData = "Name,Age\nJack,12\nJohn,5";
jsonData = agnes.csvToJson(csvData);
alert(JSON.stringify(jsonData,null,' '));

Or, if you're using custom delimiters, just specify them (row delimiter, then column delimiter)

var myCSV = "Name|Age;Jack|12;John|5;";
var myJSON = agnes.csvToJson(myCSV, ";", "|");
alert(JSON.stringify(myJSON,null,' '));

function: jsonToCsv

agnes.jsonToCsv(objects, rowDelim, fieldDelim, qualifier)

Parameters: objects, [rowDelim,] [fieldDelim,] [qualifier]

Converts a json object (or array of json objects) into a separated string. You can optionally provide the row delimiter, field delimiter and qualifying character. If you omit these parameters, sensible defaults are assumed.

The first parameter can be a single Json object, as in the first example, or an array of Json objects, as in the second example. agnes understands.


alert(agnes.jsonToCsv({ "name" : "Mary" }));

agnes is not concerned with case sensitivity.

var jsonData, csvData;
jsonData = [{ "name" : "Mary", "age" : 81, "Occupation": "Seamstress" }, { "Name" : "Alice", "Age" : 403, "Occupation" : "Governess" }];
csvData = agnes.jsonToCsv(jsonData);

Here's an example of using those last three parameters to specify the row delimiter, the field delimiter, and how the fields are qualified.

var jsonData, csvData;
jsonData = [{ "name" : "fred", "age" : 22}];
csvData = agnes.jsonToCsv(jsonData, "\r\n", "|", '"');

If you are sending in an array of Json objects, agnes expects that each object has the same properties as the first object, and that those properties are in the same order each time. Furthermore, no property is itself an object. Otherwise agnes will be most perturbed. For example...

var jsonData, csvData;
jsonData = [{ "name" : "Mary", "age" : 96, "height" : "4ft3", "drunk" : null },
{ "name" : "Alice", "height" : "4ft1", "ideas" : {"political":"yes", religious: "No!"} }];
csvData = agnes.jsonToCsv(jsonData);

function: rowDelimiter


Determines the standard line ending used on your current browser. Does your current browser use just a carriage return? Or does it use a carriage return plus a line feed?

Note that agnes does not use old school 'agent' investigation, but the more mature approach of 'feature detection' -- making sure she doesn't get tricked into a wrong answer.


There's not much to show here. Just one example:

var delim = agnes.rowDelimiter();
// in order to show you the invisible characters
// in the result, i now need to escape it...
delim = delim.replace("\r","\\r");
delim = delim.replace("\n","\\n");
alert("the standard line separator on this browser seems to be... " + delim);


That's all there is to it.

Have fun.

While you're here, here's a sample for converting from Json to CSV and back again.