ALPSリファレンス
alps
後述のセマンティックディスクリプタの集合がALPSドキュメントです。XMLまたはJSONで記述し<alps>タグで全体を囲みます。
<alps>
<descriptor ...>
<descriptor ...>
</alps>
セマンティックディスクリプタはアプリケーションで使われる特別な語句を定義します。
<descriptor id="dateCreated" title="作成日付"/>
<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting" title="ブログ記事を見る">
<descriptor href="#id"/>
</descriptor>
title, doc, link
ALPSドキュンメントにはtitle、doc、linkなどのメタ情報を付加できます。
<alps>
<title>ALPS Blog</title>
<doc>An ALPS profile example for ASD</doc>
<link href="https://github.com/koriym/app-state-diagram/issues" rel="issue"/>
<descriptor ...>
<descriptor ...>
</alps>
descriptor
descriptorはセマンティックディスクリプタ(意味的識別子)のための要素です。APIの項目名やリンクの名前など、アプリケーションのとって特別な語句を説明します。
要素 | 意味 | 例 |
---|---|---|
descriptor | 意味的識別子 |
descriptorの説明のために、docやlink要素を含むことができます。
要素 | 意味 | 例 |
---|---|---|
doc | 説明テキスト | |
link | リンク |
また、情報の入れ子構造や、遷移に必要な情報を表すためにdescriptorを含むことができます。
例) ブログ記事は本文や日付の情報を含んでいる
<descriptor id="BlogPosting" title="ブログ記事" >
<descriptor href="#dateCreated"/>
<descriptor href="#articleBody"/>
</descriptor>
例) ブログ記事を参照するには記事IDが必要
<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting">
<descriptor href="#id"/>
</descriptor>
doc
文章で意味を説明するdoc
<descriptor id="dateCreated">
<doc format="markdown">ISO8601フォーマットで表された記事の作成日付</doc>
</descriptor>
docはformatでフォーマット(text|markdown|html|asciidoc)を指定できます。無指定の時はtextです。
link
他のリソースの説明をリンクするlink
<descriptor id="dateCreated">
<link rel="author" href="https://github.com/koriym">
</descriptor>
relはIANAの[Link Relation]relをIANAの登録されたrelから選び、hrefでURLにリンクします。
Descriptor要素
descriptorにIDや、タイプ、タグと行った属性を付与できます。
属性 | 意味 | 例 |
---|---|---|
id | 識別子 | createdDate |
type | 型 | semantic | safe | unsafe | idempotent |
href | 参照 | #id |
rt | 遷移先 | #User |
rel | 関係 | edit |
title | タイトル | 作成時刻 |
tag | タグ | ontology |
id
ALPSでは全ての情報、全ての遷移(リンク)に対してユニークなIDを割り当てます。ID語句に仕様制約はありませんが、安全な遷移の時はgo
、安全ではない時の遷移はdo
を付けるベストプラクティスがあります。
type
descriptorはtype属性を持ちます。無指定の場合はsemanticです。
タイプ | 意味 |
---|---|
semantic | 意味 |
safe | 安全で冪等な遷移 |
idempotent | 安全でなく冪等な遷移 |
unsafe | 安全でなく冪等でない遷移 |
意味を表す1つのタイプと、遷移を表す3つのタイプがあります。
semantic
アプリケーションで使う語句をリストアップし、ボキャブラリを作成します。
<descriptor id="dateCreated" type="semantic"/>
safe
リソースの状態が変化しない、読み取りのための遷移です。
例) URLを指定してリソース状態を取得
<descriptor id="goBlog" type="safe" rt="#Blog" />
idempotent
リソースの状態が冪等で変化する遷移です。
例) URLを指定したリソース作成、対象リソースの変更や削除
<descriptor id="doDeleteMenu" type="idempotent" rt="#Menu">
unsafe
リソースの状態変化が冪等ではない遷移です。
例) URLを指定しないリソース作成や対象リソースの追記
<descriptor id="doAppendRecord" type="unsafe" rt="#Record">
以上、計4つのタイプがあります。
冪等とは
ある操作を1回行っても複数回行っても結果が同じであることです。たとえばリソースの追加は冪等性がありませんが、リソースの変更や消去には冪等性があります。
href
1つのdescriptorを再利用するためにhrefでリンクをする事ができます。リンクには同じドキュメントからリンクするインラインリンクと、他のファイルのdescriptorにリンクするアウトバウンドリンクの2つがあります。
<!-- インラインリンク -->
<descriptor href="#articleBody">
<!-- アウトバウンドリンク -->
<descriptor href="Blog.xml#articleBody">
rt
遷移先IDを指定します。
<descriptor id="goBlog" type="safe" rt="#Blog">
rel
typeがsafe
, idempotent
, unsafe
の遷移の時に関係性を指定します。
<descriptor id="editBlogPosting" type="idempotent" rel="edit" rt="#Blog">
relはIANAのLink Relationから選びます。
title
内容を一行で表すコメントです。
<descriptor id="editBlogPosting" type="idempotent" rt="#Blog" title="記事の編集" />
tag
<descriptor id="editBlogPosting" type="idempotent" rt="#Blog" tag="choreography" />
タグでグループを作ります。ASDはタグ単位で描画の有無や色を指定できます。