ALPS, ASD でセマンティクス重視のドキュメントを作成する

ソフトウェア設計をする際に以下のような課題が発生する場合があります。

• ドキュメント化のコストと、管理コストの増加
• システムが複雑化するにつれて、コードの理解が難しくなる
• 一貫性のない命名規則

これらの課題を解決するために、今回は ALPS という情報設計手法を学習しました。

ALPS とは

ALPS QuickStart によると、以下のように説明されています。

Application-Level Profile Semantics (ALPS)は、アプリケーションレベルのセマンティクス（語句の意味や構造）を表現するフォーマットです。JSON、HTMLなど汎用メディアにアプリケーション固有のセマンティックスを加え、情報の説明や操作の理解に役立てます。

特定のメディアタイプに囚われず、アプリケーションで利用する言葉の意味や構造に焦点を当てている、ドキュメントを作成するためのフレームワークと言えそうです。

ASD とは

ASD は ALPS を可視化するためのツールです。
こちらの説明も ALPS QuickStart から引用させていただきます。

ASD(Application State Diagram)とはALPSドキュメントから生成されるアプリケーション状態遷移図、およびその遷移図を含むドキュメンテーション生成ツールの名前です。RESTアプリケーションを純粋な情報設計の視点で俯瞰する事ができ、状態の詳細ドキュメントが遷移図からリンクされます。

EC サイトの例

ASD の公式サイトに Amazon のような EC サイトをALPS, ASD でドキュメントにした例が載っています。

このようにリソースの URL は登場せず、意味や操作を相互リンクで辿ることが可能なため、直感的にドキュメントを理解しやすいのが特徴です。

オンライン予約システムを想定して作ってみた

今回は、オンライン予約システムを想定して ALPS ドキュメントを作成してみました。

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

    <!-- オントロジー -->
    <descriptor id="scheduleId" title="スケジュールID">
        <doc format="text">スケジュールの一意の識別子</doc>
    </descriptor>
    <descriptor id="startAt" title="開始日時"></descriptor>
    <descriptor id="endAt" title="終了日時"></descriptor>
    <descriptor id="capacity" title="定員"></descriptor>
    <descriptor id="reservationStatus" title="予約ステータス">
        <doc format="text">予約の現在の状態 (確定済み、キャンセル済み)</doc>
    </descriptor>
    <descriptor id="reservedAt" title="予約日時"></descriptor>
    <descriptor id="reservationMemo" title="予約備考">
        <doc format="text">予約時にユーザーが入力する備考</doc>
    </descriptor>
    <descriptor id="userName" title="ユーザー名"></descriptor>
    <descriptor id="userEmail" title="ユーザーのメールアドレス"></descriptor>

    <!-- タクソノミー -->
    <descriptor id="Schedule" title="スケジュール情報">
        <descriptor href="#scheduleId"></descriptor>
        <descriptor href="#startAt"></descriptor>
        <descriptor href="#endAt"></descriptor>
        <descriptor href="#capacity"></descriptor>
    </descriptor>
    <descriptor id="Reservation" title="予約情報">
        <descriptor href="#scheduleId"></descriptor>
        <descriptor href="#reservationStatus"></descriptor>
        <descriptor href="#reservedAt"></descriptor>
        <descriptor href="#reservationMemo"></descriptor>
        <descriptor href="#userName"></descriptor>
        <descriptor href="#userEmail"></descriptor>
    </descriptor>
    <descriptor id="ScheduleList" title="予約日時選択">
        <descriptor href="#doSelectSchedule"/>
    </descriptor>
    <descriptor id="ReservationUserInfo" title="ユーザー情報入力">
        <descriptor href="#doSubmitUserInfo"/>
    </descriptor>
    <descriptor id="ReservationConfirm" title="予約内容確認">
        <descriptor href="#doReserve"/>
    </descriptor>
    <descriptor id="ReservationCompleted" title="予約完了">
    </descriptor>

    <!-- コレオグラフィー -->
    <descriptor id="doSelectSchedule" type="unsafe" rt="#ReservationUserInfo" title="予約日時を選択">
        <descriptor href="#scheduleId"/>
    </descriptor>
    <descriptor id="doSubmitUserInfo" type="unsafe" rt="#ReservationConfirm" title="ユーザー情報の入力を確定する">
        <descriptor href="#userName"/>
        <descriptor href="#userEmail"/>
        <descriptor href="#reservationMemo"/>
    </descriptor>
    <descriptor id="doReserve" type="unsafe" rt="#ReservationCompleted" title="予約を確定する">
    </descriptor>
</alps>

ALPS の書き方

ALPS ドキュメントは、XML または JSON 形式で記述できます。
今回はコメントアウトを利用したかったので XML で記述しました。
どちらの形式を使っても機能的な違いはないため、チームの好みや普段使っているツールに合わせて選ぶと良いそうです。

記述は descriptor タグを中心に行います。
そこに属性を追加したり、ネストすることで、意味や操作を表現することができます。

次に ALPS を構成する 3つの要素について説明します。
以下の要素を定義した ALPS を元に、ASD が相互リンクされたドキュメントを自動で生成してくれます。

1. オントロジー

アプリケーションで使用する言葉の意味を定義します。
id は 要素の一意な識別子、title は見出しのような簡潔な表現、doc はより長いテキストでの説明です。

<descriptor id="reservationStatus" title="予約ステータス">
    <doc format="text">予約の現在の状態 (確定済み、キャンセル済み)</doc>
</descriptor>

2. タクソノミー

情報の構造を定義します。
定義した用語(オントロジー)を組み合わせて、より大きな概念を表現します。

<descriptor id="Reservation" title="予約情報">
    <descriptor href="#scheduleId"></descriptor>
    <descriptor href="#reservationStatus"></descriptor>
    <descriptor href="#reservedAt"></descriptor>
    <descriptor href="#reservationMemo"></descriptor>
    <descriptor href="#userName"></descriptor>
    <descriptor href="#userEmail"></descriptor>
</descriptor>

3. コレオグラフィー

操作の流れを定義します。
type は操作の種類、rt は遷移先の指定です。
操作に必要な情報は descriptor に含めます。

<descriptor id="doSelectSchedule" type="unsafe" rt="#ReservationUserInfo" title="予約日時を選択">
    <descriptor href="#scheduleId"/>
</descriptor>

ALPSでは、操作は以下の種類に分かれます。

操作	メソッド	HTTP メソッド説明
safe	GET	アプリケーションの状態のみを変更
unsafe	POST	新しいリソース状態を作成
idempotent	PUT/DELETE	リソース状態を更新/削除

また命名規則のプレフィックスは以下のようになっています。

• safe 遷移では go を使用します
• unsafe 遷移では doCreate を使用します
• idempotent 遷移では doUpdate/doDelete を使用します

セマンティック

ALPS は言葉の意味(セマンティクス)に重きを置いています。 アプリケーションの語句の辞書になることが重要な役割の1つです。
そのため ASD では推奨セマンティック用語が提供されており、それに従って記述することで定義に一貫性を持たせることを推奨しています。

例:

用語	説明
givenName	名
familyName	姓
termsOfService	利用規約
keywords	キーワード
abstract	要約

できるだけSchema.orgの用語を基盤としつつ、必要な拡張を行うことを推奨します。

と記されている通り、個人的にはこれらの用語は命名する際の参考にしつつ、プロジェクトに合わせて開発メンバーやユーザーが理解しやすいドメイン用語を使うことが重要だと思います。
ドメイン用語を利用したとしても、その用語を元にタクソノミー(情報の構造)やコレオグラフィー(操作の流れ)を定義していくので、一貫性のあるドキュメントを作成することが可能です。

オンラインエディター

ASD 公式サイトには、入力した ALPS をリアルタイムでプレビューできるオンラインエディターが用意されています。
ローカルにインストールすることもできますが、まず軽く試してみたい場合はこちらを利用すると良いでしょう。

まとめ

見慣れない言葉が多く最初は戸惑いましたが、慣れてくると言葉の組み合わせで情報の構造を表現することができる ALPS と ASD は非常に役立つツールだと感じました。
最初に記した課題の解決のために以下のようなメリットが挙げられます。

• JSON や XML でシンプルに記述でき、Git などのバージョン管理ツールで管理できる
• 意味や操作を相互にリンクで辿ることができ、ドキュメントを理解しやすくなる
• セマンティクスに重きを置いているため、一貫性のある命名が可能

目の前のタスク単位で利用するというよりは、アプリケーション全体の設計で利用するツールだと感じました。
私自身のドキュメント作成ツールに対する知見は少ないのですが、今後画面遷移や API 設計のドキュメントを作成する際には候補に挙げたいです。
API のドキュメント作成に何を使うか迷っている方や、ドキュメントの一貫性を保ちたい方は、ぜひ他のツールと比較検討してみてください。
ASD 公式サイトにチュートリアルもあるので、まずは手を動かしてみるのがおすすめです。

参考

• ALPS チュートリアル
• ASD 公式サイト