Alps

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 Description (nl2alps)

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

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

1. Identify Entities (Ontology)

   • Extract nouns: user, product, order, cart, etc.
   • Define atomic fields for each entity

2. Identify States (Taxonomy)

   • Map user journey: login -> home -> browse -> cart -> checkout
   • Each state contains relevant fields and available transitions

3. Identify Transitions (Choreography)

   • Safe: navigation, viewing, searching
   • Unsafe: creating new resources
   • Idempotent: updating or deleting resources

4. Add Documentation

   • Every descriptor should have a meaningful title
   • Complex descriptors should have doc explaining behavior
   • Link to schema.org definitions where applicable (def)

5. Add Tags for Organization

   • Functional area tags: Group by feature domain (e.g., search, product, cart, checkout, order, account, review)
   • Flow tags: Group by user journey with flow- prefix (e.g., flow-purchase, flow-register, flow-return)
   • States and transitions should have both types where applicable
   • Example: A cart-related transition might have "tag": ["cart", "flow-purchase"]

6. Add Semantic Descriptors to Transitions

   • Every transition (go/do) should specify its required input parameters as nested descriptors
   • These define what data is needed to perform the action
   • Example:

     {"id": "goProductDetail", "type": "safe", "rt": "#ProductDetail", "tag": ["product"], "descriptor": [
       {"href": "#productId"}
     ]},
     {"id": "doAddToCart", "type": "unsafe", "rt": "#Cart", "tag": ["cart", "flow-purchase"], "descriptor": [
       {"href": "#productId"},
       {"href": "#quantity"},
       {"href": "#selectedVariant"}
     ]}
     

7. MANDATORY: Validate After Generation

   • After generating ALPS JSON, save it to a temporary file
   • Run asd --validate <file> to validate (outputs JSON per validation-result.json schema)
   • Parse the JSON result and report issues to the user
   • If errors exist, fix them before presenting the final output

Output Format

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

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

      // Taxonomy: states
      {"id": "StateName", "title": "State Title", "descriptor": [
        {"href": "#fieldName"},
        {"href": "#transitionName"}
      ]},

      // Choreography: transitions
      {"id": "goToState", "type": "safe", "rt": "#TargetState", "title": "Navigate to State"},
      {"id": "doAction", "type": "unsafe", "rt": "#ResultState", "title": "Perform Action",
        "descriptor": [{"href": "#requiredField"}]}
    ]
  }
}

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

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)

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:

{
  "$schema": "https://alps-io.github.io/schemas/alps.json",
  "alps": {
    "title": "Simple Blog",
    "doc": {"value": "ALPS profile for a blog application with posts and comments"},
    "descriptor": [
      {"id": "postId", "title": "Post ID", "def": "https://schema.org/identifier"},
      {"id": "title", "title": "Post Title", "def": "https://schema.org/headline"},
      {"id": "body", "title": "Post Body", "def": "https://schema.org/articleBody"},
      {"id": "authorName", "title": "Author Name", "def": "https://schema.org/author"},
      {"id": "createdAt", "title": "Created Date", "def": "https://schema.org/dateCreated"},
      {"id": "commentId", "title": "Comment ID"},
      {"id": "commentBody", "title": "Comment Text"},

      {"id": "Home", "title": "Home Page", "descriptor": [
        {"href": "#goPostList"}
      ]},
      {"id": "PostList", "title": "Post List", "descriptor": [
        {"href": "#postId"},
        {"href": "#title"},
        {"href": "#authorName"},
        {"href": "#goPostDetail"},
        {"href": "#goHome"}
      ]},
      {"id": "PostDetail", "title": "Post Detail", "descriptor": [
        {"href": "#postId"},
        {"href": "#title"},
        {"href": "#body"},
        {"href": "#authorName"},
        {"href": "#createdAt"},
        {"href": "#Comment"},
        {"href": "#goPostList"},
        {"href": "#doCreateComment"}
      ]},
      {"id": "Comment", "title": "Comment", "descriptor": [
        {"href": "#commentId"},
        {"href": "#commentBody"},
        {"href": "#authorName"},
        {"href": "#createdAt"},
        {"href": "#doDeleteComment"}
      ]},

      {"id": "goHome", "type": "safe", "rt": "#Home", "title": "Go to Home"},
      {"id": "goPostList", "type": "safe", "rt": "#PostList", "title": "View Post List"},
      {"id": "goPostDetail", "type": "safe", "rt": "#PostDetail", "title": "View Post Detail",
        "descriptor": [{"href": "#postId"}]},
      {"id": "doCreatePost", "type": "unsafe", "rt": "#PostDetail", "title": "Create Post",
        "descriptor": [{"href": "#title"}, {"href": "#body"}]},
      {"id": "doUpdatePost", "type": "idempotent", "rt": "#PostDetail", "title": "Update Post",
        "descriptor": [{"href": "#postId"}, {"href": "#title"}, {"href": "#body"}]},
      {"id": "doDeletePost", "type": "idempotent", "rt": "#PostList", "title": "Delete Post",
        "descriptor": [{"href": "#postId"}]},
      {"id": "doCreateComment", "type": "unsafe", "rt": "#PostDetail", "title": "Add Comment",
        "descriptor": [{"href": "#postId"}, {"href": "#commentBody"}]},
      {"id": "doDeleteComment", "type": "idempotent", "rt": "#PostDetail", "title": "Delete Comment",
        "descriptor": [{"href": "#commentId"}]}
    ]
  }
}

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

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