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>

ALPS meta-information

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>

Semantic descriptors

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>

element

descriptor element

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	<descriptor id="dateCreated" />

Elements for description

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

elements	meanings	examples
doc	descriptive text	<doc format="markdown">Date the article was created</doc>
link	link	<link href="https://example.com/issues" rel="issue"/>

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

For rel, choose IANA's [Link Relation] rel from IANA's registered rel, and link to the URL with href. The URL is linked by href.

descriptor

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

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

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.

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.

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.

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

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.