OpenAPI Mapping Reference

Complete reference for type and construct mappings between OpenAPI specifications and Pulse IDL.

Type Mapping Tables

Primitive Types

OpenAPI to Pulse

Pulse to OpenAPI

Complex Types

OpenAPI to Pulse

Pulse to OpenAPI

Struct Mapping

OpenAPI to Pulse

OpenAPI Schema:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string

Generated Pulse IDL:

struct User {
    id    int
    name  string
    email string   [optional]
}

Rules:

1. Schema title or schema name becomes struct name
2. required array determines [optional] annotations
3. Property names are converted to camelCase
4. description field becomes doc comment
5. nullable: true adds [optional] annotation

Pulse to OpenAPI

Pulse IDL:

// User represents a user account
struct User {
    userId    string
    firstName string
    lastName  string
    email     string   [optional]
}

Generated OpenAPI Schema:

components:
  schemas:
    User:
      description: User represents a user account
      type: object
      properties:
        userId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
      required:
        - userId
        - firstName
        - lastName

Rules:

1. Struct name becomes schema name
2. Fields without [optional] are in required array
3. IDL comments become description fields
4. Field names preserve original casing

Enum Mapping

OpenAPI to Pulse

OpenAPI Schema:

components:
  schemas:
    Status:
      type: string
      enum:
        - active
        - inactive
        - pending
      description: User account status

Generated Pulse IDL:

// User account status
enum Status {
    active
    inactive
    pending
}

Rules:

1. Only type: string enums are supported
2. Enum values are converted to valid Pulse identifiers
3. description field becomes doc comment
4. Numeric enums are converted to struct with const values (warning issued)

Pulse to OpenAPI

Pulse IDL:

// Order status enumeration
enum OrderStatus {
    pending
    paid
    shipped
    delivered
    cancelled
}

Generated OpenAPI Schema:

components:
  schemas:
    OrderStatus:
      description: Order status enumeration
      type: string
      enum:
        - pending
        - paid
        - shipped
        - delivered
        - cancelled

Rules:

1. All Pulse enums map to type: string
2. Enum values preserve original casing
3. IDL comments become description fields

Inheritance (extends)

OpenAPI to Pulse

OpenAPI Schema:

components:
  schemas:
    Animal:
      type: object
      required:
        - name
      properties:
        name:
          type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          required:
            - breed
          properties:
            breed:
              type: string

Generated Pulse IDL:

struct Animal {
    name  string
}

struct Dog extends Animal {
    breed  string
}

Rules:

1. allOf with exactly one $ref + object maps to extends
2. allOf with multiple $refs issues warning (uses first)
3. allOf with no $refs issues warning (flattens properties)
4. Order is preserved: parent types before child properties

Pulse to OpenAPI

Pulse IDL:

struct Animal {
    name  string
}

struct Dog extends Animal {
    breed  string
}

Generated OpenAPI Schema:

components:
  schemas:
    Animal:
      type: object
      properties:
        name:
          type: string
      required:
        - name

    Dog:
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          properties:
            breed:
              type: string
          required:
            - breed

Rules:

1. extends keyword maps to allOf composition
2. Parent struct is first item in allOf array
3. Child properties are in second allOf item

Optional Fields

OpenAPI to Pulse

Fields are optional in Pulse when:

1. Not in the required array
2. Marked with nullable: true

OpenAPI Schema:

components:
  schemas:
    User:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        email:
          type: string

Generated Pulse IDL:

struct User {
    id     string
    name   string   [optional]
    email  string   [optional]
}

Pulse to OpenAPI

Fields with [optional] are excluded from the required array.

Pulse IDL:

struct User {
    userId    string
    email     string   [optional]
}

Generated OpenAPI Schema:

components:
  schemas:
    User:
      type: object
      properties:
        userId:
          type: string
        email:
          type: string
      required:
        - userId

Interface and Method Mapping

OpenAPI to Pulse

Interface Grouping

Operations are grouped into interfaces by:

1. Primary: First tag in tags array
2. Fallback: Path prefix (e.g., /pets/* → pets interface)

OpenAPI Paths:

paths:
  /pets:
    get:
      operationId: listPets
      tags:
        - pets
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
  /pets/{id}:
    get:
      operationId: getPet
      tags:
        - pets
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

Generated Pulse IDL:

interface pets {
    getListPets() []listPetsResponse_item
    getShowPetById(petId string) showPetByIdResponse_item
}

Method Naming

Method names follow the pattern: {httpMethod}{operationId}

If operationId is missing, it’s derived from the path:

• /pets/{id} → getPetsById

Parameter Mapping

All parameters become method parameters:

Request Body Mapping

Request body becomes a parameter named after the operation or body:

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

Becomes:

postCreatePet(createPetBody NewPet) ...

Response Mapping

Success responses determine return type:

Pulse to OpenAPI

Path Generation

Each interface method becomes a POST endpoint:

Pattern: POST /{interface}/{method}

Pulse IDL:

interface UserService {
    getUser(userId string) User
    createUser(user CreateUserRequest) User
}

Generated Paths:

paths:
  /UserService/getUser:
    post:
      operationId: UserService_getUser
      tags:
        - UserService
      requestBody:
        # ... userId parameter
      responses:
        '200':
          # ... User schema

  /UserService/createUser:
    post:
      operationId: UserService_createUser
      tags:
        - UserService
      requestBody:
        # ... user parameter
      responses:
        '200':
          # ... User schema

operationId Format

Format: {interface}_{method}

Examples:

• UserService.getUser → UserService_getUser
• OrderService.placeOrder → OrderService_placeOrder

Tags

Each Pulse interface becomes an OpenAPI tag:

Pulse IDL:

interface CatalogService { }
interface CartService { }

Generated Tags:

tags:
  - name: CatalogService
    description: Pulse interface: CatalogService
  - name: CartService
    description: Pulse interface: CartService

Namespace Mapping

OpenAPI to Pulse

Namespace is derived from info.title:

1. Convert to lowercase
2. Replace non-alphanumeric characters with underscores
3. Ensure valid identifier

Examples:

Pulse to OpenAPI

info.title is derived from namespace:

Pulse IDL:

namespace my_service

Generated OpenAPI:

info:
  title: My_Service
  description: |
    Namespace: my_service

    Interfaces: 2
    Structs: 5
    Enums: 1

Warning Conditions

OpenAPI to Pulse Warnings

Pulse to OpenAPI Warnings

Circular Reference Handling

OpenAPI to Pulse

Circular references are detected and broken with [optional]:

OpenAPI Schema:

components:
  schemas:
    Node:
      type: object
      properties:
        value:
          type: string
        next:
          $ref: '#/components/schemas/Node'

Generated Pulse IDL:

struct Node {
    value  string
    next   Node   [optional]   // [optional] breaks circular reference
}

Warning Issued:

Warning: circular reference detected at #/components/schemas/Node/next (breaking with [optional])

Examples

See the OpenAPI Examples directory for complete working examples:

• petstore.yaml - Standard Petstore OpenAPI 3.0 spec
• petstore.pulse - Generated Pulse IDL
• simple-api.pulse - Simple Pulse IDL for round-trip testing
• simple-api.openapi.yaml - Generated OpenAPI spec

Additional Resources

• OpenAPI Specification
• OpenAPI 3.0 to 3.1 Migration Guide
• IDL Syntax Reference
• OpenAPI Translation Guide