SDK namespaces

The x-fern-sdk-namespace extension assigns a single schema or shared error response to a namespace. Use it when you need finer control than the spec-level namespace setting in generators.yml, which places an entire spec in one namespace.

Schemas

Add x-fern-sdk-namespace to a schema in components.schemas to generate that type in the given namespace. This overrides the spec’s namespace for that schema only, and avoids name collisions when multiple specs define a schema with the same name.

1
components:
2
  schemas:
3
    Plant:
4
      x-fern-sdk-namespace: garden
5
      type: object
6
      properties:
7
        id:
8
          type: string
9
        species:
10
          type: string

The generated SDK exposes the type as garden.Plant while other schemas in the spec stay in their default namespace.

Shared error responses

Add x-fern-sdk-namespace to a response object in components.responses to declare a shared error in a namespace. Fern only reads the extension on error responses when the spec enables settings.namespaced-errors in generators.yml. Without that setting, error responses are compared across the whole API by status code, so two specs that return different bodies for the same status code collapse the shared error’s body to unknown.

1
api:
2
  specs:
3
    - openapi: plants.yml
4
      settings:
5
        namespaced-errors: true

1
components:
2
  responses:
3
    TooManyRequests:
4
      x-fern-sdk-namespace: plants
5
      description: Rate limit exceeded
6
      content:
7
        application/json:
8
          schema:
9
            $ref: "#/components/schemas/PlantsRateLimitError"

The generated SDK exposes the error as plants.TooManyRequestsError. The extension is read from the response object only, not from the referenced body schema.