# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.

Mar | MAY | Jul
| 30 |
2022 | 2023 | 2024

success
fail
About this capture
COLLECTED BY
Collection: Common Crawl
Web crawl data from Common Crawl.
TIMESTAMPS
The Wayback Machine - https://web.archive.org/web/20230530005239/http://www.ipuz.org/

# ipuz - the open format for puzzles

Version 2.0.2

ipuz is the free, open, extensible standard format for all types of what have traditionally been called "pencil and paper" puzzles.

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 2015 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. When multiple PuzzleKinds are specified, they should be listed from least specific to most specific (e.g., crossword then cryptic crossword). In most cases, an application that does not support all of the listed kinds will be able to properly display the puzzle based on the first kind, but will not be able to support it fully without supporting all of the kinds.

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:

http://ipuz.org/crossword | Grid puzzle that uses clues for entries.
http://ipuz.org/sudoku | Sudoku-style logic.
http://ipuz.org/fill | Grid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrostic | Grid puzzle with two grids, one of which has clues, in which there is a correspondence between the letters that in the two grids.
http://ipuz.org/block | Puzzle with blocks that move.
http://ipuz.org/answer | Puzzle with a question and answer
http://ipuz.org/wordsearch | Puzzle with one or more words to be found in the grid.

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

An ipuz-formatted puzzle is formatted as a JSON 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/v2",
        "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" ] ] }
    }

Note: While some applications may support both JSON and JSONP files, we recommend that all ipuz puzzles be presented in JSON format, not JSONP. JSONP files may tempt JavaScript developers to take the shortcut of using eval(), which is a security risk.

When an ipuz puzzle is stored in a file, it is recommend that the suffix be .ipuz. An acceptable alternative is .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/v2"
|  | * Version of ipuz for this puzzle
    "kind": [ PuzzleKind, ... ]
|  | * Kind of this puzzle (must have at least one kind)

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

    "copyright": "2015 ..."
|  | Copyright information
    "publisher": "HTML name"
|  | Name and/or reference for a publisher
    "publication": "HTML pub info"
|  | Bibliographic reference for a published puzzle
    "url": "puzzle_url"
|  | Permanent URL for the puzzle
    "uniqueid": "value"
|  | Globally unique identifier for the puzzle
    "title": "HTML title"
|  | Title of puzzle
    "intro": "HTML text"
|  | Text displayed above puzzle
    "explanation": "HTML text"
|  | Text displayed after successful solve
    "annotation": "text"
|  | Non-displayed annotation
    "author": "HTML text"
|  | Author of puzzle
    "editor": "HTML text"
|  | Editor of puzzle
    "date": "mm/dd/yyyy"
|  | Date of puzzle or publication date
    "notes": "HTML text"
|  | Notes about the puzzle
    "difficulty": "HTML text"
|  | Informational only, there is no standard for difficulty
    "charset": "123456789"
|  | Characters that can be entered in the puzzle
    "origin": "text"
|  | Program-specific information from program that wrote this file
    "block": "text"
|  | Text value which represents a block (defaults to "#")
    "empty": "text"
|  | Value which represents an empty cell (defaults to 0)
    "styles": { "name": StyleSpec, ... }
|  | Named styles for the puzzle

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 solution is case-sensitive but most apps only allow upper case letters. Unless a puzzle explicitly uses mixed case, the solution values should be in upper case.

The charset field defines the characters that can be entered into the puzzle, not the values, and can be used to determine which keyboard to present to a user. For example, in a standard 16x Sudoku, the charset field could specify "0123456789" (though it's optional and not strictly necessary) and the values field would list "1" through "16". The charset field is optional and is only necessary when the allowed input characters cannot be determined automatically. Note: The charset field was previously a Sudoku-only field.

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

    "checksum": [ "salt", "SHA1 hash", ... ]
|  | Hashes for (correct solution + salt)

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": ...
|  | Partially saved solve, data format defined by the type of puzzle

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

Crossword puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ LabeledCell, ... ], ... ]
|  | * The puzzle rows, then columns
    "saved": [ [ CrosswordValue, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ CrosswordValue, ... ], ... ]
|  | Correct solution
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped entries overlaid on the grid
    "clues": { "Direction": [ Clue, ... ], ... }
|  | Clue sets
    "showenumerations": true/false
|  | Show enumerations with clues
    "clueplacement": "before"/"after"/null
|  | Where to put clues (null = auto)
    "clueplacement": "blocks"
|  | Put clues in blocks adjacent to entry
    "answer": "entry"
|  | The final answer to the puzzle
    "answers": [ "entry", ... ]
|  | List of final answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the final answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for final answers to the puzzle
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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/v2",
        "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/v2",
        "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/v2",
        "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/v2",
        "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:

    "values": ["1", "2", ...]
|  | Values used in the puzzle
    "displayvalues": true/false
|  | Indicates the list of values should be displayed
    "boxes": true/false
|  | Divide the puzzle into boxes
    "showoperators": true/false
|  | Show calculation operators
    "cageborder": "thick"/"dashed"
|  | Cage borders are thicker or dashed
    "puzzle": [ [ SudokuGiven, ... ], ... ]
|  | * Given values in the puzzle
    "saved": [ [ SudokuGuess, ... ], ... ]
|  | Current solve state of the puzzle
    "solution": [ [ SudokuValue, ... ], ... ]
|  | Solution to the puzzle
    "zones": [ GroupSpec, ... ]
|  | Arbitrarily-shaped areas that must use the charset
    "cages": [ CalcSpec, ... ]
|  | Arbitrarily-shaped areas that match a calculation

The values field is prefered over the charset field for Sudoku puzzles, and specifies the list of values which can be present in the puzzle. Values may be multiple characters. Null values in the array are ignored and can be used to indicate gaps (spaces) in the list as it is to be displayed.

The values field is optional and is only necessary when the allowed values cannot be determined automatically. For example, in a Wordoku puzzle using a phrase, the order of the letters cannot be determined automatically. Similarly, if a 9x Wordoku puzzle has only 8 of the 9 values provided as givens in the puzzle and the solution is omitted, the 9th value cannot be determined automatically. If a puzzle contains a charset field and no values field, the puzzle is treated as if the values field was an array of the single characters in the charset field. Note: The displaycharset field has been deprecated and replaced by the displayvalues field.

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

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/wordoku#1" ],
        "values" ["B", "I", "G", null, "C", "H", "E", "F", null, "A", "D"],
        "displayvalues": true,
        "boxes": true,
        "puzzle": [ [ SudokuGiven, ... ], ... ],
        "solution": [ [ SudokuValue, ... ], ... ]
    }

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

Latin squares are the genesis of Sudokus, without the boxes. The example is a 6x Latin Square

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/latinsquare#1" ],
        "values": ["1", "2", "3", "4", "5", "6"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/diagonalsudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/hypersudoku#1" ],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/jigsawsudoku#1" ],
        "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. The example is an 10x Calcudoku.

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku/calcudoku#1" ],
        "values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"],
        "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/v2",
        "kind": [ "http://ipuz.org/sudoku/killersudoku#1" ],
        "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

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/v2",
        "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/v2",
        "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, ... }
|  | * Dimensions of the puzzle grid
    "slide": true/false
|  | Blocks can be slid to a new location by the solver
    "move": true/false
|  | Blocks can be moved to a new location by the solver
    "rotatable": true/false
|  | Blocks can be rotated by the solver
    "flippable": true/false
|  | Blocks can be flipped upside down (mirrored) by the solver
    "field": [ [ StyledCell, ... ], ... ]
|  | Blocks and bars defining the obstacles
    "enter": { "name": GroupSpec, ... }
|  | Pre-initial state of the puzzle
    "start": { "name": GroupSpec, ... }
|  | Initial state of the puzzle
    "saved": { "name": GroupSpec, ... }
|  | Current solve state of the puzzle
    "end": { "name": GroupSpec, ... }
|  | Solution state of the puzzle
    "exit": { "name": GroupSpec, ... }
|  | Post-solution state for animation

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/v2",
        "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/v2",
        "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", ... ]
|  | Answer choices for the puzzle
    "randomize": true/false
|  | Randomize the choices (defaults to true)
    "answer": "entry"
|  | Single answer to the puzzle
    "answers": [ "entry", ... ]
|  | Multiple answers to the puzzle
    "enumeration": Enumeration
|  | Enumeration of the answer to the puzzle
    "enumerations": [ Enumeration, ... ]
|  | List of enumerations for answers to the puzzle
    "requiredanswers": number
|  | Number of required answers (if less than all)
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses
    "guesses": [ "entry", ... ]
|  | List of guesses already made by the solver

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

    {
        "version": "http://ipuz.org/v2",
        "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

Single and multiple choice puzzles, such as trivia puzzles.

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 grid of letters in which the solver can find words.

WordSearch puzzles support the following fields:

    "dimensions": { "Dimension": n, ... }
|  | * Dimensions of the puzzle grid
    "puzzle": [ [ CrosswordValue, ... ], ... ]
|  | The field of letters
    "solution": { "entry": GroupSpec, ... }
|  | Set of unordered valid answers and (optionally) their locations
    "solution": [ "entry"/{"entry":...}, ... ]
|  | Set of ordered valid answers
    "solution": "entry"
|  | Correct answer for the puzzle
    "dictionary": "dictname"/null
|  | Dictionary to check answers in
    "saved": [ "entry", ... ]
|  | Current entries found by the solver
    "showanswers": "during"/"after"/null
|  | Time limit for the puzzle
    "time": number
|  | Time limit (in seconds) for the puzzle
    "points": "linear"/"log"/null
|  | Point-scoring method used for puzzle
    "zigzag": true/false
|  | Allow movements in more than one direction
    "retrace": true/false
|  | Allow letters to be reused in an entry
    "useall": true/false
|  | Require all letters to be used in every entry
    "misses": { "entry": "hint", ... }
|  | List of hints to be given for misses

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 grid. The entry may have non-grid characters in it which are ignored for matching purposes (e.g., spaces and dashes inside phrases). Normally, case does not matter in entries — whether they are mixed case or match the typically all-uppercase text in the grid is a stylistic decision. Italic text within an entry is typically ignored, and is useful for parenthetical remarks (e.g., "Kalamazoo (Michigan)" matches KALAMAZOO in the grid).

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

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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/v2",
        "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

In text strings, the quote character must be escaped with \" and the \ character must be escaped with \\.

### HTML

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

    <b> ... </b>
|  | Bold
    <i> ... </i>
|  | Italic
    <s> ... </s>
|  | Strikeout
    <u> ... </u>
|  | Underline
    <em> ... </em>
|  | Emphasis
    <strong> ... </strong>
|  | Stronger emphasis
    <big> ... </big>
|  | Bigger text
    <small> ... </small>
|  | Smaller text
    <sup> ... </sup>
|  | Superscript text
    <sub> ... </sub>
|  | Subscript text
    <br> or <br/>
|  | Line break (actually regex: <br[ \r\n\t]*/?> )

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.

    &amp;
|  | Represents &
    &lt;
|  | Represents <
    &gt;
|  | Represents >

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"
|  | Background shape in cell (see note below)
    "highlight": true/false
|  | Highlighted (implementation defined)
    "named": "delimiter"/null
|  | Name of group is shown up to first occurence of delimiter
    "border": number
|  | Thickness of border around cell or group (multiplier)
    "divided": "-", "|", "/",
               "\\", "+", or "x"
|  | Subdivision in the cell (note \ is doubled for JSON)
    "label": "text"
|  | Large centered text label (e.g., for 15 puzzle)
    "mark": { "TL|TR|BL|BR": "text", ... }
|  | Small text label that appears in specified cell corner
    "mark": { "T|L|R|B": "text", ... }
|  | ... or in the middle of the specified cell side
    "mark": { "C": "text", ... }
|  | ... or in the center of the cell
    "imagebg": "image_url"
|  | Background image to show
    "image": "image_url"
|  | Image to show (replaces text, if any)
    "slice": [ col1, row1, col2, row2 ]
|  | Slice of image to show (e.g., for picture 15 puzzle)
    "barred": "TRBL"
|  | Solid bar top, left, right, bottom (any combo)
    "dotted": "TRBL"
|  | Dotted bar top, left, right, bottom (any combo)
    "dashed": "TRBL"
|  | Dashed bar top, left, right, bottom (any combo)
    "lessthan": "TRBL"
|  | Show a < constraint on top, left, right, bottom (any combo)
    "greaterthan": "TRBL"
|  | Show a > constraint on top, left, right, bottom (any combo)
    "equal": "TRBL"
|  | Show a = constraint on top, left, right, bottom (any combo)
    "color": number/"hhhhhh"
|  | Color background (number = unique color)
    "colortext": number/"hhhhhh"
|  | Color text (number = unique color)
    "colorborder": number/"hhhhhh"
|  | Color border (number = unique color)
    "colorbar": number/"hhhhhh"
|  | Color bar (number = unique color)

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.

If an app supports shapebg, the only required shape is "circle", which is supported by most crossword creation software. Apps can add support for additional shapes provided logical names are used, and no namespacing is required, as with Puzzazz extensions. This allows the set of supported shapes to grow over time as support is added, and Puzzazz is happy to help facilitate the naming of new shapes. The following shapes are known to be supported by one or more apps: circle, arrow-left, arrow-right, arrow-up, arrow-down, triangle-left, triangle-right, triangle-up, triangle-down, diamond, club, heart, spade, star, square, rhombus, /, \, X.

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 circle 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. For implementers, it is recommended that color 0 be black and that all other colors be non-black, but this is not required. It is expected that most implementations will have a finite number of unique colors (at least 16 is recommended).

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": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "line": [ [col1, row1], [deltacol, deltarow], length ]
|  | Cells in a line, delta values are -1,0,1
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "style": StyleSpec
|  | The style for the cell

### CalcSpec

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

    "rect": [ col1, row1, col2, row2 ]
|  | Cells defined by a bounding rectangle
    "cells": [ [col1, row1], ... ]
|  | An explicit list of cells
    "value": number
|  | The calculated value
    "operator": "op"
|  | The operator for the calculation: +, -, *, or /
    "style": StyleSpec
|  | The style for the cell

If the operator is missing, + is the default.

### SudokuGiven

A SudokuGiven is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "given": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuValue

A SudokuValue is one of:

    null
|  | Omitted cell
    number/"c"
|  | Cell value
    empty value
|  | Empty cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### SudokuGuess

A SudokuGuess is one of:

    number/"c"
|  | Cell value
    empty value
|  | No guess value (empty value defaults to 0 or "0")
    [ number/"c", ... ]
|  | Array of penciled-in values

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
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal cell (empty value defaults to 0 or "0")

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell

### LabeledCell

A LabeledCell is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    ClueNum
|  | Label/clue number

or a dictionary of one or more of the following:

    "cell": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "value": "str"
|  | Initial value the cell

### CrosswordValue

A CrosswordValue is one of:

    null
|  | Omitted cell
    block value
|  | Block (block value defaults to "#")
    empty value
|  | Normal unlabeled cell (empty value defaults to 0 or "0")
    string
|  | Value for cell
    [ CrosswordValue, ... ]
|  | Multiple values, all apply in all directions

or a dictionary of one or more of the following:

    "value": see above
|  | One of the values listed above
    "style": StyleSpec
|  | The style for the cell
    "Direction": CrosswordValue
|  | Value for a particular clue direction

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.

### Dimension

A Dimension specifies the size of a puzzle in one linear dimension.

    height
|  | Height of the puzzle grid in cells
    width
|  | Width of the puzzle grid in cells

### Direction

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

    Across
|  | Across clues
    Down
|  | Down clues
    Diagonal
|  | Diagonal clues which go down and to the right
    Diagonal Up
|  | Diagonal clues which go up and to the right
    Diagonal Down Left
|  | Diagonal clues which go down and to the left
    Diagonal Up Left
|  | Diagonal clues which go up and to the left
    Zones
|  | Clues for explicitly-specified zones
    Clues
|  | Pre-ordered clues (usually alphabetical)

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

    Diagonal:Southeast
|  | Diagonal clues labeled as "Southeast"
    Across:Horizontales
|  | Across clues in a Spanish puzzle

### 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.

### CrossReference

A CrossReference is a dictionary specifying an entry in the puzzle.

    "direction": "Direction"
|  | Direction of the entry
    "number": ClueNum
|  | Clue number for the clue

Note: A CrossReference is to an entry in the grid. There is a corresponding clue when used with references, but not when used with continued.

### 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"
| = |
    _ _ _ _ _ _ _
| EXAMPLE
    "1-4"
| = |
    _ - _ _ _ _
| U-TURN
    "5 1.1."
| = |
    _ _ _ _ _   _._.
| THREE A.M.
    "0.0"
| = |
    ________.________
| PUZZAZZ.COM

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)
| DOUBLE PLAY
    "0;3"
| = |
    ________   ________   ________ (3 words)
| BAKE A CAKE

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 = _ _ _ _ _ _ _ _ _
| WORDSMITH
    "STARTING LINE=4 4"
| = |
    STARTING LINE = _ _ _ _   _ _ _ _
| PLAY BALL
    "1=3/2"
| = |
    1 = _ _ _ / _ _
| AND/OR
    "DON'T=4'2"
| = |
    DON'T = _ _ _ _ ' _ _
| THEY'RE

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

Some characters in enumerations have special meanings:

    *
|  | The following word is always capitalized
    ^
|  | The following letter is capitalized in this context
    +
|  | The following word is foreign, slang, dialect, obsolete, archaic, etc.

For example:

    "*5"
| = |
    *_ _ _ _ _
| PARIS
    "*10 3"
| = |
    *_ _ _ _ _ _ _ _ _ _   _ _ _
| FAHRENHEIT 451
    "^9 *5"
| = |
    ^_ _ _ _ _ _ _ _ _   *_ _ _ _ _
| PRESIDENT OBAMA
    "^3 ^3 2 3 ^3"
| = |
    ^_ _ _   ^_ _ _   _ _   _ _ _   ^_ _ _
| THE CAT IN THE HAT
    "3 +1 +2 +4"
| = |
    _ _ _   +_   +_ _   +_ _ _ _
| PIE A LA MODE

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"
| = |
    ^_ * ^_ * ^_ * ^_
| M*A*S*H
    "^6 `1`3"
| = |
    ^_ _ _ _ _ _   13
| APOLLO 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
|  | The clue number (matches number in cell)
    "numbers": [ ClueNum, ... ]
|  | Clue numbers for clues that are for multiple entries
    "label": "text"
|  | Text to display in the list of clues instead of the clue number
    "cells": [ [ col1, row1 ], ... ]
|  | Cells, in order, this clue is for
    "clue": "Clue html"
|  | The clue
    "hints": [ "Hint html", ... ]
|  | A series of hints which replace the clue
    "image": "image_url"
|  | Image to show for the clue (clue text becomes alt text)
    "answer": "text"
|  | The answer (see below)
    "enumeration": Enumeration
|  | The enumeration of the answer
    "continued": [ CrossReference, ... ]
|  | Where this clue continues in the grid
    "references": [ CrossReference, ... ]
|  | Other clues referenced by this clue
    "type": "text"
|  | Type of the clue, displayed after successful solve or as a hint
    "explanation": "HTML text"
|  | Explanation, displayed after successful solve or as a hint
    "tags": [ "text", ...]
|  | Tags (e.g., &lit;), displayed after successful solve or as a hint
    "highlight": true/false
|  | True to highlight the clue
    "location": [ col, row ]
|  | Clue location for an ArrowWord puzzle

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. For example, GO FOR IT would have an enumeration of "2,3,2" while DR. NO would have an enumeration of "2.,2". Commas are usually used to separate words in an enumeration, but this is a stylistic decision ("2. 2" is equivalent to "2.,2" or "2., 2"). Only the numbers are officially part of the enumeration, and many apps will not do anything with the contents of the enumeration except display it. 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 specification 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 native 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:

    "*"
|  | Any data change at all
    "field,field,..."
|  | List of fields that require removal
    ""
|  | Not volatile, always roundtrip

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/v2",
        "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": { ... }
    }

Fields inside an extension do not have to be in your namespace, which helps with consistency and readability for both your own own fields and any standard fields you use. This means, for example, that you can define an extension which is very similar to, and uses the same subfields as, a standard field.

    "com.example:circularreferences": [ CrossReference, ... ]
|  | List of circular references

You are not required to document or publicize extensions that you create. However, if your extensions have potential use to the community at large, you can document them and submit them to ipuz@ipuz.org for publication and possible inclusion in a future version of the standard.

If your extensions alter the type of the puzzle, it is recommended that a puzzle kind and corresponding puzzle kind page be created for puzzles that use the extensions.

## 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

1 |
2 |
3 |
4 |
5 |

Across |  | Down
1. | OR neighbor |  | 1. | Trucker's radio
3. | Droid |  | 2. | MSN competitor
5. | Behold! |  | 4. | A preposition

1 |
| C
2 |
| A
3 |
| B
| O
4 |
| T
5 |
| L
| O

C | A |
B | O | T
| L | O

    {
        "version": "http://ipuz.org/v2",
        "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

| 1 | 2
8 |  |
5 |  |
|  | 7
9 |  |
| 4 |
|  | 6
2 |  |
| 4 |
| 7 | 5
|  | 1
6 |  |
6 | 2 |
| 8 |
|  | 6
1 |  |
| 3 |
|  | 9
1 |  |
|  | 7
|  | 5
3 | 4 |

    {
        "version": "http://ipuz.org/v2",
        "kind": [ "http://ipuz.org/sudoku#1" ],
        "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

4+ |
5+ |
4+ |
6x |

4+ |
| 1
5+ |
| 2
| 3
| 3
4+ |
| 1
| 2
6x |
| 2
| 3
| 1

    {
        "version": "http://ipuz.org/v2",
        "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/v2",
        "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 (FAQ)

### What is the current version of ipuz?

This document is for ipuz v2, which replaces ipuz v1 and v1.1. A few parts of ipuz v1/v1.1 (including some fields that were defined inconsistently or incorrectly) have been deprecated in ipuz v2, and it is recommended that all implementors support v2.

### Will there be future versions of ipuz?

As of this writing, no future versions are planned. However, various implementors will undoubtedly create extensions which may make their way into the standard in the future. Time will tell.

### 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. A binary format would also be much harder to work with in code.

### Can I support other formats?

Absolutely.

### Can I still support my own native format?

Yes.

### Can I use ipuz as my application's native format?

Yes, and you can use proprietary extensions to include any information which is not relevant to the standard (e.g., application state). If you do this, it is most convenient for users if you put your application data into as few fields as possible and that you give the field(s) names that are somewhat human readable. If you do this, the warning the user sees when opening your file in another application will be more understandable. For example, a message that says that the data "com.crosswordapp:application-state-information" will be discarded is more useful than one that says the same thing about "com.crosswordapp:asi".

### 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 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.

### Does an application have to support the entire ipuz format?

No, but an application that reads or imports ipuz puzzles must reject any puzzles that contain core features it does not support. Best practice would be to provide the user with a list of fields the puzzles uses that the application does not support.

### 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.

### Who owns ipuz?

Puzzazz owns the ipuz specification. The format is deliberately unencumbered by any intellectual property protection such as patents, contracts, and/or trade secret protection.

### Who owns ipuz extensions?

You own extensions that you create. To the extent that you create extensions which are generally useful, we encourage you to document them and to not encumber usage of them, and, if appropriate, propose them as additions to the ipuz standard.

### Who owns files in ipuz format?

The creator of the puzzle owns the file, meaning they automatically hold the copyright to it, as of the moment the file is created. They may transfer ownership if they so desire. This is the same whether the creator created the ipuz file themselves or whether they used an application or service to create the file.

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

The ipuz specification is copyrighted by Puzzazz 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. The ipuz specification itself is released under a Creative Commons license. 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 a fee to read, write, import, export, or otherwise support ipuz?

No. ipuz is and always will be free.

### Is there a fee to use the ipuz trademark?

No. Use of the ipuz trademark is and always will be free, but you must support the standard to use the trademark in your documentation, marketing materials, or your application, including as a file extension for import or export. If you do not use the ipuz trademark, you may use any part or all of the ipuz format, or a modified version of the format, without any restrictions.

### Can I charge my users a fee to read or write ipuz files?

Yes. There are no restrictions on how you run your business or charge your customers. However, you should make any restrictions clear so that your customers know that they are paying for the feature in your app, not for the ipuz standard itself. Similarly, you should never have an ipuz-related function such as Open or Save just fail without an appropriate message to your customers (e.g., a message that says "Opening imported ipuz files requires upgrading to the Pro version."). Similarly, if an ipuz file is for a puzzle type your app does not support, then you should inform the user of this fact rather than silently failing to open the file.

### Is there reference code available?

Not at this time. If you need assistance supporting ipuz in your application, please email us. 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, Ken Jordan, Scott Kim, Mike Koss, Bruce Leban, Antony Lewis, Parker Lewis, John Locke, Derek Slager, and Robert Stockton for their feedback.

## 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 2015 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.

You are not required to use the ipuz trademark in association with ipuz format puzzles, or with software that reads, writes, and/or stores ipuz format puzzles, but we recommend that you do so. You may only use the ipuz trademark with puzzles and software that conform to the standard.

### 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/v2.
- 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:

- If your software writes or exports ipuz puzzles, any puzzles that are written in ipuz format conform to the standard. Extensions in namespaces are explicitly allowed.
- If your software reads or imports ipuz puzzles and it does not support the entire standard, it must warn users of any features which are not supported (will be lost) when the file is opened A list of field names is sufficient, but better explanations will be appreciated by users. If the puzzle contains extensions which you do not understand, it is recommended that they be listed as well, but it is sufficient to provide the namespace(s) of such extensions. It is also recommended that you provide a brief text description for users explaining what you support, either in the software, documentation, 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, or anywhere else public or private, 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. If desired, 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.