This page collects all BEAR.Sunday manuals in one place.

Advanced Implementation Guide

Overview

This document describes more advanced implementation topics for Application-Level Profile Semantics (ALPS). For a description of basic elements and attributes, please refer to the ALPS Reference.

Descriptors and Link Relation Types

When including state transitions in representations, valid values for link relation types can be any of the following:

1. Standard Link Relation Types
   • Short strings registered in registries like IANA or Microformats.org
   • Example: rel="edit", rel="next", rel="collection"
   • See IANA Link Relations
2. Extended Link Relation Types ([RFC8288])
   • Fully qualified URI for a document describing the relation type
   • Contains a URI fragment identifier for an ALPS descriptor
   • Example: rel="http://alps.io/profiles/item#purchased-by"
   • Example: rel="http://alps.io/profiles/blog#comment"
3. ALPS Descriptor ID
   • id attribute value of a state transition descriptor in an ALPS document
   • Usable only if the representation includes an ALPS profile
   • Example: rel="purchased-by"
   • Example: rel="create-comment"

Resolving Link Relation Conflicts

1. Conflicts with Standard Relations
   • If a state transition descriptor has the same meaning as a standard link relation, do not change its meaning
   • Example: When creating a descriptor named edit, it must match the meaning of the edit relation registered with IANA
2. Resolving ID Conflicts
   • When conflicts occur between multiple descriptors with the same ID:
     • Define a unique ID
     • Use the name attribute to retain the original name if necessary
   • Example:

     <descriptor id="user-edit" name="edit" type="safe">
       <doc>Edit user information</doc>
     </descriptor>
     

Integration with Existing Media Types

ALPS can be used in combination with various existing media types. Below, we explain how to integrate with major media types.

HTML

In HTML, ALPS descriptors are primarily represented using the class attribute:

<div class="blog-post">
  <h1 class="title">Article Title</h1>
  <div class="content">Content...</div>
  <form class="add-comment" method="post">
    <input name="comment-text" class="comment-text">
    <button type="submit">Add Comment</button>
  </form>
</div>

Corresponding ALPS profile:

<alps version="1.0">
  <descriptor id="blog-post" type="semantic">
    <descriptor id="title" type="semantic"/>
    <descriptor id="content" type="semantic"/>
    <descriptor id="add-comment" type="unsafe">
      <descriptor id="comment-text" type="semantic"/>
    </descriptor>
  </descriptor>
</alps>

HAL (Hypertext Application Language)

In HAL, state transitions are expressed as link relations and semantic descriptors as properties:

{
  "_links": {
    "self": {"href": "/posts/1"},
    "add-comment": {"href": "/posts/1/comments"}
  },
  "title": "Article Title",
  "content": "Content...",
  "_embedded": {
    "comments": [
      {
        "_links": {
          "self": {"href": "/comments/1"}
        },
        "text": "Comment content..."
      }
    ]
  }
}

Collection+JSON

In Collection+JSON, descriptors are expressed as queries and data elements:

{
  "collection": {
    "version": "1.0",
    "href": "/posts/1",
    "items": [
      {
        "data": [
          {"name": "title", "value": "Article Title"},
          {"name": "content", "value": "Content..."}
        ]
      }
    ],
    "template": {
      "data": [
        {"name": "comment-text", "value": "", "prompt": "Enter a comment"}
      ]
    }
  }
}

Referencing ALPS Documents

This section describes how to reference ALPS profiles when applying them.

Referencing by Link

1. Referencing in HTML

   <link rel="profile" href="http://example.com/alps/blog" />
   

2. Referencing in HTTP Link Header

   Link: <http://example.com/alps/blog>; rel="profile"
   

3. Referencing in Media Type Parameter

   Content-Type: application/json; profile="http://example.com/alps/blog"
   

Applying Multiple Profiles

Multiple ALPS profiles can be applied to a single representation:

Link: <http://example.com/alps/blog>; rel="profile",
      <http://example.com/alps/comments>; rel="profile"

Profile Priority

Priority when multiple profiles conflict:

1. Profiles specified in the profile parameter of the media type
2. Profiles specified in the HTTP Link header
3. Profiles specified in the representation itself (priority given to those specified first)

Error Handling and Validation

This section describes common error cases and how to handle them during implementation.

Common Errors

1. Invalid Descriptor Reference
   • URLs or fragment identifiers that cannot be resolved
   • References to non-existent descriptors
2. Link Relation Conflict
   • Conflicts in meaning with standard relations
   • Conflicts between relation definitions in multiple profiles
3. Media Type Constraints
   • Presence of elements that cannot be expressed in a particular media type
   • Lack of support for link expressions

Best Practices

State

Application state semantic descriptors are represented in UpperCamelCase starting with a capital letter.

"descriptor": [
  {"id": "BlogPosting", "type": "semantic", "def": "https://schema.org/BlogPosting", "descriptor": [
    {"href": "#id"},
    {"href": "#articleBody"},
    {"href": "#dateCreated"},
    {"href": "#blog"}
  ]}
]

Safe State Transitions

Semantic descriptors with type safe add the prefix go to the destination descriptor. (RFC8288)

[
  {"id": "goHome", "type": "safe", "rt": "#Home"},
  {"id": "goFirst", "type": "safe", "rt": "#TodoList"},
  {"id": "goPrevious", "type": "safe", "rt": "#TodoList"}
]

Semantic descriptors that are not safe should use the prefix do.

[
  {"id": "doEditUser", "type": "idempotent", "rt": "#UserList"},
  {"id": "doDeleteUser", "type": "idempotent", "rt": "#UserList"}
]

The rt (transition destination) ID is formed by adding the destination descriptor ID to the prefix go or do.

[
  {"id": "goBlogPosting", "type": "safe", "rt": "#BlogPosting"},
  {"id": "doEditBlogPosting", "type": "idempotent", "rt": "#Blog"}
]

Elements

Semantic descriptors that are not defined as application states, i.e., elements, are written in lowerCamelCase starting with a lowercase letter.

[
    {"id": "articleBody"},
    {"id": "dateCreated"}
]

ALPS File Structure

The semantic descriptors in ALPS files are divided into three blocks in the following order:

1. Semantic descriptor groups with meaning definitions using def and doc (ontology)
2. Semantic descriptor groups with inclusion relationships (taxonomy)
3. State transition semantic descriptor groups (choreography)

{"descriptor" : [
    {"id" : "name", "type" : "semantic", "def": "http://schema.org/identifier"},
    {"id" : "age", "type" : "semantic", "def": "http://schema.org/title"},

    {"id" : "Person", "type": "semantic", "descriptor":[
      {"href": "#name"},
      {"href": "#age"}
    ]}
    
    {"id": "goPerson", "type": "safe", "rt": "#Person"},
]

Hierarchical Structure Outside ALPS

In ALPS, hierarchical meanings can be expressed by position.

{"descriptor": [
    {"id": "name", "def": "https://schema.org/name"},
    {"id": "Product", "descriptor":[
      {"href": "#name"}
    ]}
    {"id": "Person", "descriptor":[
      {"href": "#name"}
    ]}
]

• In the example above, name is shared between Product/name and Person/name.
• When expressing such terms in formats with only flat hierarchies, it’s basic practice to follow the conventions of each format.
• In HTML, they are expressed in lower camel case.

<form>
    <input name="productName" type="text">
    <input name="personName" type="text">
</form>

Adding Schema References

When creating ALPS profiles, it is recommended to add schema references.

{
  "$schema": "https://alps-io.github.io/schemas/alps.json",
  "alps" : {
  }
}

<alps 
  version="1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
</alps>  

Implementation Examples

Semantic Elements

Basic element definitions:

<descriptor id="title" title="Title" doc="Article title. Maximum 100 characters."/>
<descriptor id="content" title="Content" doc="Article body. Supports Markdown format."/>
<descriptor id="publishedAt" title="Publication Date" doc="Article publication date and time. ISO 8601 format."/>

{"descriptor": [
    {"id": "title", "title": "Title", "doc": {"value": "Article title. Maximum 100 characters."}},
    {"id": "content", "title": "Content", "doc": {"value": "Article body. Supports Markdown format."}},
    {"id": "publishedAt", "title": "Publication Date", "doc": {"value": "Article publication date and time. ISO 8601 format."}}
]}

Reusing basic elements:

<descriptor id="blogPost">
    <doc>User-created article. After publication, visible to all users.</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
    <descriptor href="#publishedAt"/>
</descriptor>

<descriptor id="pagePost">
    <doc>Static page. Permanent content such as site basic information.</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
</descriptor>

{"descriptor": [
    {"id": "blogPost", "doc": {"value": "User-created article. After publication, visible to all users."}, "descriptor": [
        {"href": "#title"},
        {"href": "#content"},
        {"href": "#publishedAt"}         
    ]},
    {"id": "pagePost", "doc": {"value": "Static page. Permanent content such as site basic information."}, "descriptor": [
        {"href": "#title"},
        {"href": "#content"}
    ]}
]}

Operation Definitions

<descriptor id="goBlog" type="safe" rt="#Blog" doc="Display blog homepage. Shows latest 10 articles."/>

<descriptor id="doCreateBlogPost" type="unsafe" rt="#BlogPost">
    <doc>Create new article. Saved in draft state.</doc>
    <descriptor href="#title"/>
    <descriptor href="#content"/>
</descriptor>

<descriptor id="doPublishBlogPost" type="idempotent" rt="#BlogPost">
    <doc>Publish article. Current time is set to publishedAt.</doc>
    <descriptor href="#id"/>
</descriptor>

{"descriptor": [
    {"id": "goBlog", "type": "safe", "rt": "#Blog", "doc": {"value": "Display blog homepage. Shows latest 10 articles."}},
    {"id": "doCreateBlogPost", "type": "unsafe", "rt": "#BlogPost", "doc": {"value": "Create new article. Saved in draft state."}, "descriptor": [
        {"href": "#title"},
        {"href": "#content"}
    ]},
    {"id": "doPublishBlogPost", "type": "idempotent", "rt": "#BlogPost", "doc": {"value": "Publish article. Current time is set to publishedAt."}, "descriptor": [
        {"href": "#id"}
    ]}
]}

Exmaple

• todomvc
• mini amazon
• LMS

FAQ

Q. Who can use the software?

A. It can be used by anyone involved in site creation (engineers, designers, POs).

Q. What kind of people can write ALPS?

A. Anyone who can understand XML and JSON and can do simple HTML coding can write ALPS.

Q. How do you use it?

A. It is used to design a site by organizing information into the minimum necessary elements, and to design web and API services. The design can be expressed in formats such as JSON and XML, and documents such as transition diagrams and vocabulary lists can be generated. In addition, each producer can know the exact words, meanings and structures of information based on the information design.

Q. What is information design?

A. Based on IA (Information Architecture), it defines the information (meta-information) of information in terms of ontology (meaning of words), taxonomy (classification of information), and choreography (links).

Q. Is it used for design clarification?

A. No, it is not. It can be used as a modeling tool from the very early stage of site design to organize information and formulate what kind of site it will be.

Q. What do I need to write ALPS?

A. You need an editor to edit JSON and XML.

Q. Isn’t it hard to edit XML and JSON directly?

A. If you use an editor that supports schemas such as WebStorm, you can edit them comfortably with completion and validation.

Q. Which is better, XML or JSON?

A. There is no difference in functionality. There is also no need to unify them when using multiple ALPS files. Please compare them in practice. XML / JSON JSON

Q. Can it be used for APIs without links?

A. Yes. It cannot represent a transition diagram, but it can generate a vocabulary and documentation of the nature of the information.

Q. Are there any other technologies that are similar to ALPS?

A. There are no direct competitors. A similar technology is Microformat.

Q. What is the difference from IDL such as OpenAPI?

A. ALPS deals with REST abstractions that are higher than HTTP. Therefore, it can be used as a modeling and design language for OpenAPI implementations.

Q. Do I need it?

A. If you want to model information to improve the quality of user experience, or if you want a reference (SSOT) to unify the understanding among production members, or if you want to overview and reuse your design, or if you want to keep your information design as a standardized document, ALPS+ASD will be useful as your information design modeling tool or as a format to express it.

VERY IMPORTANT:

ALPS is pronounced ‘alps’, the same as the Swiss alps. It is not A-L-P-S. “ælps”

VERY IMPORTANT:

ALPS is pronounced ‘alps’, the same as the Swiss alps. It is not A-L-P-S. “ælps”

VERY IMPORTANT:

ALPS is pronounced ‘alps’, the same as the Swiss alps. It is not A-L-P-S. “ælps”

VERY IMPORTANT:

ALPS is pronounced ‘alps’, the same as the Swiss alps. It is not A-L-P-S. “ælps”

Information Architecture and ALPS

Applying Information Architecture (IA) concepts to domain modeling in API design and system development enables systematic organization of business requirements. The elements of IA—”meaning,” “structure,” and “interaction”—originally developed in UX and content design, play a crucial role in structuring business domain knowledge. ALPS provides a standardized method to express these concepts.

Applying Information Architecture

Information Architecture expert Dan Klyn defined IA as the interplay of Ontology, Taxonomy, and Choreography. ¹ These concepts serve as a foundation not only for content design but also for system design. While OpenAPI focuses on technical API details (endpoints, HTTP methods, request/response structures), ALPS uses these IA concepts to structure the business domain.

Role in the Design Process

ALPS bridges business requirements and system design from the early stages of development. Unlike traditional endpoint-centric design, which typically starts with documenting predetermined API specifications, ALPS can be utilized from the requirements definition phase. This enables early detection and correction of differences in business requirement interpretations. It also establishes a common language between technical and business teams, providing a framework for easily understanding the scope of design changes.

ALPS goes beyond API endpoint design to provide a means of systematizing and sharing business domain knowledge. As a Single Source of Truth (SSOT), it consistently models system structure and behavior. Using business terminology at its core, it clearly expresses complex business rules, visualizes workflows, and enables intuitive understanding of information interactions.

Adapting to Technical Changes

ALPS offers flexibility in its application to various API styles. Even as technology evolves and architecture styles change, business domain design can be maintained. For example, whether transitioning from RESTful APIs to GraphQL, adopting microservice architecture, or implementing new communication protocols, domain models defined in ALPS remain valid. This is because ALPS focuses on abstracted business logic rather than implementation details.

Building Knowledge Foundation

In the implementation of Taxonomy, relationships between business entities are defined, ensuring scalability through hierarchical structure. This establishes a common vocabulary across the organization, streamlining communication. Choreography defines business process flows and service coordination rules, enhancing system-wide consistency and reliability.

Applying IA concepts to domain modeling naturally connects technical implementation with business requirements. ALPS functions as a framework to achieve this bridge, serving as a foundation for systematically structuring and evolving organizational knowledge.

Through this approach, organizations can build a sustainable knowledge foundation that remains resilient to technological changes.

IANA Link Relations

This document lists IANA link relations recommended for use in the rel attribute of ALPS profiles.

State Transitions

Semantic Description

Metadata

Related Information

Notes:

1. This list is an excerpt of relations that are likely to be commonly used in ALPS profiles
2. For a complete list, refer to IANA Registry
3. The categorization is for convenience
4. When using these relations, please select appropriate ones according to your application requirements

Introduction

ALPS: A Format for Clarifying Application-Level Meaning and Structure

Application-Level Profile Semantics (ALPS) is a format that expresses application-level semantics and adds application-specific information to generic media such as JSON and HTML. ALPS clarifies the meaning, structure, and operations of data, enabling efficient development processes, enhanced system interoperability, and improved API reusability and discoverability.

Consider an e-commerce platform as an example. When integrating multiple payment services such as credit cards, digital money, and bank transfers, ALPS standardizes the meaning of data and operations at each step of the payment process. This makes it easier to add new payment methods and integrate with existing systems, allowing developers to implement APIs consistently. Frontend and backend developers can communicate efficiently using a common language, enabling rapid feature additions and improvements.

ASD: Visualizing Application State Transitions

Application State Diagram (ASD) is a tool that visualizes state transitions and behaviors from ALPS documents. It enables intuitive understanding of an application’s overall structure, state transitions, and possible actions. For example, in an online shopping application, it clearly visualizes the process from product search to purchase, helping developers understand the choices and possible operations users face at each stage. This aids in making design decisions that enhance the user experience.

With ASD, all team members—including product owners, backend and frontend developers, and UI/UX designers—can understand the application from the same perspective and work together effectively. This enables smooth communication between members from different specialties and helps new members quickly integrate into complex projects. Furthermore, it allows quick evaluation and adjustment of application flows and logic, providing opportunities to identify and resolve issues early in the design phase, directly contributing to improved development efficiency and application quality.

Through the use of ASD, project transparency increases, minimizing discrepancies in vision among team members.

Information Architecture for REST Application Design

When designing REST applications from an information architecture perspective, ALPS and ASD complement each other in their roles. ALPS standardizes the meaning and structure of data handled by applications, enabling teams to define information using a common vocabulary. ASD, on the other hand, represents state changes in diagrams, making it easy to visually understand user operations and application responses. Through ALPS specifications and ASD visualization, information design in REST application development is strengthened, team communication becomes smoother, and the overall project consistency and quality are enhanced.

To improve development efficiency, deliver excellent user experiences, and ensure project sustainability, a shared understanding among diverse developers is essential. ALPS and ASD build this foundation and support the long-term success of projects.

Introduction

ALPS: A way to organize app information

ALPS (Application Level Profile Semantics) is a way to neatly describe the information and mechanics of an app. It adds app-specific information to formats commonly used on the Internet (e.g., JSON and HTML) to clarify how the app works and what information it handles. This will make the process of creating the app smoother and allow different apps and systems to work well together.

For example, consider an online shopping site. For the sequence of steps (including payment) that a customer goes through to select and buy a product, ALPS can clearly show what is happening at each step. This makes it easier for those who create the app to make the necessary improvements to ensure a smooth shopping experience for customers.

ASD: Diagrams showing how the app works

The ASD (Application State Transition Diagram) shows a diagram of how the app moves and the operations the user can perform based on the app information described in the ALPS. This allows you to understand at a glance how the app is working. In the case of an online shopping site, the diagram shows a series of steps, such as searching for a product, adding it to the cart, and paying for it.

ASD allows people in different roles in the team building the app, such as programmers and designers, to have a common understanding of how the app should work. This can be very helpful in discussions about how to improve the app and in coming up with new ideas.

Designing REST Applications

ALPS and ASD are especially useful for designing apps that run on the web (called REST applications). Using these tools, you can clearly show what information the app handles and how it works. The result is an app that is easier to create and improve, and more user-friendly for the people using it.

In order for team members with diverse skills to work efficiently toward the same goal, it is important that they understand exactly what each other is working on, and ALPS and ASD are very useful tools to help them achieve this understanding.

Resource

• ALPS official
• RFC
• Skeleton
  • json
  • xml
• GitHub Action
• app-state-diagram

Installation and Usage Guide

ASD (app-state-diagram) is a tool for creating comprehensive ALPS documentation that includes application state transition diagrams and vocabulary lists. It can be used in the following ways:

Choosing Usage Method

1. Online Version

Use immediately without local installation:

• https://editor.app-state-diagram.com/

Features:

• No installation required
• Immediately available in browser
• JSON/XML/HTML files can be loaded via drag & drop
• Snippets and advanced code completion
• Recommended option when local installation is not needed
• Note: Currently unable to edit multiple files simultaneously

2. Homebrew Version

Easiest to use in environments where homebrew is installed.

Installation:

brew install alps-asd/asd/asd

3. Docker Version

Download and run a script to execute in Docker. Follow these security verification steps as this involves downloading and running a shell script.

Security Verification Steps

1. Review script content (recommended):

curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh | less

1. Verify checksum:

curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh | sha256sum

Expected value:

0f05034400b2e7fbfee6cddfa9dceb922e51d93fc6dcda62e42803fb8ef05f66

1. Execute installation:

sudo curl -sL https://alps-asd.github.io/app-state-diagram/asd.sh -o /usr/local/bin/asd
sudo chmod +x /usr/local/bin/asd

Prerequisites

• Docker must be installed
• curl command must be available

4. Mac Launcher Application (GUI Version)

A Mac GUI application that doesn’t require command line operations.

Installation steps:

1. Download ASD launcher
2. Security verification:
   • View the downloaded files and verify the contents before proceeding
   • Verify the checksum (SHA-256):

     shasum -a 256 [downloaded zip file]
     

   • Compare with the expected checksum on the official repository: 659ecc3225b95a04f0e2ac4ebed544267ba78a0221db7ed84b6dfd7b08ce423b
3. Open the verified script in Script Editor:
   • If you get a security warning, right-click (or Control-click) the script and select “Open”
   • In System Settings > Privacy & Security, click “Open Anyway” if prompted
4. Select “File” > “Export…”
5. Save location: “Applications”
6. Save as Format: “Application”

5. GitHub Actions Version

Create ASD in CI. See marketplace for details.

6. VSCode Plugin

You can live edit ALPS files while viewing the preview screen using the VSCode Plugin (experimental).

Visual Studio Marketplace - Application State Diagram

Usage

Running Demo

# Download and run demo file
curl -L https://alps-asd.github.io/app-state-diagram/blog/profile.json > alps.json
asd -w ./alps.json

Command Line Options

asd [options] [alpsFile]

Options:
    -w, --watch     Watch mode
    -m, --mode      Drawing mode
    --port          Port to use (default 3000)

Mode Settings

• Markdown mode available for use with private repositories
• However, diagram links don’t function in Markdown mode
• Use as alternative option when HTML cannot be published

Installation Verification

asd
usage: asd [options] alps_file
@see https://github.com/alps-asd/app-state-diagram#usage

Selection Guidelines

• Quick trial, temporary use → Online version
• Local use on Mac → Homebrew version
• Cross-platform use → Docker version
• Mac local environment with GUI → Launcher application
• CI/CD environment use → GitHub Actions version

ALPS Reference

Overview

Application-Level Profile Semantics (ALPS) is a document format for describing application semantics. This document explains the elements and attributes of ALPS.

Document Structure

ALPS documents have the following hierarchical structure:

1. Root Element (alps)
   • The root element of the document containing version information
   • All definitions are contained within this element
2. Descriptor Element (descriptor)
   • The central element that defines the meaning of application features and information
   • There are four types:
     • semantic: Represents information or terminology (default)
     • safe: Read operations (does not change resource state)
     • idempotent: Operations that produce the same result when executed multiple times (e.g., complete replacement with PUT or removal with DELETE)
     • unsafe: Operations that produce different results when executed multiple times (e.g., creation with POST, numeric addition, etc.)
   • Can contain other descriptor elements as child elements
   • Can contain link elements as child elements
3. Supplementary Elements
   • doc: Detailed explanations or supplementary information
   • link: References to related documents
   • title: Description of the profile

Representation Formats

ALPS documents can be written in the following two formats:

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<alps version="1.0">
    <title>Blog API Profile</title>
    <doc>API profile for a blog system</doc>
    
    <descriptor id="title" title="Title" doc="Article title. Maximum 100 characters."/>
    
    <descriptor id="blogPost">
        <doc>Blog post</doc>
        <descriptor href="#title"/>
        <link rel="related" href="http://example.org/related-docs/blog.html" />
    </descriptor>
</alps>

JSON Format

{
    "alps": {
        "version": "1.0",
        "title": "Blog API Profile",
        "doc": {"value": "API profile for a blog system"},
        "descriptor": [
            {"id": "title", "title": "Title", "doc": {"value": "Article title. Maximum 100 characters."}},
            {"id": "blogPost", "doc": {"value": "Blog post"}, 
             "descriptor": [
                {"href": "#title"}
             ],
             "link": [
                {"rel": "related", "href": "http://example.org/related-docs/blog.html"}
             ]
            }
        ]
    }
}

Elements and Attributes in Detail

alps

The root element of an ALPS document.

Attributes:

• version: The document version (required)

descriptor

Defines the semantics (meaning) of application features or information. Either id or href is required, and other attributes are optional.

A descriptor can have the following child elements:

• descriptor: Other descriptor elements can be nested to represent hierarchical structures
• doc: Detailed description
• link: Links to related resources
• ext: Extension information

descriptor attributes list

Format attribute support levels:

• text: Required support (MUST)
• html: Recommended support (SHOULD)
• asciidoc: Optional support (MAY)
• markdown: Optional support (MAY), compliant with [RFC7763]

Priority of contentType and format:

• If contentType exists, it is used
• If both contentType and format exist, format is ignored
• If neither exists, text/plain is assumed

link

Defines references to related documents. Link can be used as a child element of alps or descriptor elements.

link attributes list

Validation

1. A descriptor requires either id or href
2. href reference targets must be resolvable URLs and must include a fragment identifier
3. rt transition targets must exist in the document
4. The type attribute must be one of the four defined values (semantic, safe, idempotent, unsafe)
5. The following prefixes are recommended for operation descriptors:
   • safe: go (e.g., goBlog)
   • unsafe: do (e.g., doCreateBlog)
   • idempotent: do (e.g., doUpdateBlog)

Hierarchical Structure Example

Below is a concise example of hierarchical structure using nested descriptor elements:

XML Format

<alps version="1.0">
  <descriptor id="user" type="semantic">
    <doc>User information</doc>
    <descriptor id="name" type="semantic" />
    <descriptor id="email" type="semantic" />
    <link rel="help" href="http://example.org/help/user.html" />
  </descriptor>
</alps>

JSON Format

{
  "alps": {
    "version": "1.0",
    "descriptor": [
      {
        "id": "user",
        "type": "semantic",
        "doc": {"value": "User information"},
        "descriptor": [
          {"id": "name", "type": "semantic"},
          {"id": "email", "type": "semantic"}
        ],
        "link": [
          {"rel": "help", "href": "http://example.org/help/user.html"}
        ]
      }
    ]
  }
}

Schema.org Terms

Properties