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	安全でなく冪等でない遷移

意味を表す１つのタイプと、遷移を表す３つのタイプがあります。

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">

以上、計４つのタイプがあります。

冪等とは

ある操作を1回行っても複数回行っても結果が同じであることです。たとえばリソースの追加は冪等性がありませんが、リソースの変更や消去には冪等性があります。

href

１つのdescriptorを再利用するためにhrefでリンクをする事ができます。リンクには同じドキュメントからリンクするインラインリンクと、他のファイルのdescriptorにリンクするアウトバウンドリンクの２つがあります。

<!-- インラインリンク -->
<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はタグ単位で描画の有無や色を指定できます。