ipuz PuzzleKind: List

Kind URI: https://puzzling.us/ipuz/list#1 Extension namespace: us.puzzling Status: Version 1, draft (2026-09-28). This file is the kind page for the URI above and will be hosted there.

A list puzzle is a set of independent clues, each with its own answer, presented together under one title and set of instructions. It's the kind of puzzle a daily trivia list or a themed set of fifteen clues is: solvers can answer the clues in any order, and each correct answer fills in one clue.

A list is a variant of the standard http://ipuz.org/answer kind (puzzles with independent answers). That kind supports a single question, a riddle, or a flat. It has no way to attach separate clue text to each of several answers, which is what this kind adds. Everything else uses standard ipuz v2 fields wherever one exists. Fields the standard lacks are extensions in the us.puzzling namespace, as the ipuz Extensions rules require.

Kind declaration

"kind": [ "http://ipuz.org/answer#1", "https://puzzling.us/ipuz/list#1" ]

Kinds are listed from least to most specific, as ipuz requires. An application that only understands answer sees a puzzle with hidden answers. It can show the title and intro, but it can't show the clues, because clues is defined by this kind rather than by answer.

Writers should also declare that us.puzzling fields always round-trip:

"volatile": { "us.puzzling": "" }

Full and public forms

A list puzzle exists in two forms:

A public form must not contain any of these fields:

Level Fields that must be absent
Puzzle misses, checksum, solution, saved, guesses, answer, answers
Clue answer, us.puzzling:alternates, us.puzzling:match

checksum isn't just stripped; writers must never emit it in either form. ipuz checksums are salted SHA-1 hashes of the solution. A short answer can be brute-forced from its hash in seconds, so a checksum reveals the answer to anyone who holds the public form.

A public form is still a valid ipuz puzzle. The standard explicitly supports puzzles whose answers are hidden and only enumerated.

Puzzle fields

Field Required Meaning
version yes "http://ipuz.org/v2"
kind yes As above.
clues yes { "Clues": [ Clue, ... ] }. It uses the same shape as a crossword's clue sets, with a single set named Clues, and must contain at least one clue. The order of the array is the order clues are presented.
title no Standard. The puzzle's title (HTML).
intro no Standard. Instructions shown above the clues (HTML).
explanation no Standard. Shown once the whole puzzle is solved (HTML).
author, editor, copyright, publisher, publication, notes, difficulty, url, uniqueid, annotation, origin no Standard, with standard meanings.
date no Standard (mm/dd/yyyy), the publication date. See Publication date.
misses no Standard { "guess": "message" }. A guess that matches a key (under the matching rules) without solving any clue shows the message. Messages apply to the whole puzzle, not to one clue. Full form only.
us.puzzling:enumerationstyle no How enumerations are displayed: "count", e.g. (5, 3), or "blanks", e.g.   . Defaults to "count". It has no effect on clues without an enumeration.

Fields that version 1 does not define for this kind are choices, randomize, requiredanswers, enumerations and styles. Writers must not emit them. Readers should reject puzzles that use them, as the ipuz FAQ requires of any unsupported core feature.

Clue fields

Every clue must be a Clue dictionary. The ipuz shorthand forms (a bare string, or [number, "text"]) have nowhere to put the required id.

Field Required Meaning
us.puzzling:id yes The clue's stable identifier, a string (a UUID is recommended). It must be unique within the puzzle. Once a puzzle has been published, a clue's id must never change and must never be reused for a different clue. Solve progress is recorded against it, so reordering, re-sorting or editing clues keeps progress attached to the right clue.
clue yes Standard. The clue text (HTML).
enumeration no Standard Enumeration. When it's absent, no length hint is shown for that clue.
label no Standard. Text shown in place of the clue's number. Without it, clues are numbered 1, 2, 3… by position.
explanation no Standard. Shown after this clue is solved (HTML).
answer full form Standard. The answer as solvers should see it once they've solved the clue, including spacing, punctuation, capitalisation and accents. When a guess is correct, the app displays and records this text, not what the solver typed. It never contains escape characters.
us.puzzling:alternates no Full form only. Additional strings that also solve this clue, e.g. alternative spellings. A correct alternate is credited, and displayed, as answer. It may use escapes.
us.puzzling:match no Full form only. A stricter version of answer for matching, written with escapes to mark characters that must be typed. Removing its escape characters must yield exactly answer; for example, answer "EVERY DAY" pairs with us.puzzling:match "EVERY\\ DAY". When it's absent, guesses are matched against answer.

The standard Clue fields number, numbers, cells, continued, references, location, hints, image, type, tags and highlight are not defined for version 1 of this kind. Writers must not emit them.

No two clues may share an answer. Within one puzzle, no clue's answer, us.puzzling:match or alternate may match another clue's under the matching rules. Otherwise one guess would solve two clues. Authoring tools should prevent this, and servers should reject it.

Enumerations

Enumerations use the standard ipuz grammar unchanged, in brief:

Write enumerations without surrounding parentheses and without word counts in the text. The display style is controlled by us.puzzling:enumerationstyle.

Because the public form has no answers, enumerations can't be computed from them at display time. An authoring tool that shows letter counts must write each clue's enumeration explicitly, normally derived from answer and editable by the author.

Cues (=) aren't used by this kind. The capitalisation and foreign-word markers (*, ^, +) are accepted, and may be ignored for display.

Answer matching

These rules decide whether a solver's guess solves a clue or triggers a misses message. They apply to answer, us.puzzling:match, each alternate and each misses key. Solvers' guesses never contain escapes: a backslash typed by a solver is just a backslash.

  1. Only letters and digits count, as Unicode letters (\p{L}) and numbers (\p{N}). Spaces and punctuation are ignored, so every day, EVERYDAY and Every-Day! are the same guess.
  2. Comparison ignores case.
  3. Accents are folded (NFKD decomposition with combining marks removed), so CAFE matches café. Compatibility forms such as full-width letters fold too.
  4. A backslash \ or backquote ` before a character makes that character required exactly as written, including a space, a punctuation mark, or an accent. EVERY\ DAY rejects EVERYDAY; CAF\É rejects CAFE. A character escaped anywhere in a string is required everywhere it appears in that string. \\ and `` are literal escape characters. A trailing lone escape is ignored.
  5. Runs of whitespace count as one space, and leading and trailing whitespace is ignored.

When checking a guess, a clue's answer (or us.puzzling:match) is tried against every clue before any alternates are tried. So a guess that exactly matches one clue's answer is never credited to a different clue that lists the same text as an alternate.

Guess Matched against Result
every day EVERYDAY match
EVERYDAY EVERY\ DAY no match
every day EVERY\ DAY match
cafe café match
cafe CAF\É no match
Reykjavik Reykjavík match
a-b-c A\-B-C match (both dashes required)
abc A\-B-C no match
(empty) anything no match

HTML

As in all ipuz, title, intro, explanation, author and clue are HTML. A tool that takes plain-text input must escape &, < and > when writing these fields. Readers must sanitize them before display, because a puzzle can come from any source.

Publication date

date is the standard ipuz publication date. On whats.puzzling.us the authoritative publication time is the atproto record's own publishAt field. When the server writes the public form, it sets date from publishAt, overwriting any date in the submitted document. How a date is presented to solvers (e.g. "Thursday of Oceanography Week") is up to the website and is not part of the puzzle data.

Example

Full form:

{
  "version": "http://ipuz.org/v2",
  "kind": [ "http://ipuz.org/answer#1", "https://puzzling.us/ipuz/list#1" ],
  "volatile": { "us.puzzling": "" },
  "title": "CAPITALS",
  "intro": "Name each capital city.",
  "date": "10/15/2026",
  "us.puzzling:enumerationstyle": "count",
  "clues": { "Clues": [
    { "us.puzzling:id": "4b0f6c52-8a3e-4d1a-9f0e-2c7d1e5a9b31",
      "clue": "Capital of France",
      "enumeration": "5",
      "answer": "Paris" },
    { "us.puzzling:id": "a9e2d7c4-1f3b-4e6a-8c5d-0b9f2e7a4c18",
      "clue": "Capital of Myanmar",
      "enumeration": "9",
      "answer": "Naypyidaw",
      "us.puzzling:alternates": [ "Nay Pyi Taw", "Naypyitaw" ] },
    { "us.puzzling:id": "e5c1b8a3-7d2f-4a9e-b6c0-3f8d1a2e5b74",
      "clue": "Where the Ring Road ends up, sort of",
      "enumeration": "9",
      "answer": "Reykjavík" }
  ] },
  "misses": { "Yangon": "Former capital. Try the current one." }
}

The same puzzle in public form:

{
  "version": "http://ipuz.org/v2",
  "kind": [ "http://ipuz.org/answer#1", "https://puzzling.us/ipuz/list#1" ],
  "volatile": { "us.puzzling": "" },
  "title": "CAPITALS",
  "intro": "Name each capital city.",
  "date": "10/15/2026",
  "us.puzzling:enumerationstyle": "count",
  "clues": { "Clues": [
    { "us.puzzling:id": "4b0f6c52-8a3e-4d1a-9f0e-2c7d1e5a9b31",
      "clue": "Capital of France",
      "enumeration": "5" },
    { "us.puzzling:id": "a9e2d7c4-1f3b-4e6a-8c5d-0b9f2e7a4c18",
      "clue": "Capital of Myanmar",
      "enumeration": "9" },
    { "us.puzzling:id": "e5c1b8a3-7d2f-4a9e-b6c0-3f8d1a2e5b74",
      "clue": "Where the Ring Road ends up, sort of",
      "enumeration": "9" }
  ] }
}

Versioning

Following the ipuz rules for PuzzleKinds, #1 is incremented only for an incompatible change, or for a new field whose omission by an older reader would display a puzzle incorrectly. New fields that readers can safely ignore are added without a version change and are listed here with the date they were introduced.

Background

whats.puzzling.us originally used its own text format, Puzzle-Flavored Markdown (PFMD). PFMD was designed so authors could write puzzles in an ordinary text editor. Once the site provides its own editor, that advantage goes away. So puzzles move to ipuz, the open standard used across puzzle software, and this kind adds only what the standard lacks.