Validate in your editor

Operations guide: configure, deploy and observe the gateway. What the feature does, product side: product guide; calling it: developer guide.

Have your editor complete flexway.yaml and underline a mistake as you type - an unknown key, a value outside the list, a malformed duration, a secret written in clear - rather than at start.

Flexway publishes a JSON Schema (2020-12) of its configuration, written from the gateway's model at every version: each key with its type, allowed values, default, the version that brought it, whether a reload applies it, and a description in English and in French. Key by key: configuration reference.

Steps

1. Add one line at the top of flexway.yaml - it is enough for the editors built on yaml-language-server (VS Code with Red Hat's YAML extension, Neovim, JetBrains, Helix):

# yaml-language-server: $schema=https://flexway.io/schema/v1/flexway.schema.json
version: 1
contracts:
  openapi: ./openapi.yaml
upstreams:
  orders:
    url: http://orders.internal:8080
    timeout: 3s

2. Offline, or to pin the schema of the version you deploy, write it from that version's image:

docker run --rm -v "$PWD:/out" -u "$(id -u)" ghcr.io/flexwiz/flexway:<version> schema --out /out
# /out/flexway.schema.json
# /out/contract-extensions.schema.json
# /out/policy-fragment.schema.json       (a fragment file, kind: PolicyFragment)

3. Point the line at the local file: # yaml-language-server: $schema=./flexway.schema.json.

Contract extensions

The x-flexway-* extensions of an OpenAPI or AsyncAPI document or of an A2A card are described by contract-extensions.schema.json (one definition per extension under $defs, with the places it is read at). Policies are in flexway.schema.json: the shape of config follows the definition's type (cors, rate-limit, quota, cache, header-inject, header-remove, rewrite-path, query-inject, query-remove, transform-body, redact, map-status, external-call).

Verify

Write timeouts: { conect: 5s } under server - the editor underlines conect (an unknown key); completion offers connect with its description and its default 5s. Write log_level: verbose under observability - the editor lists debug, info, warn, error, fatal.

Good to know