Crossword puzzle data in JSON format

This page is for programmers.

JSON

JSON format

JSON (JavaScript Object Notation) is not always the best data format for crosswords but it's included here as a contrast to XPF. JSON is compact and it is especially useful for client-side AJAX programmers because standard JavaScript objects describing a puzzle can easily be created. Modern browsers have JSON parsers built in to do this. Older browsers can resort to using eval().

You can see the most recent NYT puzzle in JSON format here.

JSON vs. XPF

XPF is designed to be a rich, portable, extensible, open data exchange format. JSON, at least in this implementation, has a rigid format which cannot handle unusual puzzle features, although it can completely describe almost any Across Lite puzzle. It can handle complex combinations of circles and rebus, which Across Lite can but the Across Lite text format cannot.

JSON format details

Let's look at an example. Here are three views of the same puzzle: XWord Info, XPF and JSON.

Top section

This is similar to XPF.

"title": "NY Times, Thu, Sep 11, 2008",
"author": "Caleb Madison",
"editor": "Will Shortz",
"copyright": "2008, The New York Times",
"publisher": "The New York Times",
"date": "9/11/2008",
"size": {
"rows": 15,
"cols": 15
},

Defining the grid

Since JavaScript doesn't natively support multi-dimensional arrays, the entire grid is a single array reading across a row at a time. A "." is used to indicate a block.

Note that rebus entries (like "STAR" below) are fully expanded. Display programs can accept the first letter of multi-letter answers as also correct.

"grid": [ "G", "R", "E", "W", ".", "A", "N", "A", "I", "S", ".", "L", "A", "B", "S", "L", "A", "R", "A", ".", "N", "O", "STAR", "C", "H", "."," ... ],

Numbering the grid

Grid numbers are also in a single array reading across rows. 0 means no number.

Note that this gives more flexibility than defining the grid numbers algorithmically. It also makes it easier for display programs to show the grid properly.

"gridnums": [ 1,2,3,4,0,5,6,7,8,9,0,10,11,12,13,14,0,0,0,0,15,0,0,0,0,0,16 ... ],

Circles

Circles are described using another single array reading across. 0 means no circle, 1 means include a circle here. For puzzles without these special indicators, the circles object will be null.

"circles": [ 0,0,0,0,0,0,0,1,0,0,0,0,0 ... ],

Clues

The "clues" section contains two sub-objects named "across" and "down". Each of these is an array of strings. Note these strings contain the grid number as well.

"clues": {
"across": [ "1. Waxed", "5. First name in erotica", ... ],
"down": [ "1. Ruiner of many a photo", "2. Charged", ... ],
},

Answers

The "answers" section similarly contains two sub-objects named "across" and "down". Each of these is an array of strings. Note that rebus answers like NOSTARCH below are fully expanded.

"answers": {
"across": [ "GREW", "ANAIS", "LABS", "LARA", "NOSTARCH", "EBON", ... ],
"down": [ "GLARE", "RANAT", "ERICH", "WALKOFFAME", "ANET", "NOSE", ... ],
},

Notes

The "notepad" section is only included if notes exist. It may contain HTML. This website also generates a similar "jnotes" section when appropriate but that would be considered a proprietary extension.

"notepad": "TEEN PUZZLEMAKER WEEK<br />All the daily crosswords this week... ",
"jnotes": "In my opinion, ... ",

Special characters

The only special character handling is that the double quote character " is escaped with a preceding blackslash like this: \". My serializer also escapes the forward slash, so dates look like this: 12\/25\/2010.

Coding with JSON

Server-side programs should use the richer XPF format but for access to this data from a web client through AJAX, JSON could be the best solution.

Coding by hand requires creating your own XMLHttp object. If you prefer, you can use a library like jQuery to do the work for you. Either way, you get a standard JavaScript object which you can manipulate however you want. Here are some code snippets with ideas:

var json = myXMLHttpObject.responseText;
var puzzle = eval("(" + json + ")"); // use JSON parser (or jQuery) if available

document.getElementById('title').innerHTML = puzzle.title;
document.getElementById('firstDownClue').innerHTML = puzzle.clues.down[0];

var n = 0;
for (var row = 0; row < puzzle.size.rows; row++)
  for (var col = 0; col < puzzle.size.cols; col++)
    myTable.rows[row].cells[col].innerHTML = puzzle.grid[n++];

for (var i in puzzle.answers.across)
  Do_Something_With_Each_Across_Answer(puzzle.answers.across[i]);

Sample Code

Sample 1 is a proof of concept only. It uses traditional AJAX to make an asynchronous call to the XWord Info JSON server. A full puzzle grid with grid numbers is displayed, along with Across and Down clues. A real-world implementation would require proxy code on the server to do the cross-domain call. Or rather, a real-world version would probably follow the much simpler Sample 2 pattern.

Sample 2 uses the jQuery library to simplify coding, and JSONP (JSON with Padding) to allow the XWord Info JSON server to be called from any domain. In other words, it is completely self-contained. No server code is required.

Sample 3 shows a simple way to add grids (empty or filled in) to any blog or web site. Once initial setup is done, additional grids can be added with a single line of code. Full details are provided.

Comments

Please with your questions or your suggestions for improvement. Thank you.