What is an OpenRPC specification?

The OpenRPC Specification is a framework used by developers to document JSON-RPC APIs. The specification is written in JSON or YAML and contains all of your methods, parameters, schemas, and server configurations. Fern is compatible with OpenRPC specification v1.3.2 and v1.2.6.

Below is an example of an OpenRPC file:

openrpc.yml

openrpc: 1.3.2
info:
  title: Calculator API
  version: 1.0.0
  description: |
    A simple calculator API that performs basic arithmetic operations
    using JSON-RPC 2.0 protocol.
servers:
  - name: production
    url: https://api.calculator.com/rpc
    description: Production JSON-RPC server
  - name: development  
    url: http://localhost:8080/rpc
    description: Development server
methods:
  - name: add
    summary: Add two numbers
    description: Performs addition of two numeric values
    params:
      - name: a
        schema:
          type: number
        required: true
        description: First number to add
      - name: b
        schema:
          type: number
        required: true
        description: Second number to add
    result:
      name: sum
      schema:
        type: number
      description: The sum of the two numbers
    examples:
      - name: AddExample
        description: Example of adding two numbers
        params:
          a: 5
          b: 3
        result: 8
  - name: divide
    summary: Divide two numbers
    description: Performs division of two numeric values
    params:
      - name: dividend
        schema:
          type: number
        required: true
        description: Number to be divided
      - name: divisor
        schema:
          type: number
        required: true
        description: Number to divide by
    result:
      name: quotient
      schema:
        type: number
      description: The result of the division
    errors:
      - code: -32602
        message: Division by zero
        data:
          type: object
          properties:
            error:
              type: string
              const: "Cannot divide by zero"
    examples:
      - name: DivideExample
        description: Example of dividing two numbers
        params:
          dividend: 10
          divisor: 2
        result: 5
  - name: notify_calculation
    summary: Notify about calculation
    description: Send a notification about a completed calculation (no response expected)
    params:
      - name: operation
        schema:
          type: string
          enum: [add, subtract, multiply, divide]
        required: true
      - name: result
        schema:
          type: number
        required: true
      - name: timestamp
        schema:
          type: string
          format: date-time
        required: true
components:
  schemas:
    CalculationRequest:
      type: object
      properties:
        operation:
          type: string
          enum: [add, subtract, multiply, divide]
        operands:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        precision:
          type: integer
          minimum: 0
          maximum: 10
          default: 2
      required:
        - operation
        - operands
    CalculationResult:
      type: object
      properties:
        result:
          type: number
        operation:
          type: string
        timestamp:
          type: string
          format: date-time
      required:
        - result
        - operation
        - timestamp

Set up your fern folder

Create your fern directory

Create a fern/ folder in your project root.

fern/

Add your OpenRPC specification

Add your OpenRPC spec to the fern directory. You can place it in a subfolder called openrpc or directly in the fern directory.

fern/
  └─ openrpc/
    └─ openrpc.yml

Create a `fern.config.json` file

Add a fern.config.json file in your fern directory that lists your organization and the current version of the Fern CLI:

fern.config.json

{
    "organization": "your-organization",
    "version": "null"
}

fern/
  ├─ fern.config.json
  └─ openrpc/
    └─ openrpc.yml

Create a `generators.yml` file

Create a generators.yml file in your fern directory and add a reference to your OpenRPC spec:

generators.yml

# Your API definition
api: 
  specs: 
    - openrpc: ./openrpc/openrpc.yml
groups:
  external:
    generators:
      # Your generator configurations here

Your final directory structure:

fern/
  ├─ fern.config.json
  ├─ generators.yml
  └─ openrpc/
    └─ openrpc.yml