YJ Schema Validator

Description

YJ Schema Validator is a lightweight Java CLI tool for validating YAML and JSON files against JSON Schema definitions (drafts 2019-09/2020-12). Built with Spring Boot for easy bootstrapping, it uses Jackson for parsing and NetworkNT for robust validation. Perfect for quick local checks or automated CI/CD pipelines.

Features

• Dual Format Support: Validates YAML and JSON files seamlessly.

• Remote Schemas: Fetch schemas via HTTP/HTTPS (with timeout & SSL ignore options).

• Flexible Outputs: Console (colored), JSON, YAML, JUnit (alpha) for CI integration.

• Multi-Document YAML: Supports --- separated YAML documents

• Batch Processing: Validate multiple files in one run; exits 0 on success, 1 on failure.

• Schema Override: Ignore embedded $schema in files for centralized control.

• Java 17+ compatible; no external deps beyond the fat JAR.

Installation

Download the latest fat JAR from Maven Central:

curl -L -o yj-schema-validator.jar https://repo1.maven.org/maven2/org/alexmond/yj-schema-validator/3.0.0/yj-schema-validator-3.0.0.jar

Verify: java -jar yj-schema-validator.jar --help

Build from source (requires Maven and Java 17+):

git clone https://github.com/alexmond/yj-schema-validator.git
cd yj-schema-validator
mvn clean package
java -jar target/yj-schema-validator-3.0.0.jar --help

Usage

Basic syntax: java -jar yj-schema-validator.jar [options] [<file1> <file2> …​]

If no files are provided, or if - is used as a filename, the tool reads from stdin.

Quick Start

Validate a single file (assumes schema in file’s $schema):

java -jar yj-schema-validator.jar config.yaml
# Output: config.yaml: ok
#         Validation Result: ok

Validate from stdin:

cat config.yaml | java -jar yj-schema-validator.jar --schema=schema.json

With explicit schema:

java -jar yj-schema-validator.jar config.yaml --schema=schema.json

Batch with JUnit report (for CI):

java -jar yj-schema-validator.jar *.yaml --schema=schema.json --report-type=junit --report-file-name=report.xml

Multi-document support

java -jar yj-schema-validator.jar src/test/resources/multi3valid.yaml
Validation Result: ok
src/test/resources/multi3valid.yaml-1: ok
src/test/resources/multi3valid.yaml-3: ok
src/test/resources/multi3valid.yaml-2: ok

GitHub Action

A reusable GitHub Action is published from this repo. It runs the validator inside a container image built with Spring Boot Cloud Native Buildpacks (no Dockerfile), so no Java setup is needed in the consumer workflow. Linux runners only.

- uses: alexmond/yj-schema-validator@v2
  with:
    files: 'config/**/*.yaml'          # paths or globs (whitespace/newline separated)
    schema: schema.json                # path or URL; omit to use each file's own $schema
    report: text                       # text | json | yaml | junit | sarif

Upload findings to the GitHub Security tab as SARIF:

- uses: alexmond/yj-schema-validator@v2
  with:
    files: 'config/**/*.yaml'
    schema: schema.json
    report: sarif
    report-file: results.sarif
    fail-on-error: 'false'             # don't fail the step; let code scanning surface issues
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Inputs: files, schema, report, report-file, schema-override, http-timeout, ignore-ssl-errors, color, extra-args, fail-on-error, image. Outputs: exit-code, report-file.

Note	The tool auto-loads a Spring Boot application.yaml from the working directory (the repo root under -w /github/workspace). If your repo has one with top-level files:/schema: keys, its settings override the action inputs — remove those keys or rely on the file instead of inputs.

Plain CLI in CI

- name: Validate Schemas
  run: |
    curl -L -o yj-schema-validator.jar https://repo1.maven.org/maven2/org/alexmond/yj-schema-validator/3.0.0/yj-schema-validator-3.0.0.jar
    java -jar yj-schema-validator.jar config/*.yaml --schema=schema.json --report-type=junit > report.xml
  # Use actions like 'dorny/test-reporter' to publish report.xml

Configuration

Flag	Description	Default	Example
--help	Show usage help	N/A	--help
--files	Path to input YAML/JSON file(s) (positional args also supported)	N/A	`--files=app.yaml or "app.yaml,config.json"
--schema	Path or URL to JSON Schema file	Embedded $schema in file	--schema=schema.json or --schema=https://example.com/schema.json
--report-type	Output format: text (colored console), json, yaml, junit (alpha)	text	--report-type=junit
--report-file-name	Output file for non-console reports	stdout	--report-file-name=validation.json
--color	Enable/disable colored output	true	--color=false
--http-timeout	Timeout (seconds) for remote schema fetches	10	--http-timeout=30
--ignore-ssl-errors	Skip SSL certificate validation for HTTPS schemas	false	--ignore-ssl-errors

Troubleshooting

Issue	Cause	Solution
"No schema found"	Missing --schema	Provide via flag or embed in file.
YAML parse error	Invalid syntax	Check line/col in error; use --color=false for plain text.
HTTP timeout	Slow remote schema	Increase --http-timeout=30.
JUnit alpha issues	Experimental	Report bugs; fallback to JSON.

For SSL issues: Use --ignore-ssl-errors (not recommended for production).

Contributing

1. Fork the repo and create a feature branch (git checkout -b feat/amazing-feature).

2. Commit changes (git commit -m 'Add some AmazingFeature').

3. Push to the branch (git push origin feat/amazing-feature).

4. Open a Pull Request.

Build and test locally:

mvn clean package
mvn test

See open issues for details.

License

Licensed under Apache 2.0 License.

Acknowledgments

• Built on NetworkNT JSON Schema Validator.

• Thanks to contributors: List here.

Full Documentation

Read the full docs here