ALPS to OpenAPI Converter

Generate OpenAPI 3.1 specification from ALPS profile with validation loop.

When to Use

• User asks to generate OpenAPI from ALPS
• User wants to create REST API documentation from ALPS profile
• User says "alps2openapi", "convert to openapi", "generate api spec"

Conversion Rules

1. Transition Type → HTTP Method

ALPS type	HTTP Method	Description
safe	GET	Read operations
unsafe	POST	Create operations (non-idempotent)
idempotent	PUT/DELETE/PATCH	Update/Delete operations (idempotent)

Determining idempotent Method

Infer from transition ID:

PUT (Update):

• Keywords: update, edit, modify, change, set, replace
• Example: doUpdateUser, doEditPost, doSetStatus

DELETE:

• Keywords: delete, remove, cancel, clear, destroy
• Example: doDeleteUser, doRemoveItem, doCancelOrder

PATCH:

• Keywords: toggle, patch, increment, decrement
• Example: doToggleComplete, doPatchProfile

2. Transition ID → operationId

Use ALPS transition ID directly as operationId:

• goTodoList → operationId: goTodoList
• doCreateTodo → operationId: doCreateTodo

3. Path Generation

Transition Pattern	Path	Method
goXxxList	/xxxs	GET
goXxxDetail	/xxxs/{xxxId}	GET
doCreateXxx	/xxxs	POST
doUpdateXxx	/xxxs/{xxxId}	PUT
doDeleteXxx	/xxxs/{xxxId}	DELETE
doToggleYyy	/xxxs/{xxxId}/yyy	PATCH

Path Naming Rules

• Use lowercase plural nouns: /todos, /users, /products
• Use kebab-case for multi-word: /order-items, /user-profiles
• Nested resources: /users/{userId}/posts

4. Schema Generation

Semantic Fields → Properties

Map ALPS semantic descriptors to OpenAPI schema properties:

# ALPS
{"id": "todoId", "title": "Task ID", "def": "https://schema.org/identifier"}

# OpenAPI
todoId:
  type: string
  description: Task ID

States → Schema Names

ALPS states become OpenAPI schema names:

• TodoList → TodoListItem (for list responses)
• TodoDetail → TodoDetail (for single item responses)

5. schema.org → OpenAPI Format Mapping

schema.org	OpenAPI
https://schema.org/DateTime	type: string, format: date-time
https://schema.org/Date	type: string, format: date
https://schema.org/Time	type: string, format: time
https://schema.org/Email	type: string, format: email
https://schema.org/URL	type: string, format: uri
https://schema.org/identifier	type: string
https://schema.org/Integer	type: integer
https://schema.org/Number	type: number
https://schema.org/Boolean	type: boolean
https://schema.org/Text	type: string

6. Input Parameters

Extract from transition's nested descriptors:

{"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
  {"href": "#title"},
  {"href": "#description"},
  {"href": "#dueDate"}
]}

Becomes:

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateTodoRequest'

With schema:

CreateTodoRequest:
  type: object
  properties:
    title:
      type: string
    description:
      type: string
    dueDate:
      type: string
      format: date-time
  required:
    - title

7. HTTP Status Codes

Operation	Success	Client Error	Not Found
GET (single)	200	400	404
GET (list)	200	400	-
POST	201	400, 409	-
PUT	200	400	404
PATCH	200	400	404
DELETE	204	400	404

8. Error Response Schema

Always include standard error schema:

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

9. Required Fields

Request (POST/PUT):

• Fields in transition's descriptor are required by default
• Mark as optional with (optional) in ALPS doc

Response:

• ID field is always required
• Primary fields (title, name, etc.) are required
• Timestamps (createdAt, updatedAt) are required

10. Tags from ALPS

Use ALPS tag attribute for OpenAPI tags:

{"id": "goTodoList", "type": "safe", "rt": "#TodoList", "tag": "todo"}

Becomes:

tags:
  - todo

Workflow

1. Read ALPS profile - Parse JSON or XML
2. Extract components:
   • Semantic fields → Schema properties
   • States → Response schemas
   • Transitions → Operations
3. Generate OpenAPI YAML
4. Validate with Spectral:

   npx @stoplight/spectral-cli lint <output_file>

5. Fix errors - If validation fails, fix and regenerate
6. Return result - Provide the validated OpenAPI spec

Output Format

• YAML format (not JSON)
• OpenAPI version: 3.1.0
• Include $schema reference
• Japanese descriptions from ALPS title

Template

openapi: 3.1.0
info:
  title: {alps.title}
  description: {alps.doc}
  version: 1.0.0

servers:
  - url: http://localhost:8080/api
    description: Development server

paths:
  # Generated from transitions

components:
  schemas:
    # Generated from semantic descriptors and states
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Validation

After generating OpenAPI, validate:

npx @stoplight/spectral-cli lint openapi.yaml

If errors occur:

1. Read error messages
2. Fix the issues in the generated spec
3. Re-validate until no errors

Example

Input (ALPS)

{
  "alps": {
    "title": "Todo API",
    "descriptor": [
      {"id": "todoId", "title": "Task ID"},
      {"id": "title", "title": "Title"},
      {"id": "completed", "title": "Completed"},

      {"id": "TodoList", "descriptor": [
        {"href": "#todoId"},
        {"href": "#title"},
        {"href": "#goTodoDetail"},
        {"href": "#doCreateTodo"}
      ]},

      {"id": "goTodoList", "type": "safe", "rt": "#TodoList"},
      {"id": "goTodoDetail", "type": "safe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#todoId"}
      ]},
      {"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#title"}
      ]},
      {"id": "doDeleteTodo", "type": "idempotent", "rt": "#TodoList", "descriptor": [
        {"href": "#todoId"}
      ]}
    ]
  }
}

Output (OpenAPI)

openapi: 3.1.0
info:
  title: Todo API
  version: 1.0.0

paths:
  /todos:
    get:
      operationId: goTodoList
      summary: Get todo list
      responses:
        '200':
          description: Todo list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TodoListItem'

    post:
      operationId: doCreateTodo
      summary: Create todo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTodoRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '400':
          $ref: '#/components/responses/BadRequest'

  /todos/{todoId}:
    parameters:
      - name: todoId
        in: path
        required: true
        schema:
          type: string

    get:
      operationId: goTodoDetail
      summary: Get todo detail
      responses:
        '200':
          description: Todo detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: doDeleteTodo
      summary: Delete todo
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    TodoListItem:
      type: object
      properties:
        todoId:
          type: string
          description: Task ID
        title:
          type: string
          description: Title
      required:
        - todoId
        - title

    TodoDetail:
      type: object
      properties:
        todoId:
          type: string
        title:
          type: string
        completed:
          type: boolean
      required:
        - todoId
        - title
        - completed

    CreateTodoRequest:
      type: object
      properties:
        title:
          type: string
      required:
        - title

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'