SakeScript 形式仕様

各 SakeScript ZIP アーカイブは、1 つの学習コンテンツ単位（たとえばストーリー、ニュース記事、レッスン、練習問題）を表します。アーカイブには次が含まれます。

マニフェストファイル: 学習コンテンツのメタデータを含む manifest.json
コンテンツファイル: main.json と、学習素材を構成する各種ファイル（テキスト、画像、音声）

SakeScript アーカイブの作成には zip CLI を使えます。必要なファイル（JSON、画像など）をすべて含めてください。例:

zip my-story-name.zip manifest.json main.json images/*

main.json: コンテンツファイル形式

main.json には学習素材の本文を記述します。SakeScript は現在、story と article の 2 種類をサポートしています。各形式は以下の通りです。

title: 言語コードからタイトルへのマップ（例: "en": "The Mountain Trail"）
cover: このフィールドは画像ファイルに対応します。uri には外部画像 URL（例: "https://example.org/cover.jpg"）またはアーカイブ内画像ファイルへの相対パス（例: "images/cover.jpg"）を指定できます。例:

    "cover": {
        "type": "image",
        "uri": "images/cover.jpg" // or "https://example.org/cover.jpg"
    }

type: コンテンツ種別（"story" または "article"）
chapters: 章の一覧
- title (optional): 現時点では story 型でサポート。言語コードからタイトルへのマップ（例: "en": "About Tokyo"）
- sentences: 文の一覧
  - ja: 日本語文
  - en: 英語文

{
    "title": {
        "en": "Journey Through Japan",
        "ja": "日本の旅"
    },
    "cover": {
        "type": "image",
        "uri": "https://www3.nhk.or.jp/news/html/20231111/K10014254991_2311111600_1111160953_01_02.jpg"
    },
    "type": "story",
    "chapters": [
        {
            "title": {
                "en": "About Tokyo",
                "ja": "東京について"
            },
            "sentences": [
                {
                    "ja": "東京は日本の首都です。",
                    "en": "Tokyo is the capital of Japan."
                },
                {
                    "ja": "新宿はにぎやかな場所です。",
                    "en": "Shinjuku is a bustling area."
                }
            ]
        }
    ]
}

manifest.json: メタデータ形式

各 SakeScript アーカイブの manifest.json には次のフィールドがあります。

id: コンテンツの一意なスクリプト識別子（例: UUID）
type: コンテンツ種別（例: "story"、"article"）
version: 形式バージョン（例: "1.0"）
title: 言語コードからタイトルへのマップ（例: "en": "The Mountain Trail"）
created: 作成日。RFC3339 形式（2020-12-29T12:00:00Z）
modified: 最終更新日。RFC3339 形式（2020-12-29T12:00:00Z）
author: コンテンツ作者または作成者
language: コンテンツの主言語
summary: 言語コードから要約へのマップ（例: "en": "A beginner-level story about a hike in the mountains."）
license: コンテンツのライセンス（例: "Creative Commons"）
tags: コンテンツのタグ一覧
Optional fields:
teaserImage (optional): コンテンツのティーザー画像
authorTwitter (optional): 作者の X/Twitter ハンドル
authorNote (optional): コンテンツに関する作者メモ
origin (optional): 元ソース URL

例

{
    "id": "474007F8-F307-42F5-BA0E-E8B4547C7DAF",
    "type": "story",
    "version": "1.0",
    "title": {
        "en": "The Mountain Trail",
        "ja": "山道"
    },
    "author": "SakeSaySo",
    "authorTwitter": "sakesayso",
    "authorNote": "demo story",
    "teaserImage": "https://raw.githubusercontent.com/sakesayso/community/master/non-fiction/sci/2F98A92E-B14F-435F-B62E-2AD91FD0E862/cover.jpg",
    "created": "2020-12-13",
    "modified": "2023-12-13",
    "summary": {
        "en": "A beginner-level story about a hike in the mountains.",
        "ja": "初級者向けの山登りの話。"
    },
    "tags": [
        "BIZ",
        "N3"
    ],
    "license": "Creative Commons Attribution-ShareAlike",
    "origin": "https://www3.nhk.or.jp/news/easy/k10014288051000/k10014288051000.html"
}

注: 実際に一意な UUID を生成するため、uuidgen、https://www.uuidgenerator.net/ などの利用を推奨します。

カバー画像を含める場合は、ファイルサイズを抑えるため JPEG 形式を推奨します。たとえば DALL·E などで作成した PNG を JPEG に変換するには、ImageMagick で次のコマンドを使えます: convert cover.png -resize 1080x -quality 92 cover.jpg。

推奨コンテンツタグ

SakeScript では JLPT レベル（N1-N5）に加えて、コンテンツ分類用の任意タグを使えます。JLPT レベルタグを 1 つ、さらにコンテンツタグを少なくとも 1 つ付けることを推奨します。

ノンフィクション系コンテンツでは次のタグを推奨します。

AME - 芸術、メディア、エンタメ
TEC - 技術、インターネット
SCI - 科学、環境
MED - 健康、医療、フィットネス
SPO - スポーツ、e スポーツ
LIF - ライフスタイル、余暇
POL - 政治、社会
BIZ - 金融、ビジネス、経済、軍事

フィクション系コンテンツでは次のタグを推奨します。

ADV - 冒険、探検
COM - コメディ、ユーモア
DRA - ドラマ、人間関係
DYS - ディストピア、社会批評
FAN - ファンタジー、神話
HIS - 歴史、時代物
SFI - SF、未来志向
THR - スリラー、ミステリー

リポジトリ index ファイル

リポジトリでは、利用可能な SakeScript 素材を一覧化するために index.json を管理します。この index は各アーカイブの manifest から自動生成され、次を含みます。

path: リポジトリ内の SakeScript ZIP への相対パス
sha256: ZIP アーカイブの SHA-256 整合性ハッシュ
manifest: 抽出済みマニフェストデータ

例

[
  {
    "path": "the-mountain-trail.zip",
    "sha256": "bf35415b1ee00fe56e6a8016848d7c7c35e392ca4732716dfce190a403b8303a",
    "manifest": {
      "id": "474007F8-F307-42F5-BA0E-E8B4547C7DAF",
      "version": "1.0",
      "title": {
        "en": "The Mountain Trail",
        "ja": "山道"
      },
      "author": "SakeSaySo",
      "authorTwitter": "sakesayso",
      "authorNote": "demo story",
      "created": "2020-12-13",
      "modified": "2023-12-13",
      "difficulty": "beginner",
      "summary": {
        "en": "A beginner-level story about a hike in the mountains.",
        "ja": "初級者向けの山登りの話。"
      },
      "tags": [
        "LIF",
        "N4"
      ],
      "license": "Creative Commons Attribution-ShareAlike"
    }
  }
  // ...
]

コントリビューションと利用ガイドライン

SakeScript 素材の投稿と利用について詳しくは、コンテンツリポジトリ https://github.com/sakesayso/community を参照してください。

SakeScript への投稿

コンテンツを用意し、SakeScript ZIP ファイルにまとめる
正確なメタデータを含む manifest.json を含める
リポジトリ内の適切なディレクトリに ZIP ファイルを配置する
index.json がマージ後に更新されることを確認する（通常は自動）

コンテンツライセンス

私たちは “Creative Commons Attribution-ShareAlike” ライセンスの利用を推奨しています。このライセンスでは、元作者のクレジット表示と、派生物を同じ条件で共有することを条件に、商用・非商用を問わず利用、改変、再配布が可能です。これは、作者への適切な評価を保ちつつ、協力的でオープンな学習環境を促進します。

自分のコンテンツにライセンスを付けるには？

manifest.json に “Creative Commons Attribution-ShareAlike” を記載するだけです。適用方法の詳細は Creative Commons を参照してください。

main.json: コンテンツファイル形式#

manifest.json: メタデータ形式#

推奨コンテンツタグ#

リポジトリ index ファイル#

コントリビューションと利用ガイドライン#

SakeScript への投稿#

コンテンツライセンス#

自分のコンテンツにライセンスを付けるには？#