# Layout and YAML styles

Source: https://apigenie.pl/docs/reference/cli/format/styles
Part of the reference of [format](https://apigenie.pl/docs/reference/cli/format.md).
Its other pages: [Property order](https://apigenie.pl/docs/reference/cli/format/property-order.md), [AsyncAPI documents](https://apigenie.pl/docs/reference/cli/format/asyncapi.md), [Swagger 2.0 documents](https://apigenie.pl/docs/reference/cli/format/swagger.md), [Protobuf files](https://apigenie.pl/docs/reference/cli/format/protobuf.md), [GraphQL documents](https://apigenie.pl/docs/reference/cli/format/graphql.md).

The `openapi` section of `commands.format` sets how an OpenAPI document is written: its format, its
indentation, its line endings, where long values are folded, and the YAML styles of its strings,
keys, sequences and mappings. The `asyncapi` and `swagger` sections take `format`, `indent`,
`force_array_indent` and `style` with the same values; the [layout](#layout) keys and
`style_overrides` are for OpenAPI documents.

## format

The output format: `yaml`, `json` or `original`. Without it, or with
`original`, every file keeps its own format. With another format, formatting
`api.json` in place writes `api.yaml` next to it.

## indent

The number of spaces of one level of indentation, from 2 to 9. The default is 2.

## force_array_indent

Indents the elements of YAML block sequences under their key (`true`), instead
of writing them at the level of the key (`false`, the default).

## Layout

The lines of the output:

| Key               | Values         | Default    | Effect                                                                                       |
| ----------------- | -------------- | ---------- | -------------------------------------------------------------------------------------------- |
| `line_width`      | 0 to 100000    | 0          | Folds long YAML scalars at this width. 0 never folds them.                                   |
| `newline`         | `lf`, `crlf`   | `lf`       | The line endings of the output, YAML and JSON.                                               |
| `final_newline`   | `true`, `false`| the writer's | Whether the output ends with a line break. Without it, YAML and indented JSON end with one. |
| `document_marker` | `true`, `false`| `false`    | Starts YAML documents with `---`.                                                            |

## style

The styles of YAML values: `string` (`original`, `best-fit`, `plain`,
`single-quoted`, `double-quoted`, `literal`, `folded`), `array` and `object`
(`original`, `best-fit`, `block`, `flow`) and `key` (`original`, `best-fit`,
`plain`, `single-quoted`, `double-quoted`). The default is `original` for all
of them, which keeps the styles of the input.


With the `best-fit` string and key styles, strings that YAML 1.1 parsers (such
as PyYAML, SnakeYAML or go-yaml v2) would read as booleans, numbers or merge
keys are written in double quotes: `yes`, `No`, `on`, `OFF`, `y`, `n`, `0755`,
`0b101`, `1_000`, `1:30`, `<<` and the like. The `original` style keeps the
quoting of the source.

## style_overrides

A list of rules giving the values of some fields their own YAML styles. A rule
selects values by `fields` (the names of their fields), by `objects` (the
[kinds](/docs/reference/cli/format/property-order#objects) of the objects holding them), or by both, and sets one
or more of `string`, `array` and `object`, with the values of
[style](#style). A rule without `objects` applies to the fields of OpenAPI
objects only, never to those inside example values or extensions. When several
rules match a value, the later ones win.

**Example** - Literal descriptions, and flow sequences for the tags of
operations and the required properties of schemas

```yaml
commands:
  format:
    openapi:
      style_overrides:
        - fields: [description]
          string: literal
        - fields: [tags]
          objects: [operation]
          array: flow
        - fields: [required]
          objects: [schema]
          array: flow
```