スクロールファイルの仕様

スクロールファイルはひとつの JSON オブジェクトです。スクロールの詳細、アイデアを含む章、任意の翻訳が入ります。このページでは、読み込み時に読まれるすべてのオブジェクトとフィールドを説明します。

ダウンロード

• サンプルファイル: よく使うフィールドをすべて含む架空のスクロールです。画面の15言語すべての完全な版が入っています。
• JSON スキーマ: 同じルールを機械で読める形 (JSON Schema 2020-12) にしたもので、エディター、スクリプト、AI エージェント向けです。上限は読み込み処理と同じコードから取られています。

構造

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

スクロール (Scroll)

ルートのオブジェクトです。スキーマでは、ほかのオブジェクトを Chapter (章)、Idea (アイデア)、Translation (翻訳)、TranslatedChapter、TranslatedIdea と呼びます。

章 (Chapter)

アイデア (Idea)

翻訳 (Translation)

translations の各項目は、その言語でのスクロールの完全な版です。章、アイデア、例は、元の版と同じ順序、同じ数でなければなりません。

TranslatedChapter には空でない title と、元の章と同じ数のアイデアを含む ideas があります。TranslatedIdea には空でない text と、元のアイデアと同じ数で空のものがない examples があります。翻訳したアイデアには tier を入れません。元の版から引き継がれ、違う値は拒否されます。

読み込み時の値の扱い

• 文字列は前後の空白が取り除かれ、長さは見た目の文字単位で数えます。
• 空の任意フィールドは、ないものとして扱われます。
• ここで説明していないフィールドは無視されます。
• 読む人には自分の言語の版が表示され、なければ元の版が表示されます。

例

{
  "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": []
            }
          ]
        }
      ]
    }
  }
}

上限

よくある読み込みエラー

• ファイルが有効な JSON ではない。 アシスタントに「有効な JSON だけ」を頼むか、カンマや引用符の抜けを探します。JSON オブジェクトの前後にある文章は消してください。
• 言語がない。 ja などのコードで "language" を加えます。
• アイデアや例が長すぎる。 メッセージに言語、章、アイデア、例が示されるので、その文を短くします。
• 翻訳が一致しない。 どの版も、章、アイデア、例の数と順序をそろえる必要があります。
• アイデアが多すぎる、またはファイルが大きすぎる。 情報源を2つのスクロールに分けます。
• 所有できるスクロールの上限に達している。 不要になったスクロールを置き換えます。編集・置き換え・共有 を参照してください。