# overlay

Source: https://apigenie.pl/techdocs/reference/cli-overlay

Applies [OpenAPI Overlays](https://spec.openapis.org/overlay/latest.html) to an
OpenAPI schema, or to any JSON or YAML document.

## Usage

```sh
apigenie overlay [OPTIONS] --overlay OVERLAY [--overlay OVERLAY ...] INPUT
apigenie overlay --validate --overlay OVERLAY [--overlay OVERLAY ...]
```

## Description

An overlay is a JSON or YAML document with an ordered list of actions. Each
action selects nodes of the input with a JSONPath query (its `target`) and
changes them. The overlays are applied in the order of the `--overlay`
options, and the actions of an overlay in their order, each to the result of
the previous one. The result is written to the standard output, or to the file
of `--output`, in the format of the input unless `--format` says otherwise.
YAML comments of the input and of the overlays are kept, unless
`--strip-comments` is given. Strings that YAML 1.1 parsers would read as
booleans or numbers, such as `yes`, `off`, `0755` or `1:30`, are written in
double quotes.

Overlays of versions 1.0, 1.1 and 1.2 of the specification are supported:
`copy` actions need version 1.1 or later, `$self` and reusable actions
(`components.actions`, referenced from the actions with `$ref`) version 1.2.
The `extends` property is informative only: the input is always `INPUT`.

To generate code from an overlaid document, there is no need for a separate step:
`apigenie-generator` takes the overlays itself, with `--overlay`, and reports problems in the
values they set at their lines in the overlay; see
[overlays](/techdocs/reference/cli-generate#overlays).

For example, with `public.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: Public API
  version: 1.0.0
actions:
  - target: $.info
    update:
      x-audience: public
  - target: $.servers[?@.description == 'Dev']
    remove: true
  - target: $.paths.*.*.parameters[?@.name == 'debug']
    remove: true
```

```sh
apigenie overlay --overlay public.overlay.yaml openapi.yaml -o public.yaml
```

### Actions

For every node the target selects:

- with `remove: true`, the node is removed from its object or array;
- otherwise the value of `update` (or, from version 1.1, a copy of the one node
  that the JSONPath query of `copy` selects) is merged into the node:
  - into an object, the value must be an object. Its members are added to the
    object, after the existing ones. When the object already has a member, a
    primitive value replaces a primitive value, an array is appended to an
    array, and an object is merged into an object the same way. Other
    combinations are errors;
  - to an array, an array is appended element by element, and any other value
    is appended as one element;
  - a primitive value (string, number, boolean or null) is replaced by the
    value, which must be a primitive value.

An action without `update`, `copy` and `remove` changes nothing. The nodes
selected by an action must all be objects, all arrays or all primitive
values. An action that selects nothing changes nothing: the command warns about
it on the standard error, and goes on.

### JSONPath

Targets are JSONPath queries as defined by
[RFC 9535](https://www.rfc-editor.org/rfc/rfc9535): names (`.name` or
`['name']`), wildcards (`*`), indexes and slices (`[0]`, `[-1]`, `[1:3]`),
descendants (`..`), unions (`[0, 2]`) and filters (`[?@.in == 'query']`), with
the comparisons, `&&`, `||`, `!` and the functions `length()`, `count()`,
`match()`, `search()` and `value()`. As an extension, member names written with
a dot may contain `-`, as in `$.paths.*.get.x-internal`.

## Options

| Option                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `--overlay OVERLAY`     | Path to an overlay. Required, can be repeated.          |
| `-o`, `--output OUTPUT` | Path to the result. Defaults to the standard output.   |
| `--format FORMAT`       | Format of the result, `json` or `yaml`.                |
| `--validate`            | Only checks the overlays.                              |
| `--strip-comments`      | Drops the comments of the result.                      |

### --overlay OVERLAY

Path to an overlay, in JSON or YAML. The option can be repeated: the overlays
are applied in the given order. When an overlay is invalid, its issues are
listed and nothing is written.

### --output OUTPUT

Path of the file to write the result to. Without it, the result is written to
the standard output.

### --format FORMAT

Format of the result: `json` or `yaml`. Defaults to the format of the input.

### --strip-comments

Drops the YAML comments of the input and of the overlays from the result,
instead of keeping them.

### --validate

Checks the overlays against the specification of their version, without
applying them: unknown properties, values of the wrong type, invalid JSONPath
queries, unresolved reusable action references and duplicate actions are
reported with their line and column. `INPUT` is not needed. The command exits
with a non-zero status when an overlay has issues.

```sh
apigenie overlay --validate --overlay public.overlay.yaml
```