ALPS Reference


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.

<descriptor ... >
<descriptor ... >

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

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

  <title>ALPS Blog</title>.
  <doc>An ALPS profile example for ASD</doc>.
  <link href="" rel="issue"/>
  <descriptor ... >
  <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.

element meaning example
descriptor semantic identifier

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

elements meanings examples
doc descriptive text Date the article was created
link link


doc to explain the meaning in text

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

A link that links to a description of another resource.

<descriptor id="dateCreated">
    <link rel="author" href="">

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.

attribute meaning example
id identifier createdDate
type type semantic | safe | unsafe | idempotent
href reference #id
rt transition destination #User
rel relationship edit
title title creation time
tag tag ontology


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.


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

type semantic
semantic meaning
safe safe and powerfull transition
idempotent unsafe and powerfull transitions
unsafe unsafe and powerless transitions

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


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

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


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


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


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.


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

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

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


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


Specifies the transition destination ID.

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


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.


A one-line comment describing the content.

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


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