Scroll file reference

A Scroll file is one JSON object: the Scroll's details, its chapters of ideas, and optional translations. This page describes every object and field the importer reads.

Downloads

• Example file: a made-up Scroll that uses every common field, with complete versions in all 15 interface languages.
• JSON Schema: the same rules in machine-readable form (JSON Schema 2020-12), for editors, scripts and AI agents. Its limits come from the same code the importer runs.

Structure

Scroll
├── language, title, authors, description, tags,
│   sourceUrl, originalYear, originalPeriod
├── summaries: Chapter[]
│   └── ideas: Idea[]
│       └── examples: string[]
└── translations: { language code: Translation }
    └── summaries: TranslatedChapter[]
        └── ideas: TranslatedIdea[]

Scroll

The root object. The schema's names for the other objects are Chapter, Idea, Translation, TranslatedChapter and TranslatedIdea.

Chapter

Idea

Translation

Each entry in translations is a complete version of the Scroll in that language. It must have the same chapters, ideas and examples as the original, in the same order and number.

A TranslatedChapter has a non-empty title and ideas, with as many ideas as the original chapter. A TranslatedIdea has a non-empty text and examples with as many entries as the original idea, none empty. Translated ideas leave tier out: it comes from the original, and a different value is refused.

How the importer reads values

• Text is trimmed at both ends, and lengths count characters as you see them.
• An optional field that is empty is treated as missing.
• Fields not described here are ignored.
• Readers see the version that matches their language, and the original when there is none.

Example

{
  "language": "en",
  "title": "Small steps",
  "authors": ["Ada Example"],
  "description": "How small, repeated actions shape what you notice and do.",
  "tags": ["habits", "attention"],
  "sourceUrl": "https://example.org/small-steps",
  "originalYear": 1841,
  "summaries": [
    {
      "title": "Starting small",
      "ideas": [
        {
          "text": "Make the first step so small that you can take it on a bad day.",
          "tier": "important",
          "examples": ["Read one page every evening."]
        },
        {
          "text": "You notice more of what you have decided to look for.",
          "tier": "common",
          "examples": []
        }
      ]
    }
  ],
  "translations": {
    "de": {
      "title": "Kleine Schritte",
      "authors": ["Ada Beispiel"],
      "description": "Wie kleine, wiederholte Handlungen prägen, was wir bemerken und tun.",
      "tags": ["gewohnheiten", "aufmerksamkeit"],
      "summaries": [
        {
          "title": "Klein anfangen",
          "ideas": [
            {
              "text": "Mach den ersten Schritt so klein, dass er dir auch an einem schlechten Tag gelingt.",
              "examples": ["Lies jeden Abend eine Seite."]
            },
            {
              "text": "Du bemerkst mehr von dem, wonach du zu suchen beschlossen hast.",
              "examples": []
            }
          ]
        }
      ]
    }
  }
}

Limits

Common import errors

• The file is not valid JSON. Ask the assistant for "only valid JSON", or check for a missing comma or quote. Remove any text before or after the JSON object.
• The language is missing. Add "language" with a code such as en.
• An idea or example is too long. The message names the language, chapter, idea and example; shorten that text.
• A translation does not match. Every version needs the same number of chapters, ideas and examples, in the same order.
• Too many ideas, or a file that is too large. Split the source into two Scrolls.
• You already own the most Scrolls. Replace one you no longer need; see Edit, replace and share.