これはBEAR.Sundayの全てのマニュアルページを一つにまとめたページです。

高度な実装ガイド

概要

このドキュメントでは、Application-Level Profile Semantics (ALPS)のより高度な実装トピックについて説明します。基本的な要素や属性の説明についてはALPSリファレンスを参照してください。

ディスクリプタとリンクリレーションタイプ

表現に状態遷移を含める場合、リンクリレーションタイプの有効な値は以下のいずれかを使用できます：

1. 標準リンクリレーションタイプ
   • IANAやMicroformats.orgなどのレジストリに登録された短い文字列
   • 例：rel="edit", rel="next", rel="collection"
   • IANAリンクリレーションを参照
2. 拡張リンクリレーションタイプ ([RFC8288])
   • リレーションタイプを説明する文書の完全修飾URI
   • ALPSディスクリプタへのURIフラグメント識別子を含む
   • 例：rel="http://alps.io/profiles/item#purchased-by"
   • 例：rel="http://alps.io/profiles/blog#comment"
3. ALPSディスクリプタID
   • ALPSドキュメントの状態遷移ディスクリプタのid属性値
   • 表現にALPSプロファイルが含まれる場合のみ使用可能
   • 例：rel="purchased-by"
   • 例：rel="create-comment"

リンクリレーションの競合解決

1. 標準リレーションとの競合
   • 状態遷移ディスクリプタが標準リンクリレーションと同じ意味を持つ場合、その意味を変更してはいけません
   • 例：editという名前のディスクリプタを作る場合、IANA登録済みのeditリレーションの意味と一致する必要があります
2. ID競合の解決
   • 複数のディスクリプタ間でidの競合が発生する場合：
     • 一意のidを定義する必要があります
     • 必要に応じてname属性を使用して元の名前を保持できます
   • 例：

     <descriptor id="user-edit" name="edit" type="safe">
       <doc>ユーザー情報の編集</doc>
     </descriptor>
     

既存メディアタイプとの統合

ALPSは様々な既存メディアタイプと組み合わせて使用できます。以下に主要なメディアタイプとの統合方法を説明します。

HTML

HTMLでは主にclass属性を使用してALPSディスクリプタを表現します：

<div class="blog-post">
  <h1 class="title">記事タイトル</h1>
  <div class="content">本文...</div>
  <form class="add-comment" method="post">
    <input name="comment-text" class="comment-text">
    <button type="submit">コメント追加</button>
  </form>
</div>

対応するALPSプロファイル：

<alps version="1.0">
  <descriptor id="blog-post" type="semantic">
    <descriptor id="title" type="semantic"/>
    <descriptor id="content" type="semantic"/>
    <descriptor id="add-comment" type="unsafe">
      <descriptor id="comment-text" type="semantic"/>
    </descriptor>
  </descriptor>
</alps>

HAL (Hypertext Application Language)

HALではリンクリレーションとして状態遷移を、プロパティとしてセマンティックディスクリプタを表現します：

{
  "_links": {
    "self": {"href": "/posts/1"},
    "add-comment": {"href": "/posts/1/comments"}
  },
  "title": "記事タイトル",
  "content": "本文...",
  "_embedded": {
    "comments": [
      {
        "_links": {
          "self": {"href": "/comments/1"}
        },
        "text": "コメント内容..."
      }
    ]
  }
}

Collection+JSON

Collection+JSONではクエリとデータ要素としてディスクリプタを表現します：

{
  "collection": {
    "version": "1.0",
    "href": "/posts/1",
    "items": [
      {
        "data": [
          {"name": "title", "value": "記事タイトル"},
          {"name": "content", "value": "本文..."}
        ]
      }
    ],
    "template": {
      "data": [
        {"name": "comment-text", "value": "", "prompt": "コメントを入力"}
      ]
    }
  }
}

ALPSドキュメントの参照

ALPSプロファイルを適用する際の参照方法について説明します。

リンクによる参照

1. HTML内での参照

   <link rel="profile" href="http://example.com/alps/blog" />
   

2. HTTP Linkヘッダーでの参照

   Link: <http://example.com/alps/blog>; rel="profile"
   

3. メディアタイプパラメータでの参照

   Content-Type: application/json; profile="http://example.com/alps/blog"
   

複数プロファイルの適用

1つの表現に複数のALPSプロファイルを適用できます：

Link: <http://example.com/alps/blog>; rel="profile",
      <http://example.com/alps/comments>; rel="profile"

プロファイルの優先順位

複数のプロファイルが競合する場合の優先順位：

1. メディアタイプのprofileパラメータで指定されたプロファイル
2. HTTPのLinkヘッダーで指定されたプロファイル
3. 表現内で指定されたプロファイル（先に指定されたものが優先）

エラー処理とバリデーション

実装時の一般的なエラーケースと対処方法について説明します。

よくあるエラー

1. 無効なディスクリプタ参照
   • 解決できないURLやフラグメント識別子
   • 存在しないディスクリプタへの参照
2. リンクリレーションの競合
   • 標準リレーションとの意味的な競合
   • 複数プロファイル間でのリレーション定義の競合
3. メディアタイプの制約
   • 特定のメディアタイプで表現できない要素の存在
   • リンク表現のサポート不足

ベストプラクティス

状態

アプリケーション状態のセマンティックディスクリプタは大文字始まりのアッパーキャメルケースで表されます。

"descriptor": [
  {"id": "BlogPosting", "type": "semantic", "def": "https://schema.org/BlogPosting", "descriptor": [
    {"href": "#id"},
    {"href": "#articleBody"},
    {"href": "#dateCreated"},
    {"href": "#blog"}
  ]}
]

安全な状態遷移

typeがsafeのセマンティックディスクリプタは、次の遷移先のディスクリプタにgoのプレフィックスを付加します。 (RFC8288)

[
  {"id": "goHome", "type": "safe", "rt": "#Home"},
  {"id": "goFirst", "type": "safe", "rt": "#TodoList"},
  {"id": "goPrevious", "type": "safe", "rt": "#TodoList"}
]

safe以外のセマンティックディスクリプタには、doの接頭辞をつけます。

[
  {"id": "doEditUser", "type": "idempotent", "rt": "#UserList"},
  {"id": "doDeleteUser", "type": "idempotent", "rt": "#UserList"}
]

rt（遷移先）のIDはgoまたはdoのプレフィックスに次の遷移先のディスクリプタIDを付加します。

[
  {"id": "goBlogPosting", "type": "safe", "rt": "#BlogPosting"},
  {"id": "doEditBlogPosting", "type": "idempotent", "rt": "#Blog"}
]

要素

アプリケーション状態として定義されないセマンティックディスクリプタ、つまり要素(element)のセマンティックディスクリプタは小文字始まりのローワーキャメルケースで表記します。

[
    {"id": "articleBody"},
    {"id": "dateCreated"}
]

ALPSファイルの構造

ALPSファイルのセマンティクディスクリプターは以下の順の3つのブロックに分けます。

1. defやdocを用いた意味定義のセマンティックディスクリプタ群（オントロジー）
2. 包含関係のセマンティックディスクリプタ群（タクソノミー）
3. 状態遷移のセマンティックディスクリプタ群(コレオグラフィー)

"descriptor" : [
    {"id" : "name", "type" : "semantic", "def": "http://schema.org/identifier"},
    {"id" : "age", "type" : "semantic", "def": "http://schema.org/title"},

    {"id" : "Person", "type": "semantic", "descriptor":[
      {"href": "#name"},
      {"href": "#age"}
    ]}
    
    {"id": "goPerson", "type": "safe", "rt": "#Person"},
]

ALPSの外にある階層構造

ALPSでは、階層的な意味をポジションで表現できます。

"descriptor": [
    {"id": "name", "def": "https://schema.org/name"},
    {"id": "Product", "descriptor":[
      {"href": "#name"}
    ]}
    {"id": "Person", "descriptor":[
      {"href": "#name"}
    ]}
]

• 上記の例では、nameは、Product/nameとPerson/nameで共有されています。 このような語をフラットな階層しかないフォーマットで表現する場合には、各フォーマットの慣習に従うのが基本です。
• htmlの場合は、Lower camel caseで表します。

<form>
    <input name="productName" type="text">
    <input name="personName" type="text">
</form>

スキーマ参照の追加

ALPSプロファイルを作成する際には、スキーマ参照を追加することをお勧めします。

{
  "$schema": "https://alps-io.github.io/schemas/alps.json",
  "alps" : {
  }
}

<alps 
  version="1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
</alps>  

実装例

セマンティック要素

基本要素の定義：

<descriptor id="title" title="タイトル" doc="記事のタイトル。最大100文字。"/>
<descriptor id="content" title="内容" doc="記事の本文。Markdown形式をサポート。"/>
<descriptor id="publishedAt" title="公開日時" doc="記事の公開日時。ISO 8601形式。"/>

{
    "descriptor": [
        {"id": "title", "title": "タイトル", "doc": {"value": "記事のタイトル。最大100文字。"}},
        {"id": "content", "title": "内容", "doc": {"value": "記事の本文。Markdown形式をサポート。"}},
        {"id": "publishedAt", "title": "公開日時", "doc": {"value": "記事の公開日時。ISO 8601形式。"}}
    ]
}

基本要素の再利用：

<descriptor id="blogPost">
    <doc>ユーザーが作成した記事。公開後は全てのユーザーが閲覧可能。</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
    <descriptor href="#publishedAt"/>
</descriptor>

<descriptor id="pagePost">
    <doc>固定ページ。サイトの基本情報などの永続的なコンテンツ。</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
</descriptor>

{"descriptor": [
    {"id": "blogPost", "doc": {"value": "ユーザーが作成した記事。公開後は全てのユーザーが閲覧可能。"}, "descriptor": [
        {"href": "#title"},
        {"href": "#content"},
        {"href": "#publishedAt"}
    ]},
    {"id": "pagePost", "doc": {"value": "固定ページ。サイトの基本情報などの永続的なコンテンツ。"}, "descriptor": [
        {"href": "#title"},
        {"href": "#content"}
    ]}
]}

操作の定義

<descriptor id="goBlog" type="safe" rt="#Blog" doc="ブログのトップページを表示。最新10件の記事を一覧表示。"/>

<descriptor id="doCreateBlogPost" type="unsafe" rt="#BlogPost">
    <doc>新規記事を作成。下書き状態で保存される。</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
</descriptor>

<descriptor id="doPublishBlogPost" type="idempotent" rt="#BlogPost">
    <doc>記事を公開。publishedAtに現在時刻が設定される。</doc>
    <descriptor href="#id"/>
</descriptor>

{"descriptor": [
    {"id": "goBlog", "type": "safe", "rt": "#Blog", "doc": {"value": "ブログのトップページを表示。最新10件の記事を一覧表示。"}},
    {"id": "doCreateBlogPost", "type": "unsafe", "rt": "#BlogPost", "doc": {"value": "新規記事を作成。下書き状態で保存される。"}, "descriptor":[
        {"href": "#title"},
        {"href": "#content"}
    ]},
    {"id": "doPublishBlogPost", "type": "idempotent", "rt": "#BlogPost", "doc": {"value": "記事を公開。publishedAtに現在時刻が設定される。"}, "descriptor": [
        {"href": "#id"}
    ]}
]}

例

• todomvc
• mini amazon
• LMS

FAQ

Q. どのような人が利用できますか

A. サイト制作に関わる全ての人（エンジニア、デザイナー、PO）が利用できます。

Q. どのような人がALPSを記述できますか

A. XMLやJSONを理解でき、簡単なHTMLのコーディングができる人ならALPSを記述できます。

Q. どのように使いますか

A. 情報を最小限必要な要素に整理してサイト設計を行い、WebやAPIサービスの設計に使います。設計はJSONやXMLなどのフォーマットとして表し、遷移図やボキャブラリリストなどのドキュメントを生成できます。また各制作者はその情報設計に基づいて情報の正確な言葉や意味、構造を知ることができます。

Q. 情報設計とはなんですか

A. IA（Information Architecture)に基づいて、情報のオントロジー（言葉の意味）、タクソノミー（情報の分類）、コレオグラフィー（リンク）の観点で情報の情報（メタ情報）を定義します。

Q. 設計の清書に使うものでしょうか

A. いいえ。サイト設計のごく初期段階から、情報を整理しどのようなサイトを形作っていくなどモデリングツールとして利用できます。

Q. ALPSを記述するのには何が必要ですか

A. JSONやXMLを編集するエディターが必要です。

Q. XMLやJSONを直接編集するのは大変じゃないですか

A. WebStormなどのスキーマをサポートするエディターを使うと補完やバリデーションが効いて快適に編集できます。

Q. XMLとJSONではどちらが良いですか

A. 機能に違いはありません。また複数のALPSファイルを利用する場合でも統一する必要がありません。実際に見比べてみてください。XML / JSON

Q. リンクのないAPIにも使えますか

A. 遷移図は表せませんが、ボキャブラリや情報の性質を表すドキュメントが生成できます。

Q. ALPSと同様の技術は他にありますか

A. 直接の競合技術はありません。近い技術にMicroformatがあります。

Q. OpenAPIなどのIDLと何が違いますか

A. ALPSはHTTPよりさらに上位のRESTの抽象を扱います。そのためOpenAPI実装のためのモデリングや設計言語として用いることもできます。

Q. 私に必要ですか

A. ユーザー体験の質の向上のために情報中心でサイトを設計したい、制作メンバー間の認識を統一するための信頼できる唯一の情報源（SSOT)が欲しい、設計を俯瞰し再利用したい、情報設計を規格化されたドキュメントとして残したい、などの動機があれば役に立つでしょう。

情報アーキテクチャとALPS

API設計やシステム構築において、情報アーキテクチャ（IA）の考え方をドメインモデリングに適用することで、ビジネス要件を体系的に整理できます。もともとUXやコンテンツ設計で培われてきたIAの「意味」「構造」「インタラクション」という要素は、ビジネスドメインの知識を構造化する際にも重要な役割を果たし、ALPSはこの考え方を標準化された方法で表せます。

情報アーキテクチャの適用

情報アーキテクチャの専門家であるDan Klynは情報アーキテクチャ（IA）を「意味（Ontology）」「構造（Taxonomy）」「インタラクションのルール（Choreography）」の相互作用として定義しました。¹ これらの概念はコンテンツ設計だけでなく、システム設計の基盤としても機能します。OpenAPIがAPIの技術的な詳細（エンドポイント、HTTPメソッド、リクエスト/レスポンス構造など）に焦点を当てるのに対し、ALPSはこれらのIA概念を用いてビジネスドメインの構造化を行います。

設計プロセスにおける位置づけ

ALPSは設計の初期段階からビジネス要件とシステム設計を橋渡しします。従来のエンドポイント中心の設計が決定済みの仕様を文書化する段階で使用されるのに対し、ALPSは要件定義のフェーズから活用できます。これにより、ビジネス要件の解釈の違いを早期に発見し、修正できます。また、技術チームとビジネスチーム間で共通言語が確立され、設計変更の影響範囲を把握しやすい仕組みが整えられます。

ALPSはAPIエンドポイントの設計を超え、ビジネス領域の知識を体系化し共有するための手段を提供します。信頼できる唯一の情報源（Single Source of Truth, SSOT）として、システムの構造と動作を一貫してモデル化します。ビジネス用語を中心とした記述により、複雑なビジネスルールを明確に表現し、ワークフローを可視化し情報の相互作用を俯瞰し直感的に理解できます。

技術変化への対応

ALPSはさまざまなAPIスタイルに適用できる柔軟性を持っています。技術の進化によってアーキテクチャスタイルが変化しても、ビジネスドメインの設計を維持できます。例えば、RESTful APIからGraphQLへの移行や、マイクロサービスアーキテクチャの導入、新しい通信プロトコルの採用など、技術的な変更が生じても、ALPSで定義したドメインモデルは継続して使用できます。これは、ALPSが実装の詳細ではなく、抽象化されたビジネスロジックに焦点を当てているためです。

知識基盤の構築

Taxonomyの実装では、ビジネスエンティティ間の関係性を定義し、階層構造による拡張性を確保します。これにより、組織全体で共通の語彙が確立され、コミュニケーションが効率化されます。Choreographyでは、ビジネスプロセスのフローとサービス間の連携ルールを定義し、システム全体の一貫性と信頼性を高めます。

IAの考え方をドメインモデリングに適用することで、技術的な実装とビジネス要件を自然に結びつけます。ALPSはこの橋渡しを実現するフレームワークとして機能し、組織の知識を体系的に構造化し、進化させる基盤となります。

この取り組みにより、技術の変化に影響されない持続可能な組織の知識基盤を構築する事ができます。

IANAリンクリレーション

このドキュメントはALPSプロファイルのrel属性で使用が推奨される、IANAリンクリレーションの一覧です。

状態遷移

順序のある遷移

意味的記述

文書構造

メタデータ

バージョン管理

関連情報

注意:

1. このリストはALPSプロファイルでよく使用される可能性のあるリレーションの抜粋です
2. 完全な一覧はIANAのRegistryを参照してください
3. カテゴリ分けは便宜上のものです
4. 実際の使用時は、アプリケーションの要件に応じて適切なリレーションを選択してください

イントロダクション

ALPS: アプリケーションレベルの意味と構造を明確にするフォーマット

Application-Level Profile Semantics (ALPS)は、アプリケーションレベルのセマンティクスを表現し、JSONやHTMLなどの汎用メディアにアプリケーション固有の情報を付加するフォーマットです。ALPSはデータの意味や構造、そして操作を明確化し、開発プロセスの効率化、システム間の互換性向上、APIの再利用性と発見性の促進を実現します。

電子商取引プラットフォームを例に考えてみましょう。クレジットカード、電子マネー、銀行振込など、複数の支払いサービスとの統合時、ALPSは支払いプロセスの各ステップにおけるデータと操作の意味を標準化します。これにより、新しい決済方法の追加や既存システムとの統合が容易になり、開発者は一貫した方法でAPIを実装できます。フロントエンドとバックエンドの開発者も共通の言語で効率的にコミュニケーションを取り、迅速に機能を追加・改善できます。

ASD: アプリケーション状態遷移の可視化

ASD（Application State Diagram）は、ALPSドキュメントからアプリケーションの状態遷移と行動を可視化するツールです。これにより、アプリケーションの全体構造を俯瞰し、状態間の遷移や可能なアクションを直感的に捉えることが可能になります。例えば、オンラインショッピングアプリにおいて、ユーザーが商品を検索してから購入に至るプロセスが明確に可視化され、開発者はユーザーが各段階で直面する選択と可能な操作を理解しやすくなります。これはユーザー体験の向上に繋がる設計上の意思決定を助けます。

ASDの利用により、プロダクトオーナー、バックエンドおよびフロントエンドの開発者、UI/UXデザイナーなど、プロジェクトに関わる全てのチームメンバーが同じ視点でアプリケーションを理解し、効果的に協力できるようになります。 これにより、専門分野の異なるメンバー間でスムーズなコミュニケーションが可能になり、複雑なプロジェクトでも新しいメンバーがスムーズに参加できるようになります。また、アプリケーションの流れやロジックを素早く把握して必要な調整ができるため、設計の早い段階で問題を見つけて解決でき、開発の効率と品質を高めます。

ASDを活用することで、プロジェクトの透明性が高まり、各チームメンバーが持つビジョンの齟齬を最小化できます。

RESTアプリケーション設計のための情報アーキテクチャ

情報アーキテクチャの観点からRESTアプリケーションを設計する際、ALPSとASDはお互いを補完する役割を果たします。ALPSはアプリケーションが扱うデータの意味や構造を標準化し、チーム全体で共通の語彙を使って情報を定義できるようにします。一方、ASDはアプリケーションの状態の変化を図で表現し、ユーザーの操作とアプリケーションの反応を視覚的に理解しやすくします。ALPSの仕様とASDによる可視化により、RESTアプリケーションの開発における情報設計が強化され、チーム間のコミュニケーションがスムーズになり、プロジェクト全体の一貫性と品質を高めます。

開発効率の向上、優れたユーザーエクスペリエンスの提供、そしてプロジェクトの持続可能性の確保には、多様な開発者間で共有される理解の基盤が不可欠です。ALPSとASDは、この基盤を構築しプロジェクトの長期的な成功を支えます。

イントロダクション

ALPS：アプリの情報を整理する方法

ALPS（アプリケーションレベルのプロファイルセマンティクス）は、アプリの情報や仕組みをきちんと説明するための方法です。インターネット上でよく使われる形式（例えばJSONやHTML）に、アプリ固有の情報を加えて、そのアプリがどのように動くのか、どんな情報を扱っているのかをはっきりさせます。これにより、アプリを作る過程がスムーズになり、異なるアプリやシステム同士が上手く連携できるようになります。

例えば、ネットショッピングのサイトを考えてみましょう。お客さんが商品を選んで買うまでの一連の手順（支払いを含む）について、ALPSを使うと、それぞれのステップで何が起こっているのかを明確に示すことができます。これにより、アプリを作る人たちは、お客さんがスムーズに買い物ができるように、必要な改善をしやすくなります。

ASD：アプリの動きを図で見る

ASD（アプリケーション状態遷移図）は、ALPSで説明されたアプリの情報をもとに、アプリの動きやユーザーができる操作を図で示します。これにより、アプリがどのように動いているのかを一目で理解できるようになります。ネットショッピングのサイトでいうと、商品を探してカートに入れる、支払う、という一連の流れが図で示されます。

ASDを使うと、アプリを作っているチームの中で、プログラマーやデザイナーなど、異なる役割の人たちが、アプリがどのように動くべきかについて、共通の理解を持つことができます。これは、アプリをより良くするための議論や、新しいアイデアを出し合う際にとても役立ちます。

RESTアプリケーションの設計

ALPSとASDは、特にWeb上で動くアプリ（RESTアプリケーションと呼ばれます）の設計に役立ちます。これらのツールを使うことで、アプリがどのような情報を扱い、どのように動くのかをはっきりと示すことができます。結果として、アプリの作成や改善がしやすくなり、使っている人にとっても、より使いやすいアプリになります。

多様なスキルを持つチームメンバーが同じ目標に向かって効率的に作業を進めるためには、お互いの作業内容を正確に理解し合うことが大切です。ALPSとASDは、そのための理解を深めるのに非常に役立つツールです。

リソース

• ALPS 公式
• RFC
• スケルトン
  • json
  • xml
• GitHub Action
• app-state-diagram

インストールと利用ガイド

ASD（app-state-diagram）は、アプリケーションの状態遷移図やボキャブラリリストを含んだALPSの包括的なドキュメントを作成するためのツールです。以下の方法で利用できます。

利用方法の選択

1. オンライン版

ローカルインストール不要で、すぐに利用できます：

• https://editor.app-state-diagram.com/

特徴：

• インストール不要
• ブラウザですぐに利用可能
• JSON/XML/HTMLファイルをドラッグ＆ドロップで読み込み可能
• スニペットや高度なコード補完機能
• ローカル環境へのインストールが不要な場合の推奨オプション
• 注意）現在複数ファイルを一度に編集することができません

2. Homebrew版

homebrewがインストールされている環境では最も簡単に利用できます。

インストール:

brew install alps-asd/asd/asd

3. Docker版

Dockerで実行するためのスクリプトをダウンロードして実行します。シェルスクリプトのダウンロードと実行を伴うために以下のセキュリティ確認手順に従ってください。

セキュリティ確認手順

1. スクリプトの内容確認（推奨）：

curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh | less

1. チェックサム検証：

curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh | sha256sum

期待値：

0f05034400b2e7fbfee6cddfa9dceb922e51d93fc6dcda62e42803fb8ef05f66

1. インストール実行：

sudo curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh -o /usr/local/bin/asd
sudo chmod +x /usr/local/bin/asd

前提条件

• Dockerがインストールされていること
• curlコマンドが利用可能であること

4. Macランチャーアプリケーション（GUI版）

コマンドライン操作が不要なMac用GUIアプリケーションです。

インストール手順：

1. ASD launcherをダウンロード
2. セキュリティ確認：
   • ダウンロードしたファイルの内容を確認してください
   • チェックサム（SHA-256）の検証：

     shasum -a 256 [ダウンロードしたzipファイル]
     

   • 公式リポジトリの期待値と比較してください: 659ecc3225b95a04f0e2ac4ebed544267ba78a0221db7ed84b6dfd7b08ce423b
3. ダウンロードしたスクリプトをスクリプトエディタで開く
   • セキュリティ警告が表示された場合は、スクリプトを右クリック（またはControlキーを押しながらクリック）して「開く」を選択
   • システム設定 > プライバシーとセキュリティで、表示された場合は「開く」をクリック
4. アプリケーションとして書き出す：
   • 保存先：「アプリケーション」
   • フォーマット：「アプリケーション」として保存

5. GitHub Actions版

CIでASD作成を行います。詳細はマーケットプレイスをご覧ください。

6. VSCode Plugin

VSCodeでライブプレビューを可能にするプラグインが利用可能です。 (experimental)

Visual Studio Marketplace - Application State Diagram

使用方法

デモ実行

# デモファイルのダウンロードと実行
curl -L https://alps-asd.github.io/app-state-diagram/blog/profile.json > alps.json
asd -w ./alps.json

コマンドラインオプション

asd [options] [alpsFile]

オプション：
    -w, --watch     ウォッチモード
    -m, --mode      描画モード
    --port          利用ポート（デフォルト3000）

モード設定

• 非公開リポジトリでの利用時はMarkdownモードを使用可能
• ただし、Markdownモードではダイアグラムのリンクは機能しません
• HTMLを公開できない場合の代替オプションとして利用

インストール確認

asd
usage: asd [options] alps_file
@see https://github.com/alps-asd/app-state-diagram#usage

選択の目安

• すぐに試したい、一時的な利用 → オンライン版
• Mac環境でのローカル利用 → Homebrew版
• クロスプラットフォームでの利用 → Docker版
• Macローカル環境でGUI → ランチャーアプリケーション
• CI/CD環境での利用 → GitHub Actions版

ALPSリファレンス

概要

Application-Level Profile Semantics (ALPS) は、アプリケーションのセマンティクス（意味論）を記述するためのドキュメントフォーマットです。このドキュメントではALPSの要素と属性について説明します。

文書構造

ALPSドキュメントは以下のような階層構造を持ちます：

1. ルート要素 (alps)
   • バージョン情報を含むドキュメントのルート要素
   • すべての定義はこの要素の中に含まれます
2. ディスクリプタ要素 (descriptor)
   • アプリケーションの機能や情報の意味を定義する中心的な要素
   • 以下の4つの型があります：
     • semantic: 語句・情報を表す（デフォルト）
     • safe: 読み取り操作（リソースの状態を変更しない）
     • idempotent: 同じ操作を複数回実行しても結果が変わらない操作（PUTによる完全な置き換えやDELETEによる消去など）
     • unsafe: 同じ操作を複数回実行すると異なる結果になる操作（POSTによる新規作成、数値の加算操作など）
   • 他のdescriptor要素を子要素として含むことができます
   • link要素を子要素として含むことができます
3. 補足要素
   • doc: 詳細な説明や補足情報
   • link: 関連ドキュメントへの参照
   • title: プロファイルの説明

記述形式

ALPSドキュメントは以下の2つの形式で記述できます：

XML形式

<?xml version="1.0" encoding="UTF-8"?>
<alps version="1.0">
    <title>ブログAPIプロファイル</title>
    <doc>ブログシステムのAPIプロファイル</doc>
    
    <descriptor id="title" title="タイトル" doc="記事のタイトル。最大100文字。"/>
    
    <descriptor id="blogPost">
        <doc>ブログ記事</doc>
        <descriptor href="#title"/>
        <link rel="related" href="http://example.org/related-docs/blog.html" />
    </descriptor>
</alps>

JSON形式

{
    "alps": {
        "version": "1.0",
        "title": "ブログAPIプロファイル",
        "doc": {"value": "ブログシステムのAPIプロファイル"},
        "descriptor": [
            {"id": "title", "title": "タイトル", "doc": {"value": "記事のタイトル。最大100文字。"}},
            {"id": "blogPost", "doc": {"value": "ブログ記事"}, 
             "descriptor": [
                {"href": "#title"}
             ],
             "link": [
                {"rel": "related", "href": "http://example.org/related-docs/blog.html"}
             ]
            }
        ]
    }
}

要素と属性の詳細

alps

ALPSドキュメントのルート要素です。

属性：

• version: 文書のバージョン（必須）

descriptor

アプリケーションの機能や情報の意味（セマンティクス）を定義します。 idまたはhrefのいずれかが必要でその他の属性はオプションです。

descriptorは以下の子要素を持つことができます：

• descriptor: 他のdescriptor要素を入れ子にして、階層構造を表現できます
• doc: 詳細な説明
• link: 関連リソースへのリンク
• ext: 拡張情報

descriptor属性一覧

※1: idまたはhrefのいずれかが必須

各属性の詳細：

• id: 一意の識別子（hrefと排他）
  • descriptorを一意に識別する文字列
  • 同一文書内で重複不可
  • URL安全な文字のみ使用可能（RFC1738に準拠）
• href: 参照先（idと排他）
  • 他のdescriptorを参照するための識別子
  • ”#”で始まるフラグメント識別子（例：#user）
  • 外部ファイルの場合はパスを含む（例：profile.xml#user）
  • 解決可能なURLとフラグメント識別子(#)必須
• type: ディスクリプターの型
  • semantic: 語句・情報を表す（デフォルト）
  • safe: 読み取り操作（リソースの状態を変更しない）
  • idempotent: 同じ操作を複数回実行しても結果が変わらない操作（PUTによる完全な置き換えやDELETEによる消去など）
  • unsafe: 同じ操作を複数回実行すると異なる結果になる操作（POSTによる新規作成、数値の加算操作など）
• rt: 遷移先（Return Type）
  • 状態遷移後の移動先リソース
  • ”#”で始まるフラグメント識別子で指定
  • type属性がsafe/idempotent/unsafeの場合に使用
• rel: リレーション
  • descriptorの関係性を示す
  • IANAで定義されたLink Relationsを使用（item, collection, self, next, prev など）
  • カスタムの場合はURIで指定
• title: 表示名
  • 人間が読むための表示名
  • UIやドキュメントでの表示用
• tag: 分類タグ
  • descriptorのグルーピングに使用
  • 複数指定する場合はスペース区切り
  • カテゴリ分類やフィルタリング用
• name: 表示用名前
  • 実際の表現で使用される名前
  • idが一意である必要がある場合に、共通の名前を指定するために使用
  • 同じnameを持つ複数のdescriptorが存在可能
• def: 定義元URI
  • descriptorの定義元となる外部リソースを示すURI
  • Schema.orgなどの標準的な定義への参照に使用

doc

要素の詳細な説明を提供します。

doc属性一覧

format属性のサポートレベル:

• text: サポート必須（MUST）
• html: サポート推奨（SHOULD）
• asciidoc: サポート任意（MAY）
• markdown: サポート任意（MAY）、[RFC7763]に準拠

contentTypeとformatの優先順位:

• contentTypeが存在する場合はそれを使用
• contentTypeとformatが両方ある場合はformatを無視
• どちらもない場合はtext/plainと見なす

link

関連ドキュメントへの参照を定義します。linkはalpsまたはdescriptor要素の子要素として使用できます。

link属性一覧

リレーション値:

• self: 自身へのリンク
• profile: プロファイルドキュメント
• help: ヘルプドキュメント
• related: 関連ドキュメント
• その他のIANAリンクリレーション

ext

拡張情報を提供します。標準仕様にない追加情報を含める場合に使用します。

ext属性一覧

バリデーション

1. descriptorにはidまたはhrefのいずれかが必要です
2. href参照先は解決可能なURLでなければならず、フラグメント識別子が必須です
3. rt遷移先は文書内に実在する必要があります
4. type属性は定義された4値（semantic、safe、idempotent、unsafe）のいずれかである必要があります
5. 操作系descriptorには以下のプレフィックスの使用を推奨します：
   • safe: go（例：goBlog）
   • unsafe: do（例：doCreateBlog）
   • idempotent: do（例：doUpdateBlog）

階層構造の例

以下は、入れ子になったdescriptor要素を使用した簡潔な階層構造の例です：

XML形式

<alps version="1.0">
  <descriptor id="user" type="semantic">
    <doc>ユーザー情報</doc>
    <descriptor id="name" type="semantic" />
    <descriptor id="email" type="semantic" />
    <link rel="help" href="http://example.org/help/user.html" />
  </descriptor>
</alps>

JSON形式

{
  "alps": {
    "version": "1.0",
    "descriptor": [
      {
        "id": "user",
        "type": "semantic",
        "doc": {"value": "ユーザー情報"},
        "descriptor": [
          {"id": "name", "type": "semantic"},
          {"id": "email", "type": "semantic"}
        ],
        "link": [
          {"rel": "help", "href": "http://example.org/help/user.html"}
        ]
      }
    ]
  }
}

Schema.org 用語集

プロパティ