Blueutils
← Back to Overview

YAML Schema Validator

Define a YAML/JSON Schema and validate your target YAML payload against it in real time.

How to Validate YAML Against a Schema

1

Provide YAML Schema

Paste a valid YAML or JSON Schema definition into the top editor or click Load Sample Schema.

2

Provide Target YAML Data

Paste the YAML configuration payload you want to test into the target data editor.

3

Execute Schema Check

Click Validate YAML against Schema to test compliance and inspect any constraint error paths.

YAML Schema Validator: Practical Guide and Error Troubleshooting

YAML is notorious for its deceptive simplicity. Relying heavily on indentation and implicit type conversions, it frequently causes deployment failures when a string evaluates as a boolean (the infamous "Norway problem" with NO becoming false) or an integer is parsed as a string. A YAML schema validator mitigates this by enforcing strict data types, required fields, and structural rules on your YAML documents using the JSON Schema specification.

When a payload fails schema validation, the YAML itself is typically syntactically correct, but the data it contains violates the explicit contract defined for the application or infrastructure. This tool intercepts those logic errors in real-time, preventing misconfigured CI/CD pipelines, Kubernetes manifests, or backend configurations from reaching production.

How the Parser Works Under the Hood

The validation process executes in a highly structured, three-stage pipeline:

  1. Lexical Parsing: The engine reads the raw YAML text, evaluating whitespace, line breaks, and indentation levels to construct a structural graph of dictionaries, arrays, and scalars.
  2. Translation to AST/JSON: Because the validation standard is built on JSON Schema, the parsed YAML data structure is converted in memory into a JSON-equivalent Abstract Syntax Tree (AST).
  3. Schema Execution: The validation engine (such as Ajv) compiles your target JSON/YAML schema into an executable function. It traverses the AST, verifying that data types, array lengths, required keys, and regex patterns match the defined rules. The moment a violation occurs, the engine maps the error back to the JSON pointer path (e.g., #/spec/replicas) and fails.

Core Syntax Rules to Avoid Failures

  • Indentation is structural: You must use spaces exclusively. Tabs are strictly forbidden by the YAML specification. Stick to consistent 2-space or 4-space increments.
  • Explicit String Quoting: Force strings to remain strings by wrapping them in quotes, especially if the value resembles a boolean ("true", "on", "no"), a float ("1.0"), or a time format.
  • Strict Type Matching: Schema validators do not coerce types. If the schema dictates an integer, passing 8080 passes, but "8080" (string) immediately triggers a failure.
  • Required Array Formatting: List items require a hyphen followed by a space (- item). Missing the space merges the hyphen into the scalar value, breaking the expected array structure.
  • No Unmapped Properties: If your schema sets additionalProperties: false, adding a typo'd key, an undocumented field, or an inline metadata tag will result in immediate rejection.

Common Error Messages and Solutions

Exact Parser Error Message Root Cause Immediate Fix
data.port should be integer A numeric field was wrapped in quotes or contains a decimal, making it a string or float. Remove the quotes (e.g., change port: "80" to port: 80).
data should NOT have additional properties A typo exists in a key name, or you injected a configuration field not defined in the schema contract. Delete the offending key, fix the typo, or update the schema's properties definition.
data should have required property 'image' A mandatory field dictated by the schema's required array is missing from the payload. Add the missing key-value pair at the correct indentation level.
data.tags should be array A field expected to be a list was defined as a scalar string or a dictionary. Format the value as a list using hyphenated syntax (- item_name).

Practical Examples: Broken vs. Corrected

The Context: Assume a schema requires a name (string), a port (integer), and sets additionalProperties: false.

Broken: Implicit Typing and Extra Fields This payload triggers two errors: a type mismatch on the port, and a violation of the strict properties rule due to the labels block.

name: core-api-service
port: "8080"
labels:
  env: production

Corrected: Strip the quotes from the port to satisfy the integer requirement, and remove the undocumented labels field.

name: core-api-service
port: 8080

Command-Line Validation Alternatives

To validate YAML against a JSON/YAML schema directly in your terminal or CI environment, use these robust CLI tools:

Using check-jsonschema (Python ecosystem): Install via pip install check-jsonschema. It natively handles YAML payloads against JSON schemas.

check-jsonschema --schemafile schema.json config.yaml

Using yq combined with ajv-cli (Node.js ecosystem): Convert the YAML to JSON on the fly, piping it to the strict JSON validator.

yq eval -j config.yaml | ajv validate -s schema.json -d -

Using Kubeconform (For Kubernetes specifically): If you are validating Kubernetes manifests against CRD schemas.

kubeconform -strict payload.yaml

Local Development Best Practices

  • IDE Schema Mapping: Use the Red Hat YAML extension in VS Code. Add # yaml-language-server: $schema=./schema.json to the top of your YAML files. This provides native intellisense, autocomplete, and real-time schema linting as you type.
  • Enforce Pre-commit Hooks: Utilize the pre-commit framework with a check-jsonschema hook. This ensures no developer can commit or push YAML configurations that violate the infrastructure contract.
  • Separate Syntax from Schema: Run a standard syntax linter like yamllint in CI before running the schema validator. yamllint catches structural bugs and trailing spaces, while the schema validator catches logic, type, and missing-field errors.