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

Read more

ALPS チュートリアル

始める 最初にASDをインストールしてください。 https://github.com/koriym/app-state-diagram#run-with-docker 次にスケルトンファイルprofile.xmlを作成します。 <?xml version="1.0" encoding="UTF-8"?> <alps xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

11/22/2021
ALPS Tutorial

Getting started Install ASD utility. https://github.com/koriym/app-state-diagram#run-with-docker Then create a skeleton file profile.xml. <?xml version="1.0" encoding="UTF-8"? > <alps xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

11/22/2021
ALPS Reference

ALPS documentation The set of semantic descriptors described below is the ALPS document, written in XML or JSON. It can be written in XML or JSON. <alps>. <descriptor ... > <descriptor ... > </alps>

10/14/2021
ALPS QuickStart

ALPSとは Application-Level Profile Semantics (ALPS)は、アプリケーションレベルのセマンティクス（語句の意味や構造）を表現するフォーマットです。JSON、HTMLなど汎用メディアにアプリケーション固有のセマンティックスを加え、情報の説明や操作の理解に役立てます。 ASDとは ASD(Application State Diagram)とはALPSドキュメントから生成されるアプリケーション状態遷移図、およびその遷移図を含むドキュメンテーション生成ツールの名前です。RESTアプリケーションを純粋な情報設計の視点で俯瞰する事ができ、状態の詳細ドキュメントが遷移図からリンクされます。 用途 RESTアプリケーション(APIやWebサイト）からUI/UXを排した純粋な情報設計の視点で設計を書式化する事ができます。整理された情報でサイト設計を行う事や、開発やメンテナンスの時に情報定義のSSOTとして用いる事ができます。 ALPSドキュメントは相互にリンク可能なハイパーメディアです。複数の部分設計をリンクする事で全体の設計を構成する等、設計の再利用が可能です。

10/14/2021
Read more from Akihito Koriyama
Published on HackMD