> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# What is an OpenRPC specification?

> Learn how to use OpenRPC specifications with Fern to document JSON-RPC APIs. Set up your fern folder and configure OpenRPC v1.3.2 or v1.2.6.

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](https://spec.open-rpc.org/) and [v1.2.6](https://github.com/open-rpc/spec/releases/tag/1.2.6).

Below is an example of an OpenRPC file:

**`openrpc.yml`**

```yaml 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`**

```json title="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`**

```yaml title="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
```

> Learn how to use OpenRPC specifications with Fern to document JSON-RPC APIs. Set up your fern folder and configure OpenRPC v1.3.2 or v1.2.6.