The Swords format
A crossword as one small JSON file, named .swords. It holds everything .puz and .jpz hold, plus the things they can’t: grid shapes, walls, emoji on squares, and an ending that plays when the puzzle is solved.
A file named .json with the same content works too. Only grid and clues are required. A reader skips any field it does not know.
{
"title": "Brews",
"author": "A. Constructor",
"grid": ["POLO#", "IRENA", "LAGER", "STOUT", "#ESPY"],
"clues": {
"0,0,across": "Collared knit shirt",
"0,0,down": "Lamp ___, e.g."
},
"ending": { "message": "Cheers!", "effects": ["confetti"], "emoji": ["🍺"] }
}
Squares
A square is named "x,y": column, then row, both from 0 at the top left.
Fields
| Field | What it holds |
|---|---|
title, author, copyright, notes |
Text. notes shows to the solver. |
grid |
One string per row, all the same length. A letter or digit is a square’s answer. # is a black square. |
clues |
Clue text for each answer. The key is the answer’s first square and its direction: "x,y,across" or "x,y,down". The key may also be the answer itself in capitals ("LAGER"), when no other answer has the same letters. <i>…</i> is italics. |
rebus |
Squares with more than one letter: {"2,3": "STAR"}. grid holds the first letter. |
circles |
A list of circled squares. |
shaded |
A list of grey squares. |
colors |
Colored squares: {"1,1": "blue"}. Names: red, orange, yellow, green, blue, purple, pink. |
absent |
A list of squares that are not part of the grid, so the grid can have any shape. Each is also # in grid. |
bars |
Walls between squares: {"3,0": ["right"], "0,2": ["bottom"]}. A wall ends an answer, like a black square. Only right and bottom: a wall on the left of a square is the right wall of its neighbor. |
sprites |
Emoji on squares: {"4,0": {"emoji": "🍺"}}. They may sit on black squares. |
ending |
What the solver sees on finishing. See below. |
Numbering
Clue numbers are not in the file. A reader numbers the grid in reading order: a square gets a number when an answer of two or more squares starts there. Black squares, left-out squares and walls end an answer.
Ending
Every part is optional. It is data, never code, so a file from a stranger is safe to open.
| Field | What it holds |
|---|---|
message |
The headline, in place of “Solved!”. |
note |
A line under it: a punchline, a thank-you, what the theme was. |
effects |
A list, played together: confetti, rain (the emoji fall), burst (the emoji fly out of the grid), wave (the squares flash in a wave). A reader skips a name it does not know. |
emoji |
The emoji that rain and burst use. |
highlight |
A list of squares that light up: a hidden word, a shape. |
link |
A button: {"label": "Next puzzle", "url": "https://…"}. |
scene |
A custom reveal: steps that play over the grid. See below. |
Scene
ending.scene is a custom reveal: a list of steps that play over the grid, in order, right after the solve. The last state stays on the grid. A solver who comes back to a solved puzzle sees that last state at once, and so does a solver who asks for less motion.
A scene is data, never code. It holds no scripts, no HTML, no CSS and no web addresses. A picture is embedded in the file as a data: URL.
"ending": {
"message": "Sunrise!",
"scene": [
{ "kind": "paint", "squares": ["0,2", "1,2", "2,2"], "color": "yellow", "stagger": 0.1 },
{ "kind": "write", "squares": ["0,2", "1,2", "2,2"], "text": "SUN" },
{ "kind": "line", "through": ["0,2", "2,2", "2,0"], "color": "orange", "for": 1.5 },
{ "kind": "image", "src": "data:image/svg+xml;base64,...", "over": { "x": 3, "y": 0, "w": 2, "h": 2 }, "enter": "grow" },
{ "kind": "text", "text": "Here comes the sun" }
]
}
Every step is one object with a kind. Every step may have:
| Field | Meaning |
|---|---|
at |
Seconds after the solve when the step starts, 0 to 60. Left out: the step starts when the step before it ends. |
for |
Seconds the change takes, 0 to 60. Left out: 0.6. An effect step has no for. |
The kinds:
kind |
What it does | Fields |
|---|---|---|
paint |
Recolors squares. | squares, color (both needed), stagger |
write |
Changes what squares show. | squares, text (both needed), stagger |
line |
Draws a line, from its first point to its last. | through (needed), color, width, closed |
image |
Shows a picture. | src (needed), over, fit, opacity, enter |
text |
Shows a caption. | text (needed), over, size, color |
clear |
Removes what earlier steps drew. | steps |
effect |
Plays one of the effects, at this point. |
effect (needed) |
The fields:
| Field | Value |
|---|---|
squares |
A list of squares, "x,y", like everywhere in the format. Black squares and left-out squares count: a step may paint or write on them. The order matters with stagger. |
color |
red, orange, yellow, green, blue, purple or pink (the same names as colors), or hex: #rgb, #rrggbb, #rrggbbaa. A line is red when it has no color. |
stagger |
Seconds between one square and the next, so the change flows along the list. |
text (write) |
One string with one character for each square (a space empties the square), or a list with one string for each square (up to 10 characters each). |
through |
A list of two or more points, "x,y". A whole number is the middle of a square, so "0,0" is the middle of the top left square and "2.5,0" is on the border between squares 2 and 3. |
width |
The line’s width in squares, 0.01 to 1. Left out: 0.12. |
closed |
true joins the last point to the first. |
src |
The picture, as data:image/png;base64,.... The types are png, jpeg, gif, webp and svg+xml. Nothing else is accepted: never a web address. |
over |
Where the picture or caption goes: "grid" (all of it), or a rectangle of squares { "x": 3, "y": 0, "w": 2, "h": 2 }, where x,y is the top left square. Fractions are fine. A caption may also be "below" (under the grid). Left out: "grid" for a picture, "below" for a caption. |
fit |
contain (the whole picture shows; the default), cover (it fills the rectangle and is cropped) or stretch. |
opacity |
0 to 1. |
enter |
How the picture comes in: fade (the default), grow or none. |
text (text) |
The caption, up to 200 characters. |
size |
The caption’s letter height in squares, 0.2 to 5, for a caption over the grid. Left out: 0.6. A caption too wide for its place shrinks to fit. |
steps |
The numbers of the steps to remove. The first step is 1. A step can only remove steps before it. Left out: remove everything, and turn off highlight. |
effect |
confetti, rain, burst or wave. |
Steps that paint or write the same square stack: the later step wins, and clear brings back what was under it.
A picture can be anything
For a reveal the other steps cannot make, draw it as an SVG picture and put it over the grid. Give the SVG a viewBox as wide and tall as the squares it covers, and one unit is one square. An SVG may animate itself with CSS or SMIL. The page draws it as an image, so it cannot run scripts and cannot load other files.
Limits
- At most 40 steps.
- Every step ends within 60 seconds of the solve (
at, plusfor, plus thestaggerof its squares). - At most 2,000 squares or points in one step.
- At most 1.5 MB of pictures in one scene: 1,500,000 bytes of image data, all pictures together, counted after base64 is decoded.
- On this site, a whole puzzle is at most 1.9 MB as stored (1,900,000 bytes of JSON). Base64 makes a picture a third larger, so about 1.4 MB of pictures fit in a puzzle pushed here. A file sent to the site is at most 3 MB.
A file with a step kind or a field that is not listed here is refused, with a message that names the step. A reader that plays a scene skips any step it does not understand.
Convert a puzzle
Push a .puz, .jpz or .ipuz file and the site converts it for you. To get the file itself, send it to /api/convert on this site. Nothing is saved. Put this site’s address in place of SITE:
curl --data-binary @puzzle.puz SITE/api/convert > puzzle.swords
For an AI agent
To put someone’s puzzle on Swords:
- If the puzzle is a
.puz,.jpzor.ipuzfile, send it to/api/convertas shown above. If it is text, a picture or a document, write the JSON above by hand:gridfirst, then one clue for each answer, keyed"x,y,across"or"x,y,down". - Add what the old file could not hold, if the constructor wants it:
absent,bars,sprites,ending(with ascenefor a custom reveal). - Run
puz publish puzzle.swords. It refuses a puzzle with an empty square or a missing clue, and names what is missing. Fix those and push again. - Give the constructor the link it prints. Run
puz publishon the same file later to update the puzzle.
A JSON Schema is at /format.schema.json.