# 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, the YAML styles of its strings,
keys, sequences and mappings, and the layout of JSON arrays and objects. 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 the 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 a YAML input in YAML output.

Since 0.12.0, the `flow`, `block` and `best-fit` array and object styles also
lay out JSON output. `flow` writes an array or object on one line, with
everything inside it. `block` and `best-fit` write one element or member per
line. With `object: flow`, the whole document is on one line, because its root
is an object. With `original`, JSON output has one element or member per line,
even for the flow collections of a YAML input. JSON keeps no styles, so a
collection kept on one line would be spread over lines the next time the JSON is
formatted. `style_overrides` apply to YAML output only.

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
```
