# Project structure

> Describes the Fern folder structure

Configuring fern starts with the `fern` folder, which contains your API definitions,
SDK generators, and your CLI version.

Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and [each generated SDK in its own separate repository](/sdks/overview/project-structure).

## Directory structure

When you run `fern init` (for the Fern Definition) or `fern init --spec-type path/to/spec` (for other specs), your fern folder is initialized with the following files:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" comment="Root-level config for entire Fern project" />

    <File name="generators.yml" comment="Declares APIs and configures SDK generation" />

    <Folder name="spec-folder" defaultOpen comment="definition, openapi, asyncapi, etc.">
      <File name="spec-file.yml" comment="API definition file" />
    </Folder>
  </Folder>
</Files>

## Core configuration files

<Note>
  Beyond the core files, you can optionally use an [overlays (OpenAPI)](/learn/api-definitions/openapi/overlays) or [overrides](/api-definitions/overview/overrides) file to customize your API definition without modifying the original spec.
</Note>

### `fern.config.json`

The `fern.config.json` file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds.

```json title="fern.config.json"
{
  "organization": "plant-catalog",
  "version": "3.47.0"
}
```

<Info>
  When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.
</Info>

### `generators.yml`

The `generators.yml` file is required for OpenAPI/AsyncAPI to declare your API specification location. This also enables [API Reference documentation](/learn/docs/api-references/generate-api-ref).

```yaml title="generators.yml"
api:
  specs:
    - openapi: ./openapi/openapi.yml
```

**For Fern Definition**, no `generators.yml` is needed to [generate API Reference docs](/learn/docs/api-references/generate-api-ref). Fern automatically detects your API by checking for a `definition/` directory.

For SDK generation, `generators.yml` is required for all specification formats. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/sdks/overview/project-structure#generatorsyml) for details.

### API definition file

For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information.

For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file.

## Multiple APIs

Fern supports two approaches for working with multiple API definitions:

1. **Separate SDKs for each API** - Each API generates its own independent set of SDK packages (e.g., `@company/user-api`, `@company/payments-api` or versioned like `@company/sdk-v1`, `@company/sdk-v2`)
2. **Combined SDKs from multiple APIs** - Multiple APIs merge into a single SDK package with optional namespacing (e.g., `client.users`, `client.payments` or versioned like `client.v1`, `client.v2`)

### Separate SDKs for each API

Use this approach when each API should generate its own independent set of SDKs. This works for both distinct APIs (e.g., `user-api` and `payments-api`) and versioned APIs where you want each version to be independently installable (e.g., `@company/sdk-v1`, `@company/sdk-v2`).

<Steps>
  <Step title="Place each API in its own directory">
    Place each API or version of an API into a separate subfolder of `fern/apis/`:

    <Tabs>
      <Tab title="Multiple distinct APIs">
        <Files>
          <Folder name="fern" defaultOpen>
            <File name="fern.config.json" />

            <Folder name="apis" defaultOpen>
              <Folder name="user-api" defaultOpen highlighted>
                <File name="generators.yml" comment="Configures user-api SDKs" />

                <File name="openapi.yml" />
              </Folder>

              <Folder name="payments-api" highlighted defaultOpen>
                <File name="generators.yml" comment="Configures payments-api SDKs" />

                <File name="openapi.yml" />
              </Folder>
            </Folder>
          </Folder>
        </Files>
      </Tab>

      <Tab title="Multiple versioned APIs">
        <Files>
          <Folder name="fern" defaultOpen>
            <File name="fern.config.json" />

            <Folder name="apis" defaultOpen>
              <Folder name="v1" highlighted defaultOpen>
                <File name="generators.yml" comment="Configures v1 SDKs" />

                <File name="openapi.yml" />
              </Folder>

              <Folder name="v2" highlighted defaultOpen>
                <File name="generators.yml" comment="Configures v2 SDKs" />

                <File name="openapi.yml" />
              </Folder>
            </Folder>
          </Folder>
        </Files>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure generators.yml for each API">
    Each API directory contains its own `generators.yml` file that references the spec in the same folder:

    ```yaml title="generators.yml"
    api:
      specs:
        - openapi: openapi.yml # Spec file in the same folder
    groups:
      # SDK generator configuration
    ```
  </Step>
</Steps>

### Combined SDKs from multiple APIs

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). You can merge up to five APIs into a single SDK on the Pro plan, and unlimited APIs on the Enterprise plan. To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

Use this approach when you want to merge multiple APIs into a single SDK package, with optional namespacing to organize them. This works for both distinct APIs and versioned APIs, though it increases package size as all APIs are bundled together.

For versioned APIs, namespacing lets you access different versions like `client.v1` and `client.v2` within the same package.

<Steps>
  <Step title="Place each API in separate subfolders">
    Place each API into a separate subfolder of `fern/apis/`:

    <Tabs>
      <Tab title="Multiple distinct APIs">
        <Files>
          <Folder name="fern" defaultOpen>
            <File name="fern.config.json" />

            <File name="generators.yml" highlighted comment="Single config for combined SDKs" />

            <Folder name="apis" defaultOpen>
              <Folder name="user-api">
                <File name="openapi.yml" />
              </Folder>

              <Folder name="payments-api">
                <File name="openapi.yml" />
              </Folder>
            </Folder>
          </Folder>
        </Files>
      </Tab>

      <Tab title="Multiple versioned APIs">
        <Files>
          <Folder name="fern" defaultOpen>
            <File name="fern.config.json" />

            <File name="generators.yml" highlighted comment="Single config for combined SDKs" />

            <Folder name="apis" defaultOpen>
              <Folder name="v1">
                <File name="openapi.yml" />
              </Folder>

              <Folder name="v2">
                <File name="openapi.yml" />
              </Folder>
            </Folder>
          </Folder>
        </Files>
      </Tab>
    </Tabs>
  </Step>

  <Step title="List all APIs in a single generators.yml">
    List all APIs in a single `generators.yml`:

    ```yaml title="generators.yml"
    api:
      specs:
        - openapi: user-api/openapi.yml
        - openapi: payments-api/openapi.yml
    groups:
      # SDK generator configuration
    ```
  </Step>

  <Step title="Add namespaces (optional)">
    Add namespaces to handle overlapping schema names between APIs or to organize different API versions:

    <Tabs>
      <Tab title="Distinct APIs">
        ```yaml title="generators.yml" {4}
        api:
          specs:
            - openapi: apis/user-api/openapi.yml
            - namespace: payments
              openapi: apis/payments-api/openapi.yml
        groups:
          # SDK generator configuration
        ```
      </Tab>

      <Tab title="Versioned APIs">
        List all API versions in a single `generators.yml` with namespaces:

        ```yaml title="generators.yml" {3, 5}
        api:
          specs:
            - namespace: v1
              openapi: apis/v1/openapi.yml
            - namespace: v2
              openapi: apis/v2/openapi.yml
        groups:
          # SDK generator configuration
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>