apigenieoverlay

overlay

Applies OpenAPI Overlays to an OpenAPI schema, or to any JSON or YAML document.

Usage

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.

For example, with public.overlay.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
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: 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.

apigenie overlay --validate --overlay public.overlay.yaml