@flagctl/yaml

YAML document schemas, parsers, and diff utilities for flagctl.

JSON Schema (editor autocomplete & validation)

This package ships a public JSON Schema for every flagctl document kind under dist-schema/. Editors that speak the YAML Language Server protocol (VSCode, Neovim, etc.) can use these for autocomplete, hover docs, and inline validation.

Per-file (modeline)

Add this comment at the top of any flagctl YAML file:

# yaml-language-server: $schema=https://flagctl.dev/schemas/v1/flag.schema.json
apiVersion: flagctl/v1
kind: Flag
metadata:
  key: example

Swap flag.schema.json for environment.schema.json, policy.schema.json, team.schema.json, or the combined flagctl-v1.schema.json as needed.

Repo-wide (.vscode/settings.json)

{
  "yaml.schemas": {
    "https://flagctl.dev/schemas/v1/flag.schema.json": "flagctl/flags/**/*.yaml",
    "https://flagctl.dev/schemas/v1/environment.schema.json": "flagctl/environments/**/*.yaml",
    "https://flagctl.dev/schemas/v1/policy.schema.json": "flagctl/policies/**/*.yaml",
    "https://flagctl.dev/schemas/v1/team.schema.json": "flagctl/teams/**/*.yaml"
  }
}

Regenerating the schema

The JSON Schema is derived from the zod schema in src/schema.ts:

pnpm --filter @flagctl/yaml generate-schema

It runs automatically as part of pnpm --filter @flagctl/yaml build.