ALPS Reference

alps

The set of semantic descriptors described below is the ALPS document, written in XML or JSON. Enclose the whole thing in tags. It can be written in XML or JSON.

<alps>.
<descriptor ... >
<descriptor ... >
</alps>

Semantic descriptors define special words used by the application.

<descriptor id="dateCreated" title="date created"/>
<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting" title="View blog post">
    <descriptor href="#id"/>
</descriptor>

title, doc, link

You can add meta-information to ALPS documents, such as title, doc, link, and so on.

<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 is an element for semantic descriptors (semantic identifiers), describing words that are special to the application, such as API item names or link names.

A doc or link element can be included to describe the descriptor.

doc

doc to explain the meaning in text

<descriptor id="dateCreated">
    <doc format="markdown">Date of creation of the article expressed in ISO8601 format</doc>.
</descriptor>
The ``.
The doc can be formatted (text|markdown|html|asciidoc) with format. If not specified, text is used.

link

A link that links to a description of another resource.

<descriptor id="dateCreated">
    <link rel="author" href="https://github.com/koriym">
</descriptor>

The rel is selected from IANA’s Link Relation rel from IANA’s registered rel, and the href links to the URL. The URL is linked by href.

Descriptor attributes

A descriptor has attributes such as ID, type, and tag.

id

ALPS assigns a unique ID to all information and all transitions (links); there are no specification constraints on the ID phrase, but there are best practices for adding go for safe transitions and do for unsafe transitions.

type

The descriptor has a type attribute. If unspecified, it is semantic.

There is one type for semantics and three types for transitions.

semantic

List the words and phrases used in your application and create a vocabulary.

<descriptor id="dateCreated" type="semantic"/>

safe

This is a transition for reading, where the state of the resource does not change.

Example: Get resource state by URL

<descriptor id="goBlog" type="safe" rt="#Blog" />

idempotent

This is a transition where the state of the resource changes by power.

Example: Creating a resource with a URL, changing or deleting the target resource.

<descriptor id="doDeleteMenu" type="idempotent" rt="#Menu">

unsafe

This is a transition where the state change of the resource is not powerless.

Example: Creating a resource without a URL or adding a target resource.

<descriptor id="doAppendRecord" type="unsafe" rt="#Record">

There are four types in total.

What is idempotent?

It means that the result of an operation is the same whether it is performed once or multiple times. For example, adding a resource is not idempotent, but changing or deleting a resource is idempotent.

Structure

A descriptor can be included to represent the nested structure of information or the information needed for a transition.

Example: A blog post contains body and date information.

<descriptor id="BlogPosting" title="Blog Posting" >
    <descriptor href="#dateCreated"/>
    <descriptor href="#articleBody"/>
</descriptor>
```.

e.g.) To refer to a blog post, the post ID is required

```xml
<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting">
    <descriptor href="#id"/>
</descriptor>

href

In order to reuse a single descriptor, you can link to it with a href. There are two types of links: inline links, which link from the same document, and outbound links, which link to a descriptor in another file.

<! -- inline link -->
<descriptor href="#articleBody">

<! -- outbound links --> <!
<descriptor href="Blog.xml#articleBody">

rt

Specifies the transition destination ID.

<descriptor id="goBlog" type="safe" rt="#Blog">

rel

Specifies a relation for transitions of type safe, idempotent, or unsafe.

<descriptor id="editBlogPosting" type="idempotent" rel="edit" rt="#Blog">

Rel is chosen from IANA’s Link Relation.

title

A one-line comment describing the content.

<descriptor id="editBlogPosting" type="idempotent" rt="#Blog" title="Edit Posting" />

tag

<descriptor id="editBlogPosting" type="idempotent" rt="#Blog" tag="choreography" />

ASD allows you to specify whether to draw or not, and the color of each tag.