ipuz

Version 2.0

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

The following are non-goals:

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 2014 Puzzazz, Inc.
Creative Commons License

Supporters

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

Kinds of Puzzles

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

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

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

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

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

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

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

The following major PuzzleKind are currently defined:

http://ipuz.org/crosswordGrid puzzle that uses clues for entries.
http://ipuz.org/sudokuSudoku-style logic.
http://ipuz.org/fillGrid puzzle that gets filled in, possibly by moving letters from a bank or other location.
http://ipuz.org/acrosticGrid 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/blockPuzzle with blocks that move.
http://ipuz.org/answerPuzzle with a question and answer
http://ipuz.org/wordsearchPuzzle 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.

The following color coding is used to indicate changes since the v1 specification. Some text corrections which are not a change in meaning from v1 are not marked.

New
This is an addition in 2.0
Changed
This has been changed since 1.0
Moved
No change has been made, but it was moved in the spec

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": "2014 ..."
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
"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 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.

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

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

Sudoku puzzles support the following fields:

"charset": "123456789"
Characters used in the puzzle
"displaycharset": true/false
Display the character set
"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

Sudoku - http://ipuz.org/sudoku

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "version": "http://ipuz.org/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 field 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 valid answers and (optionally) their locations
"solution":  "entry"
Correct answer for the puzzle
"solution":  [ "entry", ... ]
Multiple correct answers 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 field. In this case, the entry may have non-field characters in it which are ignored for matching purposes (e.g., spaces inside phrases).

WordSearch - http://ipuz.org/wordsearch

{
    "version": "http://ipuz.org/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 (currently only circle is allowed)
"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 corner 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.

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

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

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

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

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

GroupSpec

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

"rect": [ 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. 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. This helps with both consistency and readability. 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
 
 
 

AcrossDown
1.OR neighbor1.Trucker's radio
3.Droid2.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

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

Calcudoku

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

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 cheating and viewing the solution, simply omit the solution from the file and use a checksum instead of encryption.

Can ipuz puzzles be compressed?

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

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

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

The ipuz specification is copyrighted and the name is a trademark to ensure that the standard is not splintered and that only puzzles which conform to the standard can use the name. 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, provide you meet the conditions of supporting the standard, as described below.

Is there reference code available?

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

Acknowledgements

This document was authored by Roy Leban for Puzzazz, Inc. 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 2014 Puzzazz, Inc.
ipuz and ipuz.org are trademarks of Puzzazz, Inc.

Through this notice, Puzzazz, Inc. 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:

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

Trademark License

Through this notice, Puzzazz, Inc. 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:

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, Inc.

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

Creative Commons License
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.