Config File Validator

Single cross-platform CLI tool to validate different configuration file types

About

Config File Validator is a cross-platform CLI tool that validates configuration files in your project. Catch syntax errors, schema violations, and misconfigurations across all your config files — with one tool.

Single binary, zero dependencies — no runtimes, no package managers, just one executable
15 file formats — JSON, JSONC, YAML, TOML, XML, HCL, INI, HOCON, ENV, CSV, Properties, EDITORCONFIG, PList, SARIF, and TOON
Syntax + schema validation — validates structure with JSON Schema and XSD, with automatic SchemaStore integration
CI/CD ready — JSON, JUnit, and SARIF output for GitHub Actions, GitLab CI, Jenkins, and more
Configurable — project-level .cfv.toml config files, glob patterns, schema mappings, and environment variables
Usable as a Go library — embed validation in your own tools with the cli package

Supported File Types

Format	Syntax	Schema
Apple PList XML	✅	❌
CSV	✅	❌
EDITORCONFIG	✅	❌
ENV	✅	❌
HCL	✅	❌
HOCON	✅	❌
INI	✅	❌
JSON	✅	✅
JSONC	✅	✅
Properties	✅	❌
SARIF	✅	✅
TOML	✅	✅
TOON	✅	✅
XML	✅	✅
YAML	✅	✅

XML files with inline DTD declarations (<!DOCTYPE>) are automatically validated against the DTD during syntax checking.

Known Files

The validator automatically recognizes common configuration files by filename, even without a standard extension. This means files like .babelrc, .gitconfig, Pipfile, and pom.xml are validated without any configuration.

Known filenames are sourced from GitHub Linguist and updated automatically. Examples:

Type	Known Files
JSON	`.arcconfig`, `.watchmanconfig`, `composer.lock`, `bun.lock`, `deno.lock`, `flake.lock`
JSONC	`.babelrc`, `.swcrc`, `.jshintrc`, `tsconfig.json`, `jsconfig.json`, `.eslintrc.json`
YAML	`.clang-format`, `.clang-tidy`, `.clangd`, `.gemrc`
TOML	`Pipfile`, `Cargo.lock`, `poetry.lock`, `uv.lock`, `pdm.lock`
XML	`pom.xml`, `build.xml`, `ant.xml`, `.classpath`, `.project`
INI	`.gitconfig`, `.gitmodules`, `.npmrc`, `.pylintrc`, `.flake8`, `.curlrc`, `.nanorc`

Known files take priority over extension matching. For example, tsconfig.json is validated as JSONC (not strict JSON) because it’s a known JSONC file.

Use --type-map to override the automatic detection for any file:

# Force tsconfig.json to be validated as strict JSON
validator --type-map="**/tsconfig.json:json" .

### JSON vs JSONC

Files with the `.json` extension are validated as **strict JSON** — no comments, no trailing commas. Files with the `.jsonc` extension are validated as **JSONC**, which allows `//` line comments, `/* */` block comments, and trailing commas.

Many common `.json` files actually support JSONC syntax. The validator automatically detects these by filename and validates them as JSONC — no configuration needed:

`tsconfig.json`, `jsconfig.json`, `.eslintrc.json`, `.devcontainer.json`, `devcontainer.json`, `.babelrc`, `.jshintrc`, `.jslintrc`, `.jscsrc`, `.swcrc`, `tslint.json`, `api-extractor.json`, `language-configuration.json`, `.oxlintrc.json`

For other `.json` files that use JSONC syntax (e.g., VS Code settings), map them to the `jsonc` type using `--type-map` or `.cfv.toml`:

```shell
validator --type-map="**/.vscode/*.json:jsonc" .

Or in .cfv.toml:

[type-map]
"**/.vscode/*.json" = "jsonc"

JSON and JSONC are treated as a family — --file-types=json includes JSONC files, and --exclude-file-types=json excludes both JSON and JSONC files.

Demo

Installation

There are several options to install the config file validator tool.

Binary Releases

Download and unpack from https://github.com/Boeing/config-file-validator/releases

Package Managers

Homebrew

brew install config-file-validator

MacPorts

sudo port install config-file-validator

Aqua

aqua g -i Boeing/config-file-validator

Winget

winget install Boeing.config-file-validator

Scoop

scoop install config-file-validator

Arch Linux

We maintain and release an AUR package for the config-file-validator

git clone https://aur.archlinux.org/config-file-validator.git
cd config-file-validator
makepkg -si

`go install`

If you have a go environment on your desktop you can use go install to install the validator executable. The validator executable will be installed to the directory named by the GOBIN environment variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH environment variable is not set.

go install github.com/Boeing/config-file-validator/v2/cmd/validator@latest

GitHub Action

A GitHub Action is available to run the config-file-validator as part of your CI/CD pipeline. It posts validation results as PR comments with inline annotations on the affected files and lines.

- uses: Boeing/validate-configs-action@v2.0.0

See the validate-configs-action repository for full usage and configuration options.

Pre-commit Hook

The config-file-validator can be used as a pre-commit hook to validate config files before every commit.

repos:
  - repo: https://github.com/Boeing/config-file-validator
    rev: v2.1.0
    hooks:
      - id: config-file-validator

Two hooks are available:

config-file-validator — validates only changed config files (fast, for local development)
config-file-validator-full — validates all config files in the repo (for CI)

To pass additional flags (e.g., --schemastore):

hooks:
  - id: config-file-validator
    args: ['--schemastore']

Usage

Usage: validator [OPTIONS] [<search_path>...]

positional arguments:
    search_path: The search path on the filesystem for configuration files. Defaults to the current working directory if no search_path provided. Use "-" to read from stdin (requires --file-types).

Schema validation runs automatically when a file declares a schema:
  JSON:  {"$schema": "schema.json", ...}
  YAML:  # yaml-language-server: $schema=schema.json
  TOML:  "$schema" = "schema.json"
  TOON:  "$schema": schema.json
  XML:   xsi:noNamespaceSchemaLocation="schema.xsd"
  XML:   <!DOCTYPE> with inline DTD (validated during syntax check)

optional flags:
  -depth int
        Depth of recursion for the provided search paths. Set depth to 0 to disable recursive path traversal
  -exclude-dirs string
        Subdirectories to exclude when searching for configuration files
  -exclude-file-types string
        A comma separated list of file types to ignore
  -file-types string
        A comma separated list of file types to validate
  -globbing
        If globbing flag is set, check for glob patterns in the arguments.
  -groupby string
        Group output by filetype, directory, pass-fail, error-type. Supported for Standard and JSON reports
  -no-schema
        Disable all schema validation. Only syntax is checked.
        Cannot be used with --require-schema, --schema-map, or --schemastore.
  -quiet
        If quiet flag is set. It doesn't print any output to stdout.
  -reporter value
        Report format and optional output path. Format: <type>:<path> Supported: standard, json, junit, sarif (default: standard)
  -require-schema
        Fail validation if a file supports schema validation but does not declare a schema.
        Supported types: JSON ($schema property), YAML (yaml-language-server comment),
        TOML ($schema key), TOON ("$schema" key), XML (xsi:noNamespaceSchemaLocation).
        Other file types (INI, CSV, ENV, HCL, HOCON, Properties, PList, EditorConfig) are not affected.
        Cannot be used with --no-schema.
  -schema-map value
        Map a glob pattern to a schema file for validation.
        Format: <pattern>:<schema_path>
        Use JSON Schema (.json) for JSON, YAML, TOML, and TOON files.
        Use XSD (.xsd) for XML files. Paths are relative to the current directory.
        Multiple mappings can be specified.
        Examples:
          --schema-map="**/package.json:schemas/package.schema.json"
          --schema-map="**/config.xml:schemas/config.xsd"
  -schemastore
        Enable automatic schema lookup by filename using the SchemaStore catalog.
        Schemas are fetched remotely and cached in ~/.cache/cfv/schemas/ (24h TTL).
        Document-declared schemas and --schema-map take priority over SchemaStore.
  -schemastore-path string
        Path to a local SchemaStore clone for automatic schema lookup by filename.
        Implies --schemastore. Use for air-gapped environments.
        Download with: git clone --depth=1 https://github.com/SchemaStore/schemastore.git
  -config string
        Path to a .cfv.toml configuration file.
        If not specified, searches for .cfv.toml in the current and parent directories.
  -no-config
        Disable automatic discovery of .cfv.toml configuration files.
  -type-map value
        Map a glob pattern to a file type. Format: <pattern>:<type> Example: --type-map="**/inventory:ini"
  -version
        Version prints the release version of validator

Configuration File

The validator supports a .cfv.toml configuration file for setting project-level defaults. On startup, the validator searches for .cfv.toml in the current directory and walks up parent directories. Use --config=<path> to specify a file explicitly, or --no-config to disable auto-discovery.

The config file is validated against a built-in schema — typos and invalid values are caught immediately.

Precedence order (highest to lowest):

CLI flags
Configuration file (.cfv.toml)
Environment variables (CFV_*)
Built-in defaults

Example .cfv.toml:

exclude-dirs = ["node_modules", ".git", "vendor"]
exclude-file-types = ["csv"]
depth = 3
quiet = false
schemastore = true
require-schema = false
reporter = ["standard"]
groupby = ["filetype", "pass-fail"]

[schema-map]
"**/package.json" = "schemas/package.schema.json"
"**/config.xml" = "schemas/config.xsd"

[type-map]
"**/inventory" = "ini"
"**/*.cfg" = "json"

[validators.csv]
delimiter = ";"
comment = "#"

Supported keys:

Key	Type	Equivalent Flag
`exclude-dirs`	array of strings	`--exclude-dirs`
`exclude-file-types`	array of strings	`--exclude-file-types`
`file-types`	array of strings	`--file-types`
`depth`	integer (≥ 0)	`--depth`
`reporter`	array of strings	`--reporter`
`groupby`	array of strings	`--groupby`
`quiet`	boolean	`--quiet`
`require-schema`	boolean	`--require-schema`
`no-schema`	boolean	`--no-schema`
`schemastore`	boolean	`--schemastore`
`schemastore-path`	string	`--schemastore-path`
`globbing`	boolean	`--globbing`
`schema-map`	table (pattern = path)	`--schema-map`
`type-map`	table (pattern = type)	`--type-map`
`validators`	table	Per-validator options (see below)

Validator options:

Key	Type	Default	Description
`validators.csv.delimiter`	string	`","`	Field delimiter. Use `"\t"` for tab.
`validators.csv.comment`	string	(none)	Lines starting with this character are ignored.
`validators.csv.lazy-quotes`	boolean	`false`	Allow quotes in unquoted fields.
`validators.json.forbid-duplicate-keys`	boolean	`false`	Report duplicate keys in objects as errors.
`validators.ini.forbid-duplicate-keys`	boolean	`false`	Report duplicate keys within the same section as errors.

YAML duplicate keys are always rejected (enforced by the YAML parser).

Environment Variables

The config-file-validator supports setting options via environment variables. If both command-line flags and environment variables are set, the command-line flags will take precedence. The supported environment variables are as follows:

Environment Variable	Equivalent Flag
`CFV_DEPTH`	`-depth`
`CFV_EXCLUDE_DIRS`	`-exclude-dirs`
`CFV_EXCLUDE_FILE_TYPES`	`-exclude-file-types`
`CFV_FILE_TYPES`	`-file-types`
`CFV_REPORTER`	`-reporter`
`CFV_GROUPBY`	`-groupby`
`CFV_QUIET`	`-quiet`
`CFV_REQUIRE_SCHEMA`	`-require-schema`
`CFV_NO_SCHEMA`	`-no-schema`
`CFV_SCHEMASTORE`	`-schemastore`
`CFV_SCHEMASTORE_PATH`	`-schemastore-path`
`CFV_GLOBBING`	`-globbing`

Examples

Standard Run

If the search path is omitted it will search the current directory

validator /path/to/search

Multiple search paths

Multiple search paths are supported, and the results will be merged into a single report

validator /path/to/search /another/path/to/search

Exclude directories

Exclude subdirectories in the search path

validator --exclude-dirs=/path/to/search/tests /path/to/search

Exclude file types

Exclude file types in the search path. JSON and JSONC are treated as a family — excluding one excludes both. Similarly, excluding yaml also excludes yml.

validator --exclude-file-types=json /path/to/search

Note: --exclude-file-types filters by file extension. Extensionless known files (like .gitconfig or .babelrc) are not affected by this flag. Use --type-map or .cfv.toml for fine-grained control.

Include only specific file types

Validate only the specified file types. Cannot be used together with --exclude-file-types.

validator --file-types=json,yaml /path/to/search

Customize recursion depth

By default there is no recursion limit. If desired, the recursion depth can be set to an integer value. If depth is set to 0 recursion will be disabled and only the files in the search path will be validated.

validator --depth=0 /path/to/search

Customize report output

You can customize the report output and save the results to a file (default name is result.{extension}). The available report types are standard, junit, json, and sarif. You can specify multiple report types by chaining the --reporter flags.

You can specify a path to an output file for any reporter by appending :<path> to the name of the reporter. Providing an output file is optional and the results will be printed to stdout by default. To explicitly direct the output to stdout, use :- as the file path.

validator --reporter=json:- /path/to/search
validator --reporter=json:output.json --reporter=standard /path/to/search

Group report output

Group the report output by file type, directory, pass-fail, or error-type. Supports one or more groupings.

validator -groupby filetype

Multiple groups

validator -groupby directory,pass-fail

Output results to a file

Output report results to a file (default name is result.{extension}). Must provide reporter flag with a supported extension format. Available options are junit and json. If an existing directory is provided, create a file named default name in the given directory. If a file name is provided, create a file named the given name at the current working directory.

validator --reporter=json --output=/path/to/dir

Suppress output

Passing the --quiet flag suppresses all output to stdout. If there are invalid config files the validator tool will exit with 1. Any errors in execution such as an invalid path will still be displayed.

validator --quiet /path/to/search

Read from stdin

Use - as the search path to read from stdin. Requires --file-types to specify exactly one file type.

echo '{"key": "value"}' | validator --file-types=json -
cat config.yaml | validator --file-types=yaml -
curl -s https://example.com/config.json | validator --file-types=json -

Exit codes

The validator uses the following exit codes:

Code	Meaning
`0`	All files are valid
`1`	One or more validation errors (syntax or schema)
`2`	Runtime or configuration error (invalid flags, unreadable files, bad config)

Schema validation

Schema validation runs automatically for file types that support it. Files without a schema declaration pass with syntax validation only. The document is converted to JSON internally and validated against the referenced JSON Schema.

Use --require-schema to fail validation for files that support schema validation but don't declare a schema:

validator --require-schema /path/to/search

Declaring a schema

Each file type uses a different convention to declare its schema:

JSON — Add a $schema property at the top level:

{
  "$schema": "https://json.schemastore.org/package.json",
  "name": "my-package",
  "version": "1.0.0"
}

YAML — Add a yaml-language-server modeline comment before any content:

# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest

TOML — Add a $schema key at the top level:

"$schema" = "https://json.schemastore.org/pyproject.json"

[project]
name = "my-project"
version = "1.0.0"

TOON — Add a quoted "$schema" key at the top level:

"$schema": https://example.com/schema.json
host: localhost
port: 5432

SARIF — Schema validation is built-in per SARIF version (2.1.0 and 2.2). No declaration needed.

XML — Add an xsi:noNamespaceSchemaLocation attribute on the root element:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="config.xsd">
  <host>db.example.com</host>
  <port>5432</port>
</config>

XML schemas use XSD (XML Schema Definition) files rather than JSON Schema.

Schema URLs can be absolute (https://...), absolute file paths, or relative paths (resolved from the document's directory).

Automatic schema lookup with SchemaStore

SchemaStore is a community-maintained collection of JSON Schemas for hundreds of common configuration files — including package.json, tsconfig.json, .eslintrc.json, GitHub Actions workflows, pyproject.toml, and many more.

With the --schemastore flag, the validator automatically matches files by name against the SchemaStore catalog and validates them against the corresponding schema — no $schema declaration needed in your files.

Usage:

# Automatic schema lookup — schemas are fetched remotely and cached locally
validator --schemastore /path/to/project

For example, if your project contains a package.json, tsconfig.json, and .github/workflows/ci.yml, the validator will automatically find and apply the correct schema for each file without any configuration.

Schemas are cached in ~/.cache/cfv/schemas/ (or $XDG_CACHE_HOME/cfv/schemas/) with a 24-hour TTL, so subsequent runs don't require network access.

Air-gapped / offline environments:

For environments without internet access, use a local SchemaStore clone:

# Clone the SchemaStore catalog (only needed once)
git clone --depth=1 https://github.com/SchemaStore/schemastore.git

# Validate using the local clone
validator --schemastore-path=./schemastore /path/to/project

--schemastore-path implies --schemastore — you don't need to pass both.

Priority order: When multiple schema sources are available, the validator uses this precedence:

Schema declared in the document ($schema, yaml-language-server, xsi:noNamespaceSchemaLocation)
--schema-map patterns
--schemastore catalog lookup

This means document-level declarations always win, and --schemastore acts as a safety net for files that don't declare their own schema.

External schema mapping

Use --schema-map to apply a schema to files matching a glob pattern. This is useful when you can't or don't want to add schema declarations to the files themselves.

# Apply a JSON Schema to all package.json files
validator --schema-map="**/package.json:schemas/package.schema.json" /path/to/project

# Apply an XSD to XML config files
validator --schema-map="**/config.xml:schemas/config.xsd" /path/to/project

# Multiple mappings
validator --schema-map="**/package.json:schemas/pkg.json" \
          --schema-map="**/*.xml:schemas/config.xsd" /path/to/project

Use JSON Schema (.json) for JSON, YAML, TOML, and TOON files. Use XSD (.xsd) for XML files. Paths are relative to the current working directory.

Map file types with glob patterns

Use the --type-map flag to map files matching a glob pattern to a specific file type. This is useful for files without extensions or with non-standard extensions. Multiple mappings can be specified.

# Treat all files named "inventory" as ini
validator --type-map="**/inventory:ini" /path/to/search

# Map all files in a configs directory as properties
validator --type-map="**/configs/*:properties" /path/to/search

# Multiple mappings
validator --type-map="**/inventory:ini" --type-map="**/*.cfg:json" /path/to/search

Search files using a glob pattern

Use the -globbing flag to validate files matching a specified pattern. Include the pattern as a positional argument in double quotes. Multiple glob patterns and direct file paths are supported. If invalid config files are detected, the validator tool exits with code 1, and errors (e.g., invalid patterns) are displayed.

Learn more about glob patterns

# Validate all `.json` files in a directory
validator -globbing "/path/to/files/*.json"

# Recursively validate all `.json` files in subdirectories
validator -globbing "/path/to/files/**/*.json"

# Mix glob patterns and paths
validator -globbing "/path/*.json" /path/to/search

Calling the config-file-validator programmatically

The config-file-validator can be used as a Go library. See the Go API documentation for examples including custom search paths, reporters, schema validation, and all configuration options.

package main

import (
	"os"
	"log"

	"github.com/Boeing/config-file-validator/v2/pkg/cli"
)

func main() {
	cfv := cli.Init()
	exitStatus, err := cfv.Run()
	if err != nil {
	  log.Printf("Errors occurred during execution: %v", err)
	}
	os.Exit(exitStatus)
}

Build

The project can be downloaded and built from source using an environment with Go 1.26+ installed. After a successful build, the binary can be moved to a location on your operating system PATH.

macOS

Build

CGO_ENABLED=0 \
GOOS=darwin \
GOARCH=arm64 \ # for Intel use amd64
go build \
-ldflags='-w -s -extldflags "-static"' \
-tags netgo \
-o validator \
cmd/validator/validator.go

Install

cp ./validator /usr/local/bin/
chmod +x /usr/local/bin/validator

Linux

Build

CGO_ENABLED=0 \
GOOS=linux \
GOARCH=amd64 \
go build \
-ldflags='-w -s -extldflags "-static"' \
-tags netgo \
-o validator \
cmd/validator/validator.go

Install

cp ./validator /usr/local/bin/
chmod +x /usr/local/bin/validator

Windows

Build

$env:CGO_ENABLED = '0'; `
$env:GOOS = 'windows'; `
$env:GOARCH = 'amd64'; `
go build `
-ldflags='-w -s -extldflags "-static"' `
-tags netgo `
-o validator.exe `
cmd/validator/validator.go

Install

The below script will install the config-file-validator as a user to Local App Data:

$install = Join-Path $env:LOCALAPPDATA 'Programs\validator'; `
New-Item -Path $install -ItemType Directory -Force | Out-Null; `
Copy-Item -Path .\validator.exe -Destination $install -Force; `
$up = [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::User); `
if (-not ($up.Split(';') -contains $install)) { `
  $new = if ([string]::IsNullOrEmpty($up)) { $install } else { $up + ';' + $install }; `
  [Environment]::SetEnvironmentVariable('Path', $new, [EnvironmentVariableTarget]::User); `
  Write-Host "Added $install to User PATH. Open a new shell to pick up the change."; `
} else { `
  Write-Host "$install is already in the User PATH."; `
}

Docker

You can also use the provided Dockerfile to build the config file validator tool as a container

docker build . -t config-file-validator:latest

Contributors

Contributing

We welcome contributions! Please refer to our contributing guide

License

The Config File Validator is released under the Apache 2.0 License

Name		Name	Last commit message	Last commit date
Latest commit History 325 Commits
.github		.github
cmd/validator		cmd/validator
docs		docs
img		img
internal		internal
pkg		pkg
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.mega-linter.yml		.mega-linter.yml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PKGBUILD		PKGBUILD
README.md		README.md
SECURITY.md		SECURITY.md
_config.yml		_config.yml
go.mod		go.mod
go.sum		go.sum
index.md		index.md
version.go		version.go
version_test.go		version_test.go

Folders and files

Latest commit

History

Repository files navigation

Config File Validator

About

Table of Contents

Supported File Types

Known Files

Demo

Installation

Binary Releases

Package Managers

Arch Linux

go install

GitHub Action

Pre-commit Hook

Usage

Configuration File

Environment Variables

Examples

Standard Run

Multiple search paths

Exclude directories

Exclude file types

Include only specific file types

Customize recursion depth

Customize report output

Group report output

Multiple groups

Output results to a file

Suppress output

Read from stdin

Exit codes

Schema validation

Declaring a schema

Automatic schema lookup with SchemaStore

External schema mapping

Map file types with glob patterns

Search files using a glob pattern

Calling the config-file-validator programmatically

Build

macOS

Build

Install

Linux

Build

Install

Windows

Build

Install

Docker

Contributors

Contributing

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Uh oh!

Uh oh!

Uh oh!

Languages

`go install`