alps

name	alps
description	Create, validate, and improve ALPS profiles. Generate from natural language descriptions, validate existing profiles, and get improvement suggestions.

ALPS Profile Assistant

Generate, validate, and improve ALPS profiles for RESTful API design.

Ideal ALPS Profile

Goal: An ALPS that someone unfamiliar with the app can read and understand.

What Makes a Good ALPS

1. States = What the user sees

   • ProductList - viewing a list of products
   • ProductDetail - viewing one product
   • Cart - viewing cart contents

2. Transitions = What the user does

   • goProductDetail - select a product
   • doAddToCart - add to cart

3. Self-documenting

   • title explains the purpose
   • doc describes behavior and side effects
   • No need to read code to understand

4. No unreachable states

   • Every state has an entry point
   • Orphan states indicate design mistakes

5. Necessary and sufficient

   • No over-abstraction
   • Describes semantics, not implementation
   • No HTTP methods or URLs

What to Avoid

• Mechanical CRUD listings without meaning
• Implementation details leaking in
• States without transitions (can't draw a diagram)
• Excessive documentation nobody reads

How to Use

This skill responds to natural language requests:

Generate ALPS from Natural Language

• "Create an ALPS profile for a blog application"
• "Generate ALPS for an e-commerce cart system"
• "Design an ALPS profile for user authentication"

Validate Existing Profile

• "Validate this ALPS profile" (with file path or content)
• "Check my ALPS file for issues"
• "Review the ALPS profile at docs/api.json"

Get Improvement Suggestions

• "Improve this ALPS profile"
• "Suggest enhancements for my ALPS"
• "How can I make this ALPS better?"

ALPS Structure Reference

Three Layers of ALPS

1. Ontology - Semantic descriptors (data elements)

   • Atomic data fields with type="semantic" (default)
   • Should have id, title, and optionally doc and def (schema.org link)

2. Taxonomy - State descriptors (screens/pages)

   • Composite descriptors containing semantic fields and transitions
   • Represents application states (e.g., HomePage, ProductDetail, Cart)

3. Choreography - Transition descriptors (actions)

   • type="safe" - Read operations (GET)
   • type="unsafe" - Create operations (POST) - not idempotent
   • type="idempotent" - Update/Delete operations (PUT/DELETE)
   • Must have rt (return type) pointing to target state

Naming Conventions

Type	Prefix	Example
Safe transition	go	goToHome, goProductList, goSearchProducts
Unsafe transition	do	doCreateUser, doAddToCart, doLogin
Idempotent transition	do	doUpdateUser, doDeleteItem, doRemoveFromCart
State/Page	PascalCase	HomePage, ProductDetail, ShoppingCart
Semantic field	camelCase	userId, productName, createdAt

Safe Transition Naming Rule

IMPORTANT: Safe transitions (go*) MUST include the target state name in their id.

• rt="#ProductList" → id must be goProductList (or goToProductList)
• rt="#UserProfile" → id must be goUserProfile (or goToUserProfile)

Invalid examples:

• goStart with rt="#ProductList" - Wrong! Should be goProductList
• goNext with rt="#Checkout" - Wrong! Should be goCheckout

This rule ensures consistency and makes the diagram self-documenting. When a transition has no source state (entry point), it will be displayed as originating from UnknownState in the diagram.

Determining idempotent: PUT vs DELETE

Context clues for AI inference:

PUT (Update) indicators:

• update, edit, modify, change, set, replace
• Example: doUpdateProfile, doEditComment, doSetQuantity

DELETE indicators:

• delete, remove, cancel, clear, destroy
• Example: doDeleteUser, doRemoveFromCart, doCancelOrder

Generation Guidelines

When Creating ALPS from Natural Language

IMPORTANT: Structure the ALPS file in three blocks in this order:

1. Identify Entities (Ontology - Semantic definitions)

   • Extract nouns: user, product, order, cart, etc.
   • Define atomic fields for each entity
   • Add def links to schema.org where applicable
   • Add doc for validation rules, formats, constraints

2. Identify States (Taxonomy - Inclusion relationships)

   • Map user journey: login -> home -> browse -> cart -> checkout
   • Each state contains relevant fields and available transitions
   • Use PascalCase for state names
   • Add doc explaining what user sees and available actions

3. Identify Transitions (Choreography - State transitions)

   • Safe: navigation, viewing, searching (prefix: go)
   • Unsafe: creating new resources (prefix: do)
   • Idempotent: updating or deleting resources (prefix: do)
   • Add doc explaining behavior, side effects, preconditions

4. Add Documentation

   • Every descriptor MUST have a meaningful title
   • Add doc when title alone cannot fully explain the descriptor:
     • Semantic fields: Validation rules, format requirements, constraints, examples
       • Example: {"id": "title", "title": "Title", "doc": {"value": "Article title. Maximum 100 characters."}}
     • States: What user sees, available actions, when this state is shown
       • Example: {"id": "BlogPost", "doc": {"value": "User-created article. Visible to all users after publication."}}
     • Transitions: Behavior, side effects, preconditions, error cases
       • Example: {"id": "doPublishBlogPost", "doc": {"value": "Publish article. Sets publishedAt to current time."}}
   • Use def to link to schema.org definitions for standard concepts
   • Rule of thumb: If someone unfamiliar with the app would ask "what does this do?" or "what format?", add doc

5. Add Tags for Organization

Output Format

Generate XML format by default. Use JSON only if explicitly requested.

XML Format (default):

• Use XML comments to mark blocks: <!-- Ontology -->, <!-- Taxonomy -->, <!-- Choreography -->
• One descriptor per line for simple elements
• Multi-line for nested structures
• Clear hierarchical structure makes maintenance easy

<?xml version="1.0" encoding="UTF-8"?>
<alps version="1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
  <title>Application Title</title>
  <doc>Description of the application</doc>

  <!-- Ontology -->
  <descriptor id="fieldName" title="Human Title">
    <doc>Description</doc>
  </descriptor>
  <descriptor id="otherField" title="Other Field"/>

  <!-- Taxonomy -->
  <descriptor id="StateName" title="State Title">
    <descriptor href="#fieldName"/>
    <descriptor href="#transitionName"/>
  </descriptor>

  <!-- Choreography -->
  <descriptor = = = =/>
  
    
  

JSON Format (when explicitly requested):

• Simple descriptors (few attributes, no nesting): Write on a single line
• Complex descriptors (with nesting or long doc): Use multiple lines with "descriptor": [ at end of first line
• Block separation: Add ONE blank line between Ontology/Taxonomy/Choreography blocks
• No other blank lines: Keep descriptors within the same block compact

{
  "$schema": "https://alps-io.github.io/schemas/alps.json",
  "alps": {
    "title": "Application Title",
    "doc": {"value": "Description of the application"},
    "descriptor": [
      {"id": "fieldName", "title": "Human Title", "doc": {"value": "Description"}},
      {"id": "otherField", "title": "Other Field"},

      {"id": "StateName", "title":   
         
         
      

             
               
         
      
    
  

Validation

Use asd --validate <file> to validate ALPS profiles. Output conforms to the validation-result.json schema.

Error Codes (E)

• E001: Missing id or href
• E002: Missing rt on transition
• E003: Invalid type
• E004: Broken reference
• E005: Duplicate id
• E006: Invalid href
• E007: Invalid rt format
• E008: Missing alps property in document
• E009: Descriptor must be an array
• E010: Invalid XML character in descriptor title
• E011: Tag must be a string (space-separated), not an array

Warning Codes (W)

• W001: Missing title
• W002: Safe transition naming (should start with 'go')
• W003: Unsafe/idempotent naming (should start with 'do')
• W004: Orphan descriptor
• W005: Safe transition id does not match rt target (e.g., goStart with rt="#ProductList" should be goProductList)
• W006: Tag contains comma - may be confused with space-separated format

Suggestion Codes (S)

• S001: Missing doc on transition
• S002: Missing ALPS title
• S003: Missing ALPS doc

Example: Blog Application

Input: "Create an ALPS for a simple blog with posts and comments"

Output (XML - default):

<?xml version="1.0" encoding="UTF-8"?>
<alps version="1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
  <title>Simple Blog</title>
  <doc>ALPS profile for a blog application with posts and comments</doc>

  <!-- Ontology -->
  <descriptor id="postId" title="Post ID" def="https://schema.org/identifier">
    <doc>Unique identifier for blog post</doc>
  </descriptor>
  <descriptor id="title" title="Post Title" def="https://schema.org/headline">
    <doc>Article title. Maximum 100 characters.</doc>
  </descriptor>
  <descriptor id="body" title="Post Body" def="https://schema.org/articleBody">
    Article content. Markdown format supported.
  
  
  
    Publication date and time. ISO 8601 format.
  
  
    Unique identifier for comment
  
  
    Comment content. Maximum 500 characters.
  

  
  
    Blog home page. Shows navigation to post list.
    
  
  
    List of blog posts. Shows latest 10 posts with title and author.
    
    
    
    
    
  
  
    Single post view. Shows full content and comments. Allows adding new comments.
    
    
    
    
    
    
    
    
  
  
    User comment on a post. Can be deleted by comment author or post author.
    
    
    
    
    
  

  
  
    Navigate to blog home page.
  
  
    Display list of blog posts. Shows latest 10 posts.
  
  
    Display full post content with comments.
    
  
  
    Create new blog post. Post is immediately published.
    
    
  
  
    Update existing post content. Only post author can update.
    
    
    
  
  
    Delete post and all associated comments. Only post author can delete.
    
  
  
    Add comment to post. Comment is immediately visible.
    
    
  
  
    Delete comment. Comment author or post author can delete.
    
  

Integration with app-state-diagram

Generated ALPS profiles can be visualized using app-state-diagram:

# Generate HTML diagram
asd profile.json

# Generate with watch mode
asd --watch profile.json

# Generate markdown documentation
asd --mode=markdown profile.json

Advanced Features

Structured Documentation with HTML

For simple descriptions, use plain text in doc.value. When you need structured content (lists, definitions, tables), use HTML format:

{"id": "doCheckout", "type": "unsafe", "rt": "#OrderConfirmation",
 "title": "Complete Checkout",
 "doc": {
   "format": "html",
   "value": "<dl><dt>Behavior</dt><dd>Processes payment, reserves inventory, sends confirmation email</dd><dt>Preconditions</dt><dd>Valid cart with items, payment method configured</dd><dt>Errors</dt><dd>Returns 400 if payment fails or items out of stock</dd></dl>"
 }
}

Format support levels (per ALPS spec):

• text: Required (default if not specified)
• html: Recommended
• markdown: Optional
• asciidoc: Optional

Links to Related Resources

Use link elements to reference external documentation, schemas, or related resources:

{"id": "BlogPost", "def": "https://schema.org/BlogPosting",
 "title": "Blog Post",
 "doc": {"value": "User-created article visible to all after publication"},
 "link": [
   {"rel": "help", "href": "https://example.com/docs/blog-api.html", "title": "Blog API Documentation"},
   {"rel": "related", "href": "https://example.com/schemas/post.json", "title": "JSON Schema"}
 ]
}

Link attributes:

• rel (required): Relationship type - use IANA Link Relations (help, related, profile, etc.)
• href (required): URL to the related resource
• title (optional): Human-readable description of the link
• tag (optional): Classification tags

Tips for Better ALPS

1. Start with user journeys - Map the happy path first, then add alternatives
2. Be consistent - Use the same naming pattern throughout
3. Document transitions - Explain what each action does and when it's available
4. Use schema.org - Link to standard definitions for interoperability
5. Think about errors - Add error states and recovery transitions
6. Consider pagination - List states should support pagination
7. Tag descriptors - Use tag attribute to group related descriptors

References

• ALPS Specification
• Schema.org
• app-state-diagram