OpenRPCExtensions

Use audiences to filter your API

Use x-fern-audiences to filter to relevant methods, parameters and schemas

View as Markdown

Audiences are a useful tool for segmenting your JSON-RPC API for different consumers. Common examples of audiences include public and beta.

Tag methods, parameters, and schemas with x-fern-audiences, then filter each output to those audiences: SDKs in generators.yml and your API Reference in docs.yml. Untagged elements are always included; if you don’t specify audiences, nothing is filtered.

Filter methods

Add x-fern-audiences to methods to control which methods are included for specific audiences:

openrpc.yml
1methods:
2  - name: public.getInfo
3    summary: Get public API information
4    description: Publicly available information about the API
5    x-fern-audiences:
6      - public
7    params: []
8    result:
9      name: info
10      schema:
11        $ref: '#/components/schemas/ApiInfo'
12  - name: admin.getUsers
13    summary: Get all users (admin only)
14    x-fern-audiences:
15      - admin
16    params:
17      - name: limit
18        schema:
19          type: integer
20          default: 100
21    result:
22      name: users
23      schema:
24        type: array
25        items:
26          $ref: '#/components/schemas/User'

Filter method parameters

You can filter specific parameters within methods:

openrpc.yml
1methods:
2  - name: user.create
3    summary: Create a new user
4    params:
5      - name: userData
6        schema:
7          type: object
8          properties:
9            email:
10              type: string
11              format: email
12            name:
13              type: string
14            adminNotes:
15              type: string
16              x-fern-audiences:
17                - admin
18            internalId:
19              type: string
20              x-fern-audiences:
21                - internal
22          required:
23            - email
24            - name
25        required: true
26    result:
27      name: user
28      schema:
29        $ref: '#/components/schemas/User'

Filter schemas

Filter entire schemas to different audiences:

openrpc.yml
1components:
2  schemas:
3    PublicUser:
4      type: object
5      x-fern-audiences:
6        - public
7      properties:
8        id:
9          type: string
10        name:
11          type: string
12        email:
13          type: string
14      required:
15        - id
16        - name
17        - email
18    AdminUser:
19      allOf:
20        - $ref: '#/components/schemas/PublicUser'
21        - type: object
22          x-fern-audiences:
23            - admin
24          properties:
25            role:
26              type: string
27            permissions:
28              type: array
29              items:
30                type: string
31            createdAt:
32              type: string
33              format: date-time
34            lastLoginAt:
35              type: string
36              format: date-time

Filter schema properties

You can filter individual properties within schemas:

openrpc.yml
1components:
2  schemas:
3    Order:
4      type: object
5      properties:
6        id:
7          type: string
8        amount:
9          type: number
10          x-fern-audiences:
11            - public
12        internalCost:
13          type: number
14          x-fern-audiences:
15            - internal
16        debugInfo:
17          type: object
18          x-fern-audiences:
19            - debug
20        customerInfo:
21          type: object
22          properties:
23            id:
24              type: string
25            email:
26              type: string
27              x-fern-audiences:
28                - admin

Filter error responses

Filter error information based on audience:

openrpc.yml
1methods:
2  - name: payment.process
3    summary: Process a payment
4    params:
5      - name: paymentData
6        schema:
7          $ref: '#/components/schemas/PaymentRequest'
8    errors:
9      - code: -32001
10        message: Payment failed
11        x-fern-audiences:
12          - public
13        data:
14          type: object
15          properties:
16            error:
17              type: string
18              const: "Payment could not be processed"
19      - code: -32001
20        message: Payment failed
21        x-fern-audiences:
22          - admin
23        data:
24          type: object
25          properties:
26            error:
27              type: string
28            errorCode:
29              type: string
30            gatewayResponse:
31              type: object
32            debugTrace:
33              type: string

Server-level filtering

Apply audience filtering at the server level:

openrpc.yml
1servers:
2  - name: public-api
3    url: https://api.example.com/rpc
4    x-fern-audiences:
5      - public
6    description: Public API server
7  - name: admin-api
8    url: https://admin-api.example.com/rpc
9    x-fern-audiences:
10      - admin
11    description: Admin API server with additional privileges

Conditional method availability

Use audiences to make methods available only in certain contexts:

openrpc.yml
1methods:
2  - name: debug.getSystemInfo
3    summary: Get system debug information
4    description: Internal system information for debugging
5    x-fern-audiences:
6      - debug
7    params: []
8    result:
9      name: systemInfo
10      schema:
11        type: object
12        additionalProperties: true
13  - name: beta.advancedSearch
14    summary: Advanced search functionality
15    x-fern-audiences:
16      - beta
17    params:
18      - name: query
19        schema:
20          type: object
21          properties:
22            text:
23              type: string
24            filters:
25              type: object
26              additionalProperties: true
27    result:
28      name: results
29      schema:
30        $ref: '#/components/schemas/SearchResults'
31  - name: internal.resetCache
32    summary: Reset internal caches
33    x-fern-audiences:
34      - internal
35    params:
36      - name: cacheType
37        schema:
38          type: string
39          enum: [user, product, session, all]
40    # Notification - no result expected

This allows you to create different views of the same JSON-RPC API for different types of consumers, ensuring each audience only sees the methods and data relevant to their use case.