> 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 a Fern Definition?

> Fern Definition is a YAML format for API specifications. Define your REST API endpoints, data models, and errors in one source of truth.

Fern Definition isn't recommended for new customers and Fern isn't accepting feature requests for this format. It remains supported for existing users.

A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo,
inside of which describes your API requests, responses, models, paths, methods, errors, and authentication scheme.

## Fern Definition structure

To initialize a Fern Definition, simply run:

```sh
npm install -g fern-api
fern init
```

This will create the following folder structure in your project:

## Definition file

Each Fern Definition file may define:

* **[Custom types](/learn/api-definitions/ferndef/types)**. Use **custom types** to build your data model.
* **[Endpoints](/learn/api-definitions/ferndef/endpoints/overview)**. A **service** is a set of related REST endpoints.
* **[Errors](/learn/api-definitions/ferndef/errors)**. An **error** represents a failed (non-200) response from an endpoint.
* **[Imports](/learn/api-definitions/ferndef/imports)**. Use **imports** to share types across files.

**`imdb.yml`**

```yml imdb.yml maxLines=0
service:
  auth: false
  base-path: /movies
  endpoints:
    createMovie:
      docs: Add a movie to the database
      method: POST
      path: /create-movie
      request: CreateMovieRequest
      response: MovieId

    getMovie:
      method: GET
      path: /{movieId}
      path-parameters:
        movieId: MovieId
      response: Movie
      errors:
        - NotFoundError
        - UnauthorizedError

types:
  Movie:
    properties:
      title: string
      rating:
        type: double
        docs: The rating scale from one to five stars
      id:
        type: MovieId
        docs: The unique identifier for a movie

  CreateMovieRequest:
    properties:
      title: string
      rating: double

errors:
  NotFoundError:
    http:
      statusCode: 404
    type:
      properties:
        id: MovieId

  UnauthorizedError:
    http:
      statusCode: 401
```

## Why another format?

Google built gRPC. Amazon built Smithy. Facebook built GraphQL. Palantir built
Conjure. These companies rejected OpenAPI in favor of a more concise API Definition Language.

We built Fern to productize this design and make it accessible to all
software companies.

Despite being a different format for describing APIs, **you are never locked in to Fern.** It's easy to convert your
[Fern Definition to OpenAPI](/learn/api-definitions/ferndef/export-openapi).

> Fern Definition is a YAML format for API specifications. Define your REST API endpoints, data models, and errors in one source of truth.