OpenRPCWorkflow & automation

Overlay Customizations

Use overlay files to modify your OpenRPC specification without editing the original

Overlays allow you to modify your OpenRPC specification without directly editing the original file. This is useful for:

  • Adding Fern-specific extensions
  • Customizing documentation
  • Adding examples and descriptions
  • Overriding specific properties

Configure overlays

To use overlays, add them to your generators.yml file:

generators.yml
1api:
2  specs:
3    - spec: openrpc.yml
4      overlays:
5        - overlay.yml
6  generators:
7    - name: fernapi/fern-typescript-node-sdk
8      version: 0.8.8

Overlay file structure

Overlay files follow the OpenAPI Overlay Specification format:

overlay.yml
1overlay: 1.0.0
2info:
3  title: OpenRPC Fern Extensions
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'user.create')]
7    update:
8      x-fern-sdk-method-name: create
9      summary: Create a new user account
10  - target: $.methods[?(@.name == 'order.list')]
11    update:
12      description: Retrieve orders with optional filtering and pagination
13      x-fern-audiences:
14        - public

Add method names

Override SDK method names for better developer experience:

overlay.yml
1overlay: 1.0.0
2info:
3  title: SDK Method Names
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'user.getById')]
7    update:
8      x-fern-sdk-method-name: getUser
9      summary: Retrieve user by ID with enhanced details
10  - target: $.methods[?(@.name == 'order.createNew')]
11    update:
12      x-fern-sdk-method-name: create
13      summary: Create order with automatic validation

Add examples

Enhance your specification with examples:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Method Examples
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'user.create')]
7    update:
8      examples:
9        - name: StandardUser
10          description: Create a regular user
11          params:
12            userData:
13              email: "john@example.com"
14              name: "John Doe"
15              role: "user"
16          result:
17            id: "user_123"
18            email: "john@example.com"
19            name: "John Doe"
20            createdAt: "2024-01-15T10:30:00Z"

Filter with audiences

Add audience filtering to methods:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Audience Filtering
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'admin.getUsers')]
7    update:
8      x-fern-audiences:
9        - admin
10  - target: $.methods[?(@.name == 'debug.getSystemInfo')]
11    update:
12      x-fern-audiences:
13        - internal

Add documentation

Enhance descriptions and documentation:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Enhanced Documentation
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'payment.process')]
7    update:
8      description: |
9        Process a payment transaction with comprehensive validation and fraud detection.
10        
11        This method supports multiple payment methods including credit cards, 
12        digital wallets, and bank transfers. All transactions are processed
13        securely with PCI DSS compliance.
14        
15        Returns a payment result with transaction details or error information.
16      summary: Process payment with fraud detection

Server configurations

Add server-specific configurations:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Server Extensions
4  version: 1.0.0
5actions:
6  - target: $.servers[?(@.name == 'production')]
7    update:
8      x-fern-server-name: Production
9      description: Production environment with high availability and monitoring
10      variables:
11        region:
12          default: us-east-1
13          enum: [us-east-1, us-west-2, eu-west-1]
14          description: AWS region for the API server

Add parameter customizations

Customize parameter names and descriptions:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Parameter Customizations
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'user.search')].params[?(@.name == 'search_criteria')]
7    update:
8      x-fern-parameter-name: searchCriteria
9      description: |
10        Search criteria for finding users. Supports multiple filters:
11        - name: Partial name matching (case-insensitive)
12        - email: Exact or partial email matching
13        - role: Filter by user role
14        - status: Filter by account status
15        - dateRange: Filter by creation date range
16      schema:
17        type: object
18        properties:
19          name:
20            type: string
21            description: Partial name search (minimum 2 characters)
22          email:
23            type: string
24            description: Email search pattern
25          role:
26            type: string
27            enum: [user, admin, moderator]
28          status:
29            type: string
30            enum: [active, inactive, suspended]

Add error documentation

Enhance error handling information:

overlay.yml
1overlay: 1.0.0
2info:
3  title: Error Documentation
4  version: 1.0.0
5actions:
6  - target: $.methods[?(@.name == 'order.create')]
7    update:
8      errors:
9        - code: -32001
10          message: Insufficient inventory
11          data:
12            type: object
13            properties:
14              productId:
15                type: string
16              availableQuantity:
17                type: integer
18              requestedQuantity:
19                type: integer
20        - code: -32002
21          message: Payment authorization failed
22          data:
23            type: object
24            properties:
25              paymentMethod:
26                type: string
27              errorCode:
28                type: string
29              retryAllowed:
30                type: boolean

Multiple overlays

You can apply multiple overlay files in sequence:

generators.yml
1api:
2  specs:
3    - spec: openrpc.yml
4      overlays:
5        - base-overlay.yml
6        - sdk-overlay.yml
7        - docs-overlay.yml
8        - examples-overlay.yml

Environment-specific overlays

Use different overlays for different environments:

generators.yml
1groups:
2  production:
3    audiences: [public]
4    specs:
5      - spec: openrpc.yml
6        overlays:
7          - production-overlay.yml
8    generators:
9      - name: fernapi/fern-typescript-node-sdk
10        version: 0.8.8
11  internal:
12    audiences: [admin, internal]
13    specs:
14      - spec: openrpc.yml
15        overlays:
16          - internal-overlay.yml
17    generators:
18      - name: fernapi/fern-typescript-node-sdk
19        version: 0.8.8

Overlays are applied in order, allowing you to build up customizations incrementally while keeping your original OpenRPC specification clean and focused on the core API definition.