ipuz

Version 1.0

This is an archived version of the ipuz 1.1 spec, preserved for historical purposes. This copy contains one change from the original 1.1 spec. Shortly after 1.1 was finalized, JSONP was deprecated for security reasons. This is indicated with struckout text in the specification and all examples have been changed to be in JSON, not JSONP, format.

This specification defines the ipuz data format for representing puzzles. The ipuz format is designed to meet the following goals:

• Provide a simple, clean, consistent, and free industry standard format for representing puzzles.
• Provide an implementation-independent format.
• Provide a format that is easy to work with in code, for both creation and usage.
• Support the vast majority of puzzle types.
• Support significant puzzle variants.
• Support extensibility for company-specific information and variants.
• Support single puzzles (as a file, download, or as part of a larger file).

The following are non-goals:

• Facilitate editing data by hand.
• Maintain backward compatability with any previous common puzzle formats.
• Support every imaginable puzzle.
• Encryption of solutions within the data format (however, solution verification is supported and an entire puzzle could be encrypted).

The ipuz format is free to use in puzzle data and in software, and will always remain free. The ipuz trademarks are free to use for puzzles and software that conform to the standard. This specification is free to use under a Creative Commons license. Please see the bottom of this document for complete details.

© Copyright 2011 Puzzazz

Supporters

A current list of supporting companies, software and web sites can be found here.

Kinds of Puzzles

The ipuz format is based on the concept of groups of puzzles, called kinds or PuzzleKinds. Each kind of puzzle defines the semantics of the puzzles in the group.

Each PuzzleKind is specified by a Uniform Resource Identifier (URI), similar to how XML namespaces are defined. For example, the PuzzleKind for crosswords is http://ipuz.org/crossword. This means that a PuzzleKind looks like a URL and each unique kind defines a particular set of puzzles.

PuzzleKinds are required to be valid URLs, but they do not have to be resolvable. However, URLs must be owned by the author of the PuzzleKind, or be an approved PuzzleKind on ipuz.org. The convention is that the location referenced by the URL contains a human-readable description of the PuzzleKind, a definition of the data in a puzzle of that PuzzleKind, and an example. These files may be plain text, HTML or XHTML. Such documentation provides assistance to developers encountering a PuzzleKind they have not seen before.

Fields introduced or changed in an incompatible way after the initial version of a PuzzleKind should be marked with a version number in the documentation. If the definition of a field is changed in an incompatible way, then the PuzzleKind version number must be incremented. Likewise, if a field is added to the definition, and ignoring that field will result in an incorrect presentation of a puzzle that uses the field, the PuzzleKind version number must be incremented. If a new field can be safely ignored, then the version number does not need to be incremented (and probably should not be).

It is anticipated that it will be useful to have machine-readable descriptions of PuzzleKinds in these pages and that will be investigated as they are created.

Each PuzzleKind URI is independent of all other URIs. However, it is the convention that URIs which are nested within other URIs are used for subordinate kinds of puzzles. For example, http://ipuz.org/crossword/crypticcrossword defines cryptic crosswords, which are considered a subset of crosswords.

A kind specification in a puzzle normally ends with a fragment which defines the version of the PuzzleKind in use. For example, http://ipuz.org/crossword#1. Programs dealing with ipuz data can use the URIs of a puzzle's kinds to understand the semantics of the puzzle, which are not always completely defined by the puzzle type and options. The version number allows the program to determine if it can properly read the puzzle. When writing a puzzle, you should use the lowest version number that is compatible with the features you are using. A puzzle may use features that are defined in later versions if they can be safely ignored.

The following major PuzzleKind are currently defined:

The ipuz.org web site contains a number of PuzzleKind pages for you to reference and additional pages will be created over time. You are free to create additional PuzzleKinds, but you should only create new URIs under domains that you control (or under which you have permission to create pages). If you create a page for your new PuzzleKind, you may use any format that is convenient for you, but you may find it convenient to model it after the pages on ipuz.org. Note that you do not need to create a new PuzzleKind for every puzzle variant or trick. Instead, it is recommended that you create new PuzzleKinds when you create a significant variant with different semantics, particularly those which existing programs will not handle properly.

To request that a new PuzzleKind page be created on ipuz.org, send email to ipuz@ipuz.org.

PuzzleKinds are not organized into a taxonomy, but one may develop organically over time.

ipuz Format

A ipuz-formatted puzzle is formatted as a JSON or JSONP object. This format is easy for machines to parse and generate and JSON-to-object converters exist for almost all programming languages.

Here is a sample Crossword in ipuz format:

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword#1" ],
    "dimensions": { "width": 3, "height": 3 },
    "puzzle": [ [ { "cell": 1, "style": { "shapebg": "circle" } }, 2, "#" ],
                [ 3, { "style": { "shapebg": "circle" } }, 4 ],
                [ null, 5, { "style": { "shapebg": "circle" } } ] ],
    "solution": [ [ "C", "A", "#" ],
                  [ "B", "O", "T" ],
                  [ null, "L", "O" ] ],
    "clues": { "Across": [ [ 1, "OR neighbor" ],
                           [ 3, "Droid" ],
                           [ 5, "Behold!" ] ],
               "Down": [ [ 1, "Trucker's radio" ],
                            [ 2, "MSN competitor" ],
                            [ 4, "A preposition" ] ] }
}

While an ipuz puzzle may be either JSON or JSONP, it is recommended that JSONP format be used when puzzles are stored in files or returned dynamically from web servers, as this avoids problems with fetching puzzles across domains. If the callback function name is static instead of supplied by the browser, the a function name of ipuz is recommended.

When an ipuz puzzle is stored in a file, it is recommend that the suffix either be .ipuz or .ipuz followed by an app-specific suffix (e.g., filename.ipuz.mysolverapp).

See the bottom of this specification for more examples.

Conventions

In this document, a * before the description of a field indicates that the field is required.

There are some conventions in JavaScript and JSON-based data structures which are used in the ipuz.

The syntax { } defines a name-value dictionary. All names in the dictionary must be unique. If a name is defined twice, only the second value is used. Names are case-sensitive. In a dictionary, any unspecified value is equivalent to a null. Usually, null means that the option is unspecified. If null has a different meaning, it is stated explicitly. Additionally, when a value is specified as true/false, null also means false.

The syntax [ ] defines an array of values. The values can be of different types.

Numbers are interchangeable with strings containing just numbers (e.g., both 1 and "1" should be treated the same).

By default, a 0 (or "0") value is used to represent an empty cell or value. If the puzzle needs a cell or value of 0, it must define a different value for empty. Some programs may wish to always define an empty value.

See JSON.org for complete information on JSON.

Common Puzzle Fields

There are a number of fields which are shared by all puzzle types.

The following fields are required:

"version": "http://ipuz.org/v1"

"kind": [ PuzzleKind, ... ]

The following fields are generally optional and apply to all puzzles.

"copyright": "2011 ..."

"publisher": "HTML name"

"publication": "HTML pub info"

"url": "puzzle_url"

"uniqueid": "value"

"title": "HTML title"

"intro": "HTML text"

"explanation": "HTML text"

"annotation": "text"

"author": "HTML text"

"editor": "HTML text"

"date": "mm/dd/yyyy"

"notes": "HTML text"

"difficulty": "HTML text"

"origin": "text"

"block": "text"

"empty": "text"

"styles": { "name": StyleSpec, ... }

Although HTML is allowed in many of these fields, it is recommended that any usage be minimized so that it does not conflict with any styles that applications use when displaying these fields. You may use HTML entities of the form &letters; for special and international characters.

The following fields are optional and apply to puzzles with solver-entered solutions or answers:

"checksum": [ "salt", "SHA1 hash", ... ]

A puzzle which does not include the solution can be verified if a checksum is provided. The checksum is the hex format SHA1 hash of the correct solution appended with the salt. For puzzles which have multiple correct solutions, multiple SHA1 hashes can be supplied. All hashes for the same puzzle use the same salt.

Some puzzles allow answers to be entered in mixed case, while some puzzles only show uppercase letters. Applications which allow mixed case entry must check the answer both as entered and when converted to all uppercase. It is up to the creator of the puzzle whether they want to include a hash for either or both forms.

For Crossword and Sudoku puzzles, the correct solution is the string formed by concatenating all values in the correct solution (taken as strings and uppercased), in reading order from top to bottom and left to right.

For WordSearch puzzles, the correct solution is the string formed by concatenating all found entries in alphabetical order.

The following common field only applies to partially solved puzzles:

"saved": ...

Crossword Puzzles - http://ipuz.org/crossword

Crossword puzzles support the following fields:

"dimensions": { "Dimension": n, ... }

"puzzle": [ [ LabeledCell, ... ], ... ]

"saved": [ [ CrosswordValue, ... ], ... ]

"solution": [ [ CrosswordValue, ... ], ... ]

"zones": [ GroupSpec, ... ]

"clues": { "Direction": [ Clue, ... ], ... }

"showenumerations": true/false

"clueplacement": "before"/"after"/null

"clueplacement": "blocks"

"answer": "entry"

"answers": [ "entry", ... ]

"enumeration": Enumeration

"enumerations": [ Enumeration, ... ]

"misses": { "entry": "hint", ... }

If a puzzle's given dimensions are larger than the supplied puzzle cells, any excess cells are omitted. If a puzzle's given dimensions are smaller than the supplied puzzle cells, the puzzle is invalid (despite this, an application may choose to allow the dimensions to be exceeded).

Puzzles with a final answer which is hidden (not within the ipuz definition) have an enumeration or enumeration, but no answer.

American Crossword - http://ipuz.org/crossword

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword#1" ],
    "dimensions": { "Dimension": n, ... },
    "puzzle": [ [ LabeledCell, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],
    "clues": { "Across": [ Clue, ... ],
               "Down": [ Clue, ... ] },
}

Cryptic Crossword - http://ipuz.org/crossword/crypticcrossword

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword/crypticcrossword#1" ],
    "dimensions": { "Dimension": n, ... },
    "showenumerations": true,
    "puzzle": [ [ LabeledCell, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],
    "clues": { "Across": [ Clue, ... ],
               "Down": [ Clue, ... ] },
}

Note that cryptics usually have enumerations for every clue. For a barred cryptic, use bar styles for the puzzle definition.

ArrowWord - http://ipuz.org/crossword/arrowword

ArrowWord puzzles are also known as Pencil Pointers. Clues are auto-placed in blocks adjacent to the first cell of the entry. If the clues do not have a location specified, the clue location is picked automatically (usually correctly).

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword/arrowword#1" ],
    "dimensions": { "Dimension": n, ... },
    "clueplacement": "blocks",
    "puzzle": [ [ LabeledCell, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],    
    "clues": { "Clues": [ Clue, ... ], ... },
}

Logic Crossword - http://ipuz.org/crossword/logiccrossword

These are the like the Sunday puzzles on puzzazz.com - an unnumbered grid and alphabetical clues.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword/logiccrossword#1" ],
    "dimensions": { "Dimension": n, ... },
    "clueplacement": "before",
    "puzzle": [ [ LabeledCell, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],    
    "clues": { "Clues": [ Clue, ... ] },
}

Diagramless Crosswords - http://ipuz.org/crossword/diagramless

Diagramless crosswords are specified as a grid with all cells omitted, except, possibly, the location of clue number 1.

Other Trick Crosswords

There are lots of tricks used in crosswords and cryptic crosswords which are easily supported by ipuz. Many are implicitly supported while some require additional fields for full support.

• Cells may be numbered arbitrarily.
• Any cell can have a clue number, even unchecked cells.
• A clue can be blank.
• A numbered cell in the grid need not have a clue associated with it.
• A numbered clue can exist for a number which is not in the grid.
• A clue can specify a different answer and/or a different enumeration than what appears in the grid.
• A single clue can be used for multiple entries (e.g., "22 & 23. Beatles bassist").
• A cell can have more than one value in it, possibly differentiated by the direction of the clue.
• Cells can be prepopulated with values.
• Row and column labels can be created by specifying borderless cells with initial values.
• Arbitrarily shaped entries overlaying the grid.

Sudoku Puzzles - http://ipuz.org/sudoku

Sudokus are puzzles in which rows, columns, boxes, and zones all have the same values from a set of values. A box is a 2-dimensional area within the grid. A zone is an arbitrary collection of cells within the grid.

Sudoku puzzles support the following fields:

"charset": "123456789"

"displaycharset": true/false

"boxes": true/false

"showoperators": true/false

"cageborder": "thick"/"dashed"

"puzzle": [ [ SudokuGiven, ... ], ... ]

"saved": [ [ SudokuGuess, ... ], ... ]

"solution": [ [ SudokuValue, ... ], ... ]

"zones": [ GroupSpec, ... ]

"cages": [ CalcSpec, ... ]

Sudoku - http://ipuz.org/sudoku

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku#1" ],
    "charset": "123456789",
    "boxes": true,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ]
}

Wordoku - http://ipuz.org/sudoku/wordoku

Wordoku variants specify a different character set and usually specify that the character set should be displayed. If it is desired to highlight a row or column in the solution, this can be done by specifying styles in the solution.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
    "charset": "BIG CHEF AD",
    "displaycharset": true,
    "boxes": true,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ]
}

Latin Square - http://ipuz.org/sudoku/latinsquare

Latin squares are the genesis of Sudokus, without the boxes.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
    "charset": "123456789",
    "boxes": false,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ],
}

Diagonal Sudoku - http://ipuz.org/sudoku/diagonalsudoku

Diagonal sudokus also require that each diagonal use the full character set.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
    "charset": "123456789",
    "boxes": true,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ],
    "zones": [ { "style": { "highlight": true },
                 "cells": [ [1,1],[2,2],[3,3],[4,4],[5,5],[6,6],[7,7],[8,8],[9,9] ] ],
               { "style": { "highlight": true },
                 "cells": [ [1,9],[2,8],[3,7],[4,6],[5,5],[6,4],[7,3],[8,2],[9,1] ] ] ],
}

Hyper Sudoku - http://ipuz.org/sudoku/hypersudoku

Hyper Sudokus add 4 more inner squares that must use the full character set.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
    "charset": "123456789",
    "boxes": true,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ],
    "zones": [ { "style": { "highlight": true }, "rect": [ 2, 2, 4, 4] },
               { "style": { "highlight": true }, "rect": [ 2, 6, 4, 8] },
               { "style": { "highlight": true }, "rect": [ 6, 2, 8, 4] },
               { "style": { "highlight": true }, "rect": [ 6, 6, 8, 8] } ],
}

Jigsaw Sudoku - http://ipuz.org/sudoku/jigsawsudoku

Jigsaw Sudokus add abritrarily shaped interior sections that must use the full character set.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
    "charset": "123456789",
    "boxes": false,
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "solution": [ [ SudokuValue, ... ], ... ],
    "zones": [ GroupSpec, ... ]
}

Calcudoku - http://ipuz.org/sudoku/calcudoku

Calcudoku puzzles (also called KenKen and KenDoku) remove the boxes and add an additional mathematical constraint. Within each small region, called a cage, when a specified mathematical operation is applied to the values, the result must equal a specified value.

The puzzle field is optional as Calcudokus usually have no givens.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
    "charset": "123456789",
    "boxes": false,
    "showoperators": true,
    "cageborder": "thick",
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "cages": [ CalcSpec, ... ],
    "solution": [ [ SudokuValue, ... ], ... ]
}

Killer Sudoku - http://ipuz.org/sudoku/killersudoku

Killer Sudokus combine Calcudoku and traditional sudoku. In a "normal" Killer Sudoku, the operator is always + so the operator is not shown. The puzzle field is optional.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
    "charset": "123456789",
    "boxes": true,
    "showoperators": false,
    "cageborder", "dashed",
    "puzzle": [ [ SudokuGiven, ... ], ... ],
    "cages": [ CalcSpec, ... ],
    "solution": [ [ SudokuValue, ... ], ... ]
}

Normally, the cage border is just thickened grid lines. A dashed cage border is different -- it is an inset dashed border.

Greater Than Sudoku - http://ipuz.org/greaterthansudoku

A Greater Than Sudoku is specified just like a normal Sudoku except the puzzle must specify where the > symbols are shown using the constraint styles.

Fill-in Puzzles - http://ipuz.org/fill

Fill-In Puzzles - http://ipuz.org/fill

These are like the Monday Anagram, Tuesday Vowels, and Wednesday CrossedWords puzzles on puzzazz.com. There are a set of fill letters, words, or bigrams, trigrams, etc., which can be moved into the grid.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/fill/vowels#1" ],
    "start": [ [ CrosswordValue, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],    
    "fill": "ABCD...",
    "fill": [ "AB", "CD", ... ],
    "answer": "entry",
    "answers": [ "entry", ... ],
    "misses": { "entry": "hint", ... }
}

The misses field allows for hints for misses and is optional.

Acrostic Puzzles - http://ipuz.org/acrostic

Acrostic - http://ipuz.org/acrostic

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/acrostic#1" ],
    "puzzle": [ [ LabeledCell, ... ], ... ],
    "solution": [ [ CrosswordValue, ... ], ... ],
    "clues": { "Direction": [ Clue, ... ], ... },
}

Block Puzzles - http://ipuz.org/block

Block puzzles have one or more blocks which move about on a field of obstacles defined by blocks and bars.

Block puzzles support the following fields:

"dimensions": { "Dimension": n, ... }

"slide": true/false

"move": true/false

"rotatable": true/false

"flippable": true/false

"field": [ [ StyledCell, ... ], ... ]

"enter": { "name": GroupSpec, ... }

"start": { "name": GroupSpec, ... }

"saved": { "name": GroupSpec, ... }

"end": { "name": GroupSpec, ... }

"exit": { "name": GroupSpec, ... }

The groups in the end state may be a subset of the groups in the start state. If a particular group in the start state is not present in the end state, it means that group's position is not important and it is not used to determine correctness. In many moving block puzzles, this allows the end state to specify a single target block which needs to reach a particular position, with the positions of all other blocks being irrelevant.

The enter and exit states allow for optional entry and exit animations. When the puzzle is started, an animation from the enter state to the start state may be made. When the puzzle is solved, an animation from the end state to the exit state may be made. Like the end states, the enter and exit states may specify a subset of the blocks in the start state. Only the blocks listed are animated and all other blocks in the start state are simply placed on the field. The enter and exit states (and only these states) may specify positions for groups that are outside the field.

Sliding Block - http://ipuz.org/block/slidingblock

Sliding block puzzles may have a field of obstacles but typically do not.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/block/slidingblock#1" ],
    "dimensions": { "Dimension": n, ... },
    "slide": true,
    "start": { "name": GroupSpec, ... },
    "saved": { "name": GroupSpec, ... },
    "end": { "name": GroupSpec, ... },
    "exit": { "name": GroupSpec, ... }
}

Maze - http://ipuz.org/block/maze

Mazes typically have a single block that slides through a field of obstacles.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/block/maze#1" ],
    "dimensions": { "Dimension": n, ... },
    "slide": true,
    "field": [ [ StyledCell, ... ], ... ],
    "enter": { "block": GroupSpec },
    "start": { "block": GroupSpec },
    "saved": { "block": GroupSpec },
    "end": { "block": GroupSpec },
    "exit": { "block": GroupSpec }
}

Puzzles with independent answers - http://ipuz.org/answer

Puzzles with independent answers, such as trivia questions and riddles, are supported by the following fields:

"choices": [ "entry", ... ]

"randomize": true/false

"answer": "entry"

"answers": [ "entry", ... ]

"enumeration": Enumeration

"enumerations": [ Enumeration, ... ]

"requiredanswers": number

"misses": { "entry": "hint", ... }

"guesses": [ "entry", ... ]

Riddle - http://ipuz.org/answer/riddle

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/answer/riddle#1" ],
    "intro": "HTML text",
    "body": "HTML text",
    "answer": "entry",
    "misses": { "entry": "hint", ... },
    "guesses": [ "entry", ... ]
}

Choice - http://ipuz.org/answer/choice

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/answer/choice#1" ],
    "intro": "HTML text",
    "choices": [ "entry", ... ],
    "randomize": true,
    "answer": "entry",
    "guesses": [ "entry", ... ]
}

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/answer/choice#1" ],
    "intro": "HTML text",
    "choices": [ "entry", ... ],
    "randomize": true,
    "answers": [ "entry", ... ],
    "guesses": [ "entry", ... ]
}

Flat - http://ipuz.org/answer/flat

The native puzzle type of the National Puzzlers' League.

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/answer/flat#1", "http://www.puzzlers.org/flats/...#1" ],
    "intro": "HTML text",
    "lines": [ "HTML line", ... ],
    "answers": [ "entry", ... ],
    "enumeration": [ Enumeration, ... ],
    "requiredanswers": number,
}

WordSearch Puzzles - http://ipuz.org/wordsearch

A WordSearch puzzle presents a field of letters in which the solver can find words.

WordSearch puzzles support the following fields:

"dimensions": { "Dimension": n, ... }

"puzzle": [ [ CrosswordValue, ... ], ... ]

"solution":  { "entry": GroupSpec, ... }

"solution":  "entry"

"solution":  [ "entry", ... ]

"dictionary": "dictname"/false

"saved": [ "entry", ... ]

"showanswers": "during"/"after"/null

"time": number

"points": "linear"/"log"/null

"zigzag": true/false

"retrace": true/false

"useall": true/false

"misses": { "entry": "hint", ... }

A given puzzle has either a solution or a dictionary reference, but not both. A GroupSpec for a correct solution may be omitted (specified as null), in which case the solution will not be displayed on the field. In this case, the entry may have non-field characters in it which are ignored for matching purposes (e.g., spaces inside phrases).

WordSearch - http://ipuz.org/wordsearch

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/wordsearch#1" ],
    "dimensions": { "Dimension": n, ... },
    "puzzle": [ [ CrosswordValue, ... ], ... ],
    "solution":  { "entry": GroupSpec, ... },
    "saved": [ "entry", ... ]
}

Either dictionary or solution but not both.

Anagrid - http://ipuz.org/wordsearch/anagrid

Also known as Boggle or Scramble

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/wordsearch/anagrid#1" ],
    "dimensions": { "Dimension": n, ... },
    "time": 300,
    "dictionary": "allwords",
    "points": "log",
    "zigzag": true,
    "retrace": false,
    "puzzle": [ [ CrosswordValue, ... ], ... ]
}

TraceOut - http://ipuz.org/wordsearch/traceout

These are like the Saturday puzzles on puzzazz.com

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/wordsearch/traceout#1" ],
    "dimensions": { "Dimension": n, ... },
    "puzzle": [ [ CrosswordValue, ... ], ... ],
    "zigzag": true,
    "retrace": true,
    "useall": true,
    "solution": { "entry": null },
    "misses": { "entry": "hint", ... }
}

The misses field allows for hints for misses and is optional.

Data Structures

Text

HTML

Where HTML is supported, only a small subset of HTML is allowed. The following tags are allowed:

<b> ... </b>

<i> ... </i>

<s> ... </s>

<u> ... </u>

<em> ... </em>

<strong> ... </strong>

<big> ... </big>

<small> ... </small>

<sup> ... </sup>

<sub> ... </sub>

<br> or <br/>

In some fields which have their own formatting (e.g., author), <big>, <small>, <sup>, <sub>, and <br> may not produce the desired results.

In addition, special ipuz tags within the HTML may be used to conditionally insert text values from the puzzle definition into the HTML. For example, a Wordoku puzzle might insert the charset, while a Fill-In puzzle might insert the fill. When the puzzle is displayed, if the corresponding value has not been displayed automatically, then the ipuz tag is replaced with the attribute value. For example:

Fit the letters <ipuz:fill/> into the grid

Another variant of the ipuz tag can be used to insert the name of a unique color, or a text description of what a highlighted cell looks like. For example:

Starting with the <ipuz:color1/> letters ...
Starting with the <ipuz:highlight/> squares ...

Whether or not you support HTML in a field where HTML is supported, the special characters & < > must be encoded.

&

<

>

Entities of the form &letters; are allowed for special and international characters.

Because HTML is always contained within a string, double quote and the \ character must be escaped as described in the preceding section on Text. While &quot; may be used to represent a double quote, \" is recommended instead for consistency with plain text strings.

StyleSpec

A StyleSpec is either the name of a style or a dictionary of style specifiers.

The style specifiers are:

"shapebg": "circle"

"highlight": true/false

"named": "delimiter"/false

"border": number

"divided": "-", "|", "/",
           "\\", "+", or "x"

"label": "text"

"mark": { "TL|TR|BL|BR": "text", ... }

"imagebg": "image_url"

"image": "image_url"

"slice": [ x1, y1, x2, y2 ]

"barred": "TRBL"

"dotted": "TRBL"

"dashed": "TRBL"

"lessthan": "TRBL"

"greaterthan": "TRBL"

"equal": "TRBL"

"color": number/"hhhhhh"

"colortext": number/"hhhhhh"

"colorborder": number/"hhhhhh"

"colorbar": number/"hhhhhh"

The special value of null specifies no style. It is equivalent to { }. Normally, a solution cell inherits the style from the puzzle unless overridden. A null style allows a solution cell to have no style even if the puzzle specified one. In contrast, if the style is omitted, it has no effect and the puzzle's style is inherited.

When a puzzle needs highlighting of certain cells, but does not care about the particular look, the highlight style should be used. Each implementation is free to highlight in the way that is best for the device, operating system, etc. Examples include using a color background, thick borders, a cirlce in the background, or a symbol (such as a *) in a corner. The <ipuz:highlight/> can be used to insert a text description of the highlighting into any HTML text.

Unique colors are automatically selected from a predefined table of puzzle colors which are implementation-defined. Any two colors that are specified as the same numeric value get the same selected color, allowing a puzzle to ensure that two squares get the same coloration without actually needing to specify a specific color. Unless specific colors are needed, it is recommended that unique colors be used.

hhhhhh denotes a 6-digit hex value for a specific color.

When specified, bars replace the normal grid line (but see the note about dashed borders for cages). Since grid lines are between cells, a given line can be modified by two different cells. If the two cells specify different styles, they are combined (e.g., barred + dashed + constraint produces a thick dashed line with a constraint on top of it). If dashed and dotted are combined, the result is a dashed line.

The delimiter for the named style allows for multiple distinct groups which appear to have the same name (e.g., for a sliding block puzzle).

GroupSpec

A GroupSpec is a dictionary of one or more of the following:

"rect": [ x1, y1, x2, y2 ]

"cells": [ [x1, y1], ... ]

"style": StyleSpec

CalcSpec

A CalcSpec is a dictionary of one or more of the following:

"rect": [ x1, y1, x2, y2 ]

"cells": [ [x1, y1], ... ]

"value": number

"operator": "op"

"style": StyleSpec

If the operator is missing, + is the default.

SudokuGiven

A SudokuGiven is one of:

null

number/"c"

empty value

or a dictionary of one or more of the following:

"given": see above

"style": StyleSpec

SudokuValue

A SudokuValue is one of:

null

number/"c"

empty value

or a dictionary of one or more of the following:

"value": see above

"style": StyleSpec

SudokuGuess

A SudokuGuess is one of:

number/"c"

empty value

[ number/"c", ... ]

No semantics are assigned to penciled-in values. Some solvers may use them for possible values, while others may use them for impossible values.

StyledCell

A StyledCell is one of:

null

block value

empty value

or a dictionary of one or more of the following:

"cell": see above

"style": StyleSpec

LabeledCell

A LabeledCell is one of:

null

block value

empty value

ClueNum

or a dictionary of one or more of the following:

"cell": see above

"style": StyleSpec

"value": "str"

CrosswordValue

A CrosswordValue is one of:

null

block value

empty value

string

[ CrosswordValue, ... ]

or a dictionary of one or more of the following:

"value": see above

"style": StyleSpec

"Direction": CrosswordValue

If one or more directional values are supplied, the value field does not need to be specified. If it is specified, it applies to any directions which are not explicitly specified.

height

width

Direction

A Direction specifies the direction of the entries for a set of clues.

Across

Down

Diagonal

Diagonal Up

Diagonal Down Left

Diagonal Up Left

Zones

Clues

A direction can optionally specify a different string to be shown to solvers. For example:

Diagonal:Southeast

Across:Horizontales

ClueNum

A ClueNum is either a number or a string, allowing for lettered clues. You should normally not include punctuation (e.g., "23." or "(3)") in the clue number as any appropriate punctuation will be provided by the application.

Enumeration

An Enumeration specifies what a value or solution looks like. They are most commonly used in Cryptic Crosswords, to enumerate what each clue yields, and in Flats, to enumerate what the final solution looks like. Note that the enumeration may not match what is visible in the puzzle (this is particularly true with Variety Cryptics).

An enumeration is specified as a string (following the general convention, a number is equivalent to a string of that number). The string is parsed into a series of numbers and non-numeric characters. The numeric characters in the enumeration specify the letters (and possibly numeric characters) of the answer. The number 0 represents a word of unspecified length. Some PuzzleKinds (or applications) may allow non-alphabetic or non-alphanumeric characters to be omitted when the user enters an answer (for example, an application might accept UTURN for the answer U-TURN). Generally a space is interpreted to mean any white space and is optional. Some characters have special meanings, detailed below.

You should normally not include surrounding delimiters (e.g., "(4 4)") or commas (e.g., "4, 4") in the enumeration. The application will format the enumeration if appropriate and may allow the user to choose whether a word count is displayed. For example, If you supply an an enumeration of "3 2" an application could display it as any of "3 2", "3, 2", "5", or "5, two words".

The following are some examples of enumeration strings:

"7"

_ _ _ _ _ _ _

"1-4"

_ - _ _ _ _

"5 1.1."

_ _ _ _ _   _._.

"0.0"

________.________

An enumeration can be followed by a semicolon and a word count. When present, the word count overrides the automatically calculated word count from the rest of the enumeration. Do not include the word count as plain text in the enumeration (e.g., "5, two words").

"10;2"

_ _ _ _ _ _ _ _ _ _ (2 words)

"0;3"

________   ________   ________ (3 words)

An enumeration can also be associated with a cue. A cue is an identifier (typically a number or word) that is associated with one of the answers. The cue is given by including it at the start of the enumeration followed by an equal sign. For example:

"LONG=9" 

LONG = _ _ _ _ _ _ _ _ _

"STARTING LINE=4 4"

STARTING LINE = _ _ _ _   _ _ _ _

"1=3/2"

1 = _ _ _ / _ _

"DON'T=4'2"

DON'T = _ _ _ _ ' _ _

As shown in the last two examples, a cue word may contain non-alphabetic characters.

Some characters in enumerations have special meanings:

*

^

+

For example:

"*5"

*_ _ _ _ _

"*10 3"

*_ _ _ _ _ _ _ _ _ _   _ _ _

"^9 *5"

^_ _ _ _ _ _ _ _ _   *_ _ _ _ _

"^3 ^3 2 3 ^3"

^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _

"3 +1 +2 +4"

_ _ _   +_   +_ _   +_ _ _ _

To include one of the special characters *, ^, +, =, or ; literally in an enumeration or cue, precede it with a ` (backquote) character. You can also use a ` to use a literal number in an enumeration. For a literal backquote, use two backquotes (``).

"^1`*^1`*^1`*^1" 

^_ * ^_ * ^_ * ^_

"^6 `1`3" 

^_ _ _ _ _ _   13

Clue

A Clue is either:

An HTML string (for unnumbered clues)

"Clue html"

or a single clue number and an HTML string

[ ClueNum, "Clue html" ]

or a dictionary of options, all optional

"number": ClueNum

"numbers": [ ClueNum, ... ]

"clue": "Clue html"

"hints": [ "Hint html", ... ]

"image": "image_url"

"answer": "text"

"enumeration": Enumeration

"references": [ ClueNum, ... ]

"see": ClueNum

"highlight": true/false

"location": [ x, y ]

Normally, the enumeration and answer for a clue are automatically calculated from the grid. If this cannot be done for some reason (e.g., phrases or variant cryptic crosswords with special rules), the proper values can be supplied with the clue. The clue's answer value does not affect what appears in the grid, only what is shown to the solver when the answer for a clue is revealed. For puzzles with hidden answers, an enumeration can be provided without an answer.

If one or more hints are provided, they replace the clue when they are given. The hint is usually a superset of the clue -- for example, a parenthetical comment at the end of the clue is added, or a / is added to show the division between the two parts of a cryptic clue. Replacement HTML is used to give maximum flexibility in how the hint modifies the clue.

Images

Image URLs can be relative (to site or package) or absolute.

Extensions

The ipuz extension is extensible so that we can improve it to handle new puzzle types and so that individual companies can add their own data. For example, if an application uses ipuz as its file format, it may be desirable for it to also contain preference information. If you follow the rules in this section, you may extend ipuz on your own, without permission from or coordination with anyone else.

Extensions to ipuz must be declared in a namespace, using reverse domain name notation. If you are reading an ipuz file and you encounter a field with a . in its name, it is an extension field. Additionally, applications may (and should) declare the volatility of any extensions they write. Applications that both read and write puzzles should respect the volatility of extensions they do not recognize. However, applications should also be aware that it is possible that the volatility may not be properly respected, so they should be resilient of potential inconsistencies.

Volatility is specified as a list of fields that require removal, with the special value "*" meaning all fields:

"*"

"field,field,..."

""

When you save a file with changes you should remove any fields whose volatility indicates that they are no longer valid -- that is, one of the listed fields has been changed. If the volatility of an extension is not specified, the default volatility is "*" (remove on any data change). Volatility can be set for an entire namespace or for an individual field in a namespace.

In the following example, com.example:preferences is always volatile, com.example:cursor is only volatile when saved state information is added or changed, com.example:info is volatile when the puzzle, solution, explanation, notes, or saved state are changed, and com.example:other is not volatile and should always be roundtripped (from the default volatility for com.example):

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku#1", "http://my.example.com/example#1" ],
    "volatile": { "com.example": "",
                  "com.example:preferences": "*",
                  "com.example:cursor": "saved",
                  "com.example:info": "puzzle,solution,explanation,notes,saved" },
    "com.example:preferences": { ... },
    "com.example:cursor": { ... },
    "com.example:info": { ... },
    "com.example:other": { ... }
}

You are not required to document extensions that you create, but we recommend that you do so. It is also recommended that all such extensions be submitted to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

Examples

A complete example of a crossword can be found on this page. A copy of the first crossword ever created in ipuz format can be found on this page

Crossword

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/crossword#1" ],
    "dimensions": { "width": 3, "height": 3 },
    "puzzle": [ [ { "cell": 1, "style": { "shapebg": "circle" } }, 2, "#" ],
                [ 3, { "style": { "shapebg": "circle" } }, 4 ],
                [ null, 5, { "style": { "shapebg": "circle" } } ] ],
    "solution": [ [ "C", "A", "#" ],
                  [ "B", "O", "T" ],
                  [ null, "L", "O" ] ],
    "clues": { "Across": [ [ 1, "OR neighbor" ],
                           [ 3, "Droid" ],
                           [ 5, "Behold!" ] ],
               "Down": [ [ 1, "Trucker's radio" ],
                            [ 2, "MSN competitor" ],
                            [ 4, "A preposition" ] ] }
}

Sudoku

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku#1" ],
    "charset": "123456789",
    "boxes": true,
    "puzzle": [ [ 0, 1, 2, 0, 0, 7, 0, 0, 0 ],
                [ 8, 0, 0, 9, 0, 0, 0, 0, 6 ],
                [ 5, 0, 0, 0, 4, 0, 2, 0, 0 ],
                [ 0, 4, 0, 0, 0, 1, 0, 0, 0 ],
                [ 0, 7, 5, 0, 0, 0, 6, 2, 0 ],
                [ 0, 0, 0, 6, 0, 0, 0, 8, 0 ],
                [ 0, 0, 6, 0, 3, 0, 0, 0, 7 ],
                [ 1, 0, 0, 0, 0, 9, 0, 0, 5 ],
                [ 0, 0, 0, 1, 0, 0, 3, 4, 0 ] ],
    "solution": [ [ 9, 1, 2, 5, 6, 7, 4, 3, 8 ],
                  [ 8, 3, 4, 9, 1, 2, 5, 7, 6 ],
                  [ 5, 6, 7, 3, 4, 8, 2, 1, 9 ],
                  [ 6, 4, 8, 7, 2, 1, 9, 5, 3 ],
                  [ 3, 7, 5, 8, 9, 4, 6, 2, 1 ],
                  [ 2, 9, 1, 6, 5, 3, 7, 8, 4 ],
                  [ 4, 8, 6, 2, 3, 5, 1, 9, 7 ],
                  [ 1, 2, 3, 4, 7, 9, 8, 6, 5 ],
                  [ 7, 5, 9, 1, 8, 6, 3, 4, 2 ] ]
}

Calcudoku

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
    "boxes": false,
    "showoperators": true,
    "cages": [ { "value": 4, "operator": "+", "cells": [ [1, 1], [1, 2] ] },
               { "value": 5, "operator": "+", "cells": [ [2, 1], [3, 1] ] },
               { "value": 6, "operator": "x", "cells": [ [1, 3], [2, 3] ] },
               { "value": 4, "operator": "+", "cells": [ [2, 2], [3, 2], [3, 3] ] } ],
    "solution": [ [ 1, 2, 3 ],
                  [ 3, 1, 2 ],
                  [ 2, 3, 1 ] ],
}

Flat

PHONETIC BEHEADMENT (4, 4)
The TWO thought it was fun,
As she aced the ONE.
=Qoz, Redmond WA

{
    "version": "http://ipuz.org/v1",
    "kind": [ "http://ipuz.org/answer/flat#1",
               "http://www.puzzlers.org/flats/phoneticbeheadment#1" ],
    "author": "Qoz, Redmond WA",
    "lines": [ "The TWO thought it was fun,", "As she aced the ONE." ],
    "enumerations": [ 4, 4 ],
}

Frequently Asked Questions

Is there an XML version of ipuz?

No. The purpose of the standard is to provide a format that every program can read and write. Having two versions of the standard would mean that applications would need twice as much code to support the standard.

Is there a binary ipuz format?

No. A binary format would only be slightly smaller and would splinter the standard. Having two versions of the standard would mean that applications would need twice as much code to support the standard.

Can I support other formats?

Absolutely.

Can I still support my own native format?

Yes.

Can I convert puzzles to/from ipuz format?

Yes.

Can I encrypt puzzles in ipuz format?

The standard does not support encryption, but you may encrypt an entire ipuz puzzle if you wish. However, doing so will make your puzzles unreadable by others until they have been unencrypted. If your goal is to prevent solvers from cheating and viewing the solution, simply omit the solution from the file and use a checksum instead of encryption.

Can ipuz puzzles be compressed?

The standard does not support compression within a puzzle. With the size of storage available these days and the speed of networks (even wireless and cellular networks), the savings would not be significant and is not worth the tradeoff of complexity. You may, of course, compress any data within your application that you desire, but an ipuz puzzle which has been compressed is not considered to conform to the standard for interchange purposes.

Can I extend the ipuz format?

Yes. You can extend ipuz on your own and still conform to the standard by following the instructions in the Extensions section above. If your extensions are useful to the community at large, we recommend that you contact us about including your extensions in a future version of the standard.

Is there a fee to support ipuz?

No. ipuz is and always will be free. There are some requirements for use of the ipuz trademarks but there will never be a fee for use of the format, trademarks, or other intellectual property associated with ipuz.

Is ipuz covered by copyright, trademarks, patents, etc.?

The ipuz specification is copyrighted and the name is a trademark to ensure that the standard is not splintered and that only puzzles which conform to the standard can use the name. Complete details are in the section below.

There are no plans to patent anything which would inhibit the free distribution of ipuz format puzzles, or which would inhibit any application from being able to fully support ipuz format files. If Puzzazz (creators and caretakers of the ipuz standard) does patent anything which would inhibit supporting, reading, or writing ipuz format files, a free license will be granted to anyone supporting the standard.

Is there reference code available?

Not at this time. We do not control code created by third parties, but we encourage the community to release code as open source and we recommend the MIT License for any such code.

Acknowledgements

This document was authored by Roy Leban for Puzzazz. Thanks to (in alphabetical order) Sam Bellotto Jr., Ross Beresford, Scott Blomquist, Chip Brown, Jérome Foucher, Jim Horne, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback on this specification.

Disclaimers

No warranties, express or implied, are conferred through this specification. No guarantee is made as to the suitability of the ipuz format, or of any software supporting the ipuz format, for any particular usage. It is up to you to evaluate the suitability of the format for your intended usage.

Application developers are solely responsible for ensuring that they comply with government regulations including, but not limited to, laws on export of cryptographic technology.

Copyright, Trademarks and Licensing

The ipuz specification is © Copyright 2022 Puzzazz
ipuz and ipuz.org are trademarks of Puzzazz

Through this notice, Puzzazz hereby grants you a perpetual, irrevocable, free license to use the ipuz format for puzzle data, and to read, write, and/or store the ipuz format in any software.

Rationale

The ipuz specification is copyrighted and the name is a trademark for a simple reason: to ensure that the standard is not splintered and that only puzzles which conform to the standard can use the name. This will help both solvers, constructors, and companies alike. By granting this perpetual, irrevocable, free license, it is the intent of Puzzazz to ensure that the standard is as open as possible.

Conforming to the Standard

A puzzle conforms with the ipuz standard if:

• The puzzle only uses fields defined in the specification as they are defined in the specification.
• The version field of the puzzle specifies the URL of the version of the specification used by the puzzle, The URL for the current version of ipuz is http://ipuz.org/v1.
• The kind field of the puzzle specifies the proper PuzzleKind URI and version number, and conforms to the requirements of the PuzzleKind.
• Any extension fields are declared in a namespace.

Software (including applications, web sites, web services, etc.) conforms with the standard if:

• Any puzzles that are written as ipuz format conform to the standard.
• If your software reads or imports ipuz puzzles and it does not support the entire standard, it must reject any puzzles that use features it does not support. If your software can write ipuz puzzles, any puzzles so written must conform to the standard. If your software can modify existing ipuz files, it must either correctly maintain any features it does not support, or it must reject any puzzles for which it cannot do so.
• If your software reads or imports a subset of the entire standard, you must provide a brief text description for users explaining what you support. This description may be in your software or on your web site.

Trademark License

Through this notice, Puzzazz hereby grants you a perpetual, irrevocable, free license to use the ipuz trademarks in association with puzzles that conform to the ipuz standard, and/or with software that supports the ipuz standard, subject to the following conditions:

• If you use the ipuz trademark outside of a puzzle, such as in software or on your web site, you must include the following notice:

  ipuz is a trademark of Puzzazz, used with permission

  This notice can be placed wherever you normally place such notices in your software, documentation, or web site, and it need not receive any higher prominence than any other similar notice. We require this notice to help maintain the trademark in good standing. You only need to provide such a notice if you use the ipuz trademark. You do not need to provide it solely because you support the standard, or you use or include puzzles that conform to the standard.

No other rights to the ipuz trademarks are conferred or implied. No rights to any other Puzzazz trademarks or intellectual properties are conferred or implied. This license does not grant you the right to make any claims of endorsement of your puzzles by either ipuz.org or Puzzazz.

You may not use the ipuz trademark in association with puzzles or software that do not conform to the ipuz standard as described above, even if you have other puzzles or software that do conform to the standard.

This Specification

This ipuz specification document is licensed under a Creative Commons Attribution-No Derivative Works 3.0 Unported License.

In plain English, this means that you may place a copy of this specification on your web site, provided that you do not change it. Although attribution is required, this will happen automatically if you do not change it. The "no derivatives" restriction of the license applies only to the specification itself. As described above, you may create derivatives of the standard by extending it, but you must document these extensions in a separate document, not by modifying this specification. You may present this specification within a web page that contains other content (such as by putting the specification within an iframe) provided the document boundary is clearly delineated. Such an iframe may reference this specification on ipuz.org directly. We recommend that you do this to document extensions to the standard or to present comments about it.