SCRIPTMETA は、スクリプト配布ページとスクリプト本体に埋め込める、軽量な更新検知用メタデータフォーマットです。
Adobe アプリ用の jsx スクリプトは、配布チャネルとスクリプト本体の結びつきが弱く、配布後に不具合修正や更新があっても、利用者が気づきにくいという問題があります。
この問題を解消するため、次の 2 点を行います。
- スクリプト自体に、バージョンと配布ページを示すメタデータを埋め込む
- note、Qiita、gist などの配布ページに、平文のメタデータを記載する
スクリプトコメントと配布ページの両方を仕様に沿ってパースすれば、利用者側でバージョンアップを検知するアプリケーションを作成できます。
また、配布側は特別なサーバーやサービスに切り替える必要がありません。現在使っている Web サービスをそのまま利用できます。
機械的に読み取りやすいという点では、可能であれば gist を推奨します。
SCRIPTMETA は 自動ダウンロードや自動インストールを目的としません。jsx を直接ダウンロードさせることは禁止します。アプリ実装側で zip や jsx などのスクリプト拡張子を弾いてください。更新検知後の取得と導入は、利用者が配布ページを確認して手動で行います。jsx は、もともとセキュリティ面では自己責任で利用するものだからです。
SCRIPTMETAは、人が読めるコメントを入れられるなら対応できます。jsxやAppleScriptにブロックコメントで、できるだけスクリプトの先頭側に入れておきましょう。 難読化jsx（jsxbin）の場合は、難読化したものを普通のjsx中に埋め込むことができますので、冒頭に普通にタグを置くことができます。
（参考：ExtendScript│JSXコードの一部だけを難読化（暗号化）する方法│jsxbin）
スクリプトのコメントブロック内に、SCRIPTMETA-BEGIN と SCRIPTMETA-END で囲んだメタ情報を記述します。
必須項目:
Script-IDVersionMeta-URL
例:
/*
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.1
Meta-URL=https://gist.github.com/Yamonov/d06d117b56445e52b30764b9c994356c
SCRIPTMETA-END
*/
説明:
Script-IDは必ず一意になるようにします。逆ドメイン記法を推奨します。Versionはパーサ側で比較できればよいため、1.1、1.1.1、1.1.1.1のような形式でも問題ありません。Meta-URLは更新情報を取得するためのページです。できるだけ永続的な URL を使用してください。
配布ページ（note、Qiita、gist など）には、最新版情報を記述します。平文で、ページ内の見える場所（有料部分でないところ）に書いてください。フォントサイズや色、コードブロック内に置く等は自由ですが、人に見えているほうが良いでしょう。
gist の場合は、SCRIPTMETA.txt を作成してそこに記述してください。このテキストファイルを優先して探します。
GitHub リポジトリを配布ページとして使う場合も、repo 直下に SCRIPTMETA.txt を置くことを推奨します。クライアントはこのテキストファイルを優先して探します。
GitHub リポジトリでも、更新判定の正本は SCRIPTMETA.txt とします。配布物そのものは Releases などの GitHub の機能を使って公開しても構いません。
必須項目:
- 共通:
Script-ID - 最新版情報をこのページで直接示す場合:
Version - 別ページへ案内する場合:
Latest-URL
Version と Latest-URL の両方を記載しても構いませんが、その場合は Latest-URL を優先します。クライアントは移動先でも同じ判定を繰り返します。これは削除漏れ対策です。旧版ページでは Version を残しても構いませんが、非推奨です。
Latest-URL は、次に参照すべき SCRIPTMETA 情報ページの URL です。配布ファイルそのものの URL ではありません。
例:
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
SCRIPTMETA-END
この情報をもとに、クライアントは Latest-URL がないページまで順にたどり、そこで見つかった Version とローカル script の Version を比較します。
配布側ページの 1 つの SCRIPTMETA ブロックには、複数のスクリプト情報を記述できます。
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
Script-ID=org.iwashi.Photoshop_InDesign_Resize
Version=1.5.2
SCRIPTMETA-END
ルール:
Script-IDは必ずレコードの先頭に置きます。- 次の
Script-IDまでを同一レコードと見なします。
同じページを更新して最新版を配布する場合は、Version を更新してください。
更新ページの Latest-URL が未記載の場合、スクリプト記載の Meta-URL のページを最新版のあるページとして扱います。
Version があっても、Latest-URL が記載されていて参照ページと異なる場合は、そちらを優先してチェックします。移動先でも同じ判定を繰り返します。
例:
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
SCRIPTMETA-END
新しいページで最新版を配布する場合は、スクリプト内の Meta-URL ページに記述した SCRIPTMETA ブロックを編集し、新しいページの URL を Latest-URL として記載してください。旧版ページに Version を残しても構いませんが、非推奨です。
例:
元が次の状態なら、
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign
Version=1.1
SCRIPTMETA-END
次のように変更します。
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign
Latest-URL=https://example.com/page2
SCRIPTMETA-END
Latest-URL 先の SCRIPTMETA ブロックには、新しい Version を入れてください。
# example.com/page2
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign
Version=1.2
SCRIPTMETA-END
さらに配布ページを先へ送る場合は、次の形にします。
- 最も古いページ: 2 へのリンクを持つ
SCRIPTMETA。バージョン表記なし - 次のページ: 3 へのリンクを持つ
SCRIPTMETA。バージョン表記なし - 最新ページ:
VersionありのSCRIPTMETA
つまり、ひとつ前のページだけを変更する運用にします。こうすることで、古いバージョンの利用者も順にたどることができ、開発側の負担も小さくなります。
クライアントの動作:
- スクリプト記載の
Meta-URLを見に行く - そのページ内の
SCRIPTMETAブロックから、対象のScript-IDのレコードを確認する Latest-URLがあれば、その URL を次の参照先とする- 移動先でも同じ
Script-IDのレコードを確認し、Latest-URLがある限りこの判定を繰り返す Latest-URLがなく、Versionがあれば、そのページを最新情報のあるページとして扱うLatest-URLがなく、Versionもない場合は、最新版不明として最後に見つけたページを最新候補とし、未解決フラグを立てるLatest-URLの循環参照を防ぐため、クライアント側でページ遷移回数に適切な上限を設けるLatest-URLがないページを見つけられない場合も、最後に見つけたページを最新候補として扱い、未解決フラグを立てる
クライアント側で最終ページ URL をキャッシュしておくとよいでしょう。
更新確認は、クライアントで利用者が更新ボタンを押したときに行うことを基本とします。自動的に確認する場合でも、確認間隔は 1 日単位以上とすることを推奨します。
Meta-URL が GitHub リポジトリの URL を指す場合、クライアントは repo 直下の SCRIPTMETA.txt を探します。
SCRIPTMETA.txt が見つかった場合は、その内容を通常の配布ページと同じようにパースします。
GitHub の HTML 本文や latest release は、更新判定の正本としては扱いません。GitHub を配布に使う場合も、更新判定は SCRIPTMETA.txt を基準にします。
SCRIPTMETA は次のルールで記述します。
Key=Value形式- 区切りは最初の
=のみ - UTF-8 テキスト
- 空行は無視
- 不明キーは無視可能
- 複数行の値は禁止
- ただしスクリプト内の説明文は
Description-BEGINとDescription-ENDのブロック形式で記述できます Description-BEGINとDescription-ENDは単独行でのみ有効です- 説明文ブロック内はキーとして解釈しません
- 説明文ブロックは、直前の
Script-IDのレコードに属します - 説明文ブロックは 1 レコードにつき 1 個までです
- 配布ページで
Description-BEGINとDescription-ENDがあっても、クライアントは無視します
Script-ID はスクリプトを識別する ID です。逆ドメイン記法を推奨します。ドメインを持っていなくても、他と重ならない一意の ID にしてください。
逆ドメイン記法を推奨するのは、一意の ID を作りやすいためです。
また、各レコードの先頭に置いてください。複数のスクリプト情報を記載する場合は、Script-ID がレコードの区切りになります。
空行は無視します。
例:
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
Script-ID=org.iwashi.Photoshop_InDesign_Resize
Version=1.5.2
SCRIPTMETA-END
使用可能文字:
A-Za-z0-9._-
バージョンチェック用の参照 URL です。スクリプト側の必須項目です。
そのスクリプトが最初に見に行く配布ページ URL を指定します。
Meta-URL には、note、Qiita、gist、GitHub リポジトリなどの URL を指定できます。gist や GitHub リポジトリでは、クライアントは SCRIPTMETA.txt を探し、それを更新判定の正本として扱います。
例:
Meta-URL=https://gist.github.com/Yamonov/d067b564...
日本語や空白を含む場合は URL エンコードしてください。
スクリプト内のバージョンと配布側のバージョンを比較するための項目です。
スクリプト側では必須です。配布側では、そのページで最新版を直接示すレコードで必須です。
バージョンは . 区切りの整数列とします。
例:
1
1.5
1.5.2
1.5.2.1
別のページにある新しい SCRIPTMETA 情報へ案内するための項目です。
このキーがある限り、クライアントはその URL を順にたどります。最新版配布ページでは書かないことを推奨します。旧版ページで Version と併記することは可能ですが、非推奨です。記載中のページと同じ URL であれば無視します。
Latest-URL は、次に参照すべき SCRIPTMETA 情報ページの URL を示します。配布ファイルそのものの URL ではありません。
例:
Latest-URL=https://gist.github.com/Yamonov/d067...
SCRIPTMETA ブロック内に Version と Latest-URL の両方がある場合は、Latest-URL を優先してチェックします。移動先にも Latest-URL があれば、同じ判定を繰り返します。最終的に Latest-URL がなく、Version があるレコードの値を使います。これは削除漏れ対策です。旧版ページでの併記は可能ですが、非推奨です。
複数行の説明文を記述するためのブロックです。
この項目はスクリプト内でのみ使用します。配布ページに記述されていても、クライアントは無視します。
書式:
Description-BEGIN
ここに説明文
複数行可
Description-END
ルール:
Description-BEGINとDescription-ENDの間の内容を説明文として扱います- 改行を含めて保持します
- 改行コードの正規化はパーサ側で行います
Description-BEGINとDescription-ENDは単独行でのみ有効です- 説明文ブロック内はキー解析しません
- 説明文ブロックは直前の
Script-IDのレコードに属します - 説明文ブロックは 1 レコードにつき 1 個までです
以下はオプションです。
| Key | スクリプト側 | 配布ページ側 | 説明 |
|---|---|---|---|
| Target-App | ○ | ○ | Illustrator、Photoshop、InDesign、Bridge を指定します。大文字小文字は無視します |
| Min-Target-Version | ○ | ○ | 動作対象バージョンを記載します。2024 のような年表記ではなく、詳細バージョンを記載してください |
| Release-Date | ○ | ○ | リリース日（yyyy-mm-dd） |
| Description（-BEGIN ～ -END） | ○ | - | 複数行の説明文。Description-BEGIN と Description-END で囲んだ部分を、改行も含めて取得します。スクリプトの説明をクライアント側で表示させられます |
| Name | ○ | ○ | スクリプト名 |
- 冒頭付近に書いてください
Script-ID、Version、Meta-URLは必須項目です。Descriptionブロックは、スクリプトの説明をクライアント側で表示させられます。readme.txt等に頼らず、スクリプト本体を開かずに説明を付けられるので、ぜひ活用してください。
jsxの場合の例
/*
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
Meta-URL=https://gist.github.com/Yamonov/d067b564...
Description-BEGIN
Photoshopで実行すると、InDesign上に配置した画像のフレーム枠に合わせて画像サイズを変更します。
・画像より大きいフレームに合わせ、イメージサイズを変更
・画像に食い込む部分にはガイドを付けます
正立のみ対応し、回転した画像には非対応です。
解像度等はそのまま、伸ばした部分は透明になりますので、コンテンツに応じた塗り潰しなどで足してください。
Description-END
SCRIPTMETA-END
*/
- 課金しなくても見えるところに書いてください。htmlパースが前提で、文字サイズ、色に制限はありません。見えなくても構いませんが、人が見て「あること」が分かる方が良いでしょう。
コードブロックとしても構いません。
必須項目はScript-IDで、Versionは最新ページで必須です。旧版ページではLatest-URLが必須で、Versionの併記は可能ですが非推奨です。
- 配布ページを更新して新版を出す場合もこの記法に沿います。
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Version=1.2
SCRIPTMETA-END
- 旧版ページは残し、最新版ページへ飛ばす設定です
Latest-URLを書いてくださいVersionを残しても動作しますが、非推奨です
SCRIPTMETA-BEGIN
Script-ID=org.iwashi.Photoshop_InDesign_Crop
Latest-URL=https://gist.github.com/Yamonov/d067b56
SCRIPTMETA-END
以下を仕様として厳守してください。
- SCRIPTMETA は、スクリプト内コメントと配布ページ内テキストに書ける更新検知用メタデータです。
- スクリプト側の必須項目は
Script-ID、Version、Meta-URLです。 - 配布ページ側の必須項目は
Script-IDと、最新版ページではVersion、旧版ページではLatest-URLです。 - 旧版ページで
Versionを併記してもよいですが、非推奨です。 VersionとLatest-URLが両方ある場合は、必ずLatest-URLを優先してください。Latest-URLは、次に参照するSCRIPTMETA情報ページの URL です。配布ファイルの URL と解釈してはいけません。Meta-URLが gist または GitHub リポジトリを指す場合は、SCRIPTMETA.txtを優先してください。GitHub の HTML 本文や release 情報は正本として扱ってはいけません。SCRIPTMETA.txtが取得できる場合は、HTML 本文より必ず優先してください。- 配布ページが HTML の場合は、まず本文をテキスト化し、そのテキストから
SCRIPTMETA-BEGINとSCRIPTMETA-ENDを探してください。 - HTML では、通常本文とコードブロックのどちらにある
SCRIPTMETAも有効として扱ってください。 - HTML の見た目、文字サイズ、色、CSS による表示状態では判定してはいけません。取得できた本文テキストだけを対象にしてください。
- 1 つの
SCRIPTMETAブロックには複数レコードを書けます。各レコードはScript-IDで始まり、次のScript-IDまでを同じレコードとして扱ってください。 Key=Value形式では、最初の=だけを区切りとして扱ってください。- 改行コードは解析前に
LFに正規化してください。 - 空行は無視してください。
- 不明キーは無視してください。
Descriptionはスクリプト内だけで使う任意項目です。配布ページにあるDescriptionは無視してください。DescriptionはDescription-BEGINとDescription-ENDのブロックで記述し、その間の内容を改行込みで保持してください。Description-BEGINとDescription-ENDは単独行でのみ有効です。Descriptionブロック内はキー解析してはいけません。Descriptionブロックは直前のScript-IDのレコードに属します。Descriptionブロックは 1 レコードにつき 1 個までです。Latest-URLの追跡では循環参照を検出してください。Latest-URLの追跡回数には上限を設けてください。Latest-URLの追跡先で最終的にVersionが見つからない場合は、未解決として扱ってください。- 自動ダウンロードや自動インストールは行ってはいけません。