# 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.

<Warning title="Enterprise feature">
  This feature is available only for the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

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:

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

<Info>
   Considering options to generate an OpenRPC spec? Get live support 

  [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email)

   
</Info>

<Steps>
  <Step title="Create your fern directory">
    Create a `fern/` folder in your project root.

    ```
    fern/
    ```
  </Step>

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

  <Step title="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:

    ```json title="fern.config.json"
    {
        "organization": "your-organization",
        "version": "3.57.0"
    }
    ```

    ```
    fern/
      ├─ fern.config.json
      └─ openrpc/
        └─ openrpc.yml
    ```
  </Step>

  <Step title="Create a `generators.yml` file">
    Create a `generators.yml` file in your fern directory and add a reference to your OpenRPC spec:

    ```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
    ```
  </Step>
</Steps>