Write a custom spells file

What the file is

A JSON file in the Locanda format with your spells in customSpells, no spellbooks and no settings: the same kind of file that “Export custom spells” saves.

It holds at most 1,000 spells and 5 MB.

Import is all or nothing: if one spell breaks a rule, nothing is added, and the import lists what to fix and where. For a spell whose id is already on this device, you choose whether to replace it or keep both.

An example

A whole file with one cantrip, written in English and Italian. Copy it as a starting point.

{
  "format": "locanda",
  "schemaVersion": 1,
  "exportedAt": "2026-10-25T12:00:00Z",
  "appVersion": "0.0.0",
  "dataVersion": "custom",
  "spellbooks": [],
  "customSpells": [
    {
      "id": "custom:6c49a5ff-2c31-4316-b0ce-0ebd82a9d04d",
      "source": "custom",
      "level": 0,
      "school": "illusion",
      "classes": [
        "bard",
        "sorcerer",
        "wizard"
      ],
      "castingTime": {
        "unit": "action",
        "amount": 1
      },
      "ritual": false,
      "range": {
        "type": "ranged",
        "distance": 30,
        "unit": "feet",
        "area": null
      },
      "components": {
        "v": false,
        "s": true,
        "m": null
      },
      "duration": {
        "type": "timed",
        "amount": 1,
        "unit": "hour"
      },
      "concentration": false,
      "damageTypes": [],
      "savingThrows": [],
      "text": {
        "en": {
          "name": "Lantern Moth",
          "castingCondition": null,
          "material": null,
          "description": "A moth of soft light appears at a point you can see within range. It sheds dim light in a 10-foot radius and follows the path you trace with one finger.",
          "higherLevels": null,
          "cantripUpgrade": "You create one more moth when you reach levels 5, 11 and 17."
        },
        "it": {
          "name": "Falena lanterna",
          "castingCondition": null,
          "material": null,
          "description": "Una falena di luce tenue appare in un punto entro gittata che puoi vedere. Emana luce fioca in un raggio di 3 metri e segue il percorso che tracci con un dito.",
          "higherLevels": null,
          "cantripUpgrade": "Crei una falena in più quando raggiungi il 5°, l'11° e il 17° livello."
        }
      },
      "reference": null,
      "tags": [
        "Homebrew"
      ],
      "createdAt": "2026-10-25T12:00:00Z",
      "updatedAt": "2026-10-25T12:00:00Z"
    }
  ]
}

The fields

Write every field in the tables, in any order. Where a field has nothing to say, write null or [] as the table says; never leave it out. Fields that are not in the tables are refused. Line breaks and tabs are allowed only in the Markdown fields.

The file

Each spell

Allowed values

These fields take only the keys below, written exactly as here, in English whatever the language of the text. The words after a key are how Locanda shows it.

JSON Schemas

To check a file before you import it, or to give a script or an AI assistant the exact rules, download the three JSON Schemas (draft 2020-12):

• Export file schema (urn:locanda:schema:export:1)
• Custom spell schema (urn:locanda:schema:custom-spell)
• Spell schema (urn:locanda:schema:spell)

Load all three into the same validator, then validate the file against urn:locanda:schema:export:1: the schemas refer to each other by these urn: ids, not by web address. The format keywords are for information only, as a pattern checks the same fields. With Ajv, for example:

import Ajv2020 from 'ajv/dist/2020.js';

const ajv = new Ajv2020({ allErrors: true, validateFormats: false });
ajv.addSchema([exportSchema, customSpellSchema, spellSchema]);
const valid = ajv.validate('urn:locanda:schema:export:1', file);
console.log(valid ? 'Valid' : ajv.errors);

A few rules are checked only by Locanda when it imports: a name in at least one language; higher-level text only on spells of level 1 or more, and cantrip text only on cantrips; material text only with a material component; real calendar dates; no two tags alike; and each id only once in the file.

A prompt for an AI assistant

To turn your own notes into a file, give an AI assistant this prompt with the three schemas and the example file attached, then paste your notes after it. Check what it returns: assistants make mistakes.

I will paste notes about spells I wrote for my own game. Turn them into one Locanda custom spells file that follows the attached JSON Schemas (export.schema.json, custom-spell.schema.json and spell.schema.json) and looks like the attached example file.

Rules:
- The file is one JSON object with "format": "locanda", "schemaVersion": 1, "exportedAt" set to the current time in RFC 3339 (UTC), "appVersion": "0.0.0", "dataVersion": "custom", "spellbooks": [] and "customSpells" with one object per spell.
- Give every spell a new random id: "custom:" followed by a lowercase version 4 UUID.
- Use only the English enum keys the schemas allow (schools, classes, units, range types, area shapes, damage types, abilities), even if my notes are in another language.
- Put the words of each spell under "text", in the language of my notes ("en" for English, "it" for Italian). Write null for what my notes do not say. Write descriptions in Markdown, without HTML.
- Give distances in feet.
- Set "createdAt" and "updatedAt" to the same time as "exportedAt", "tags" to [] and "reference" to null, unless my notes give them.
- Do not invent spells, rules or text that are not in my notes. If something the schemas require is missing or unclear, ask me instead of guessing.

Reply with the JSON file only.

My notes:

Copy the prompt

Before you import

• Every spell has a new id of its own (custom: and a fresh UUID), not one copied from the example.
• Every value in the fields above is one of the allowed keys, in English, even when the text is in Italian.
• The file passes a validator with the schemas above. Or simply import it: Locanda checks the whole file first, and if anything is wrong it adds nothing and says what to fix.

Whose spells

Put in the file only spells you wrote yourself or have the right to use, such as your group’s homebrew. Locanda does not check where the text comes from, and the file stays on your device unless you share it.