Repository files navigation

A GitHub Action to quickly validate JSON and YAML files in a repository

This action comes pre-packaged with two different common JSON and YAML validators:

• JSON validation withajv - The fastest NodeJS JSON validator
• YAML validation withyaml-schema-validator

If you have a repository containing JSON or YAML files and want to validate them extremely quickly, this action is for you!

You can provide schemas to check against, or just validate the syntax of the files. This comes very handy when you want to ensure that your JSON and YAML files are valid before committing them to your repository, especially from pull requests.

This Action is also extremelyfast ⚡. It usesfdir under the hood for directory crawling and file globbing when looking for JSON and YAML files. This Action can crawl through a million files in under a second and validate those files in just a few more.

Here is a quick example of how to install this action in any workflow:

# checkout the repository (required for this Action to work)-uses:actions/checkout@v5# validate JSON and YAML files-name:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# <--- replace with the latest version

Here are some basic usage examples for this Action

name:json-yaml-validateon:push:branches:      -mainpull_request:workflow_dispatch:permissions:contents:readjobs:json-yaml-validate:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v5      -name:json-yaml-validateid:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# replace with the latest version

Here is a usage example in the context of a pull request with comment mode enabled:

name:json-yaml-validateon:push:branches:      -mainpull_request:workflow_dispatch:permissions:contents:readpull-requests:write# enable write permissions for pull request commentsjobs:json-yaml-validate:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v5      -name:json-yaml-validateid:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# replace with the latest versionwith:comment:"true"# enable comment mode

The resulting comment will look like this:

This Action also supports schema validation for both JSON and YAML files.

References docs for both JSON and YAML schema validation can be found at the links below:

• JSON Schema Validation Docs
• YAML Schema Validation Docs - Additional docscan be found here

Note: JSON files and YAML files use two separate libraries for schema validation

Assuming the following repository structure:

/├── schemas/│   ├── schema.yml│   └── schema.json├── data/│   ├── test.json│   └── test.yml└── ...

Here is an example of how to use this feature:

# checkout the repository-uses:actions/checkout@v5-name:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# replace with the latest versionwith:yaml_schema:schemas/schema.yml# validate YAML files against the schemajson_schema:schemas/schema.json# validate JSON files against the schema

When this Action workflow runs, it will validate all JSON and YAML files in the repository against the schema files in theschemas/ directory.

If you want to only validate files in thedata/ directory, you could set thebase_dir input todata/

For validating a.json file with a.json schema

{"foo":1,"bar":"abc"}

{"type":"object","properties": {"foo": {"type":"integer"    },"bar": {"type":"string"    }  },"required": ["foo"  ],"additionalProperties":false}

Details on the fields seen in the schema above:

• type - the type of the value, can be one ofstring,number,integer,boolean,array,object,null
• required - an array of strings, each of which is a property name that is required
• additionalProperties - a boolean value that determines if additional properties are allowed in the object

You can also use custom regex formats in your JSON schema. This is useful for validating specific formats of strings. This section describes how you can use custom regex formats with this Action.

Here is an example JSON schema that uses custom regex formats:

For this example, assume that the JSON schema's file path is./schemas/custom_with_regex.json from the root of the repository

{"type":"object","properties": {"lowercase_char_property": {"type":"string","format":"lowercase_char"    },"lowercase_alphanumeric_property": {"type":"string","format":"lowercase_alphanumeric"    }  },"required": ["lowercase_char_property","lowercase_alphanumeric_property"],"additionalProperties":false}

Here is an example file that we are going to validate against the schema above:

For this example, assume that the JSON file's file path isconfig/valid.json from the root of the repository

{"lowercase_char_property":"valid","lowercase_alphanumeric_property":"valid1"}

Now that we have a JSON schema that uses custom regex formats and a JSON file that we want to validate against the schema, we need to provide the custom regex formats to the Action. The example workflow step below shows how to do this:

-name:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# replace with the latest versionid:json-yaml-validatewith:json_schema:./schemas/custom_with_regex.json# <--- the schema file that uses custom regex formatsajv_custom_regexp_formats:|      lowercase_char=^[a-z]*$      lowercase_alphanumeric=^[a-z0-9]*$# ^ these are the custom regex formats used in the schema that we inject into the Action so they can be usedfiles:|      config/valid.json# ^ uses the example file as seen in the section above

Theajv_custom_regexp_formats input is a multi-line string that contains the custom regex formats used in the JSON schema. Each line in the string should be in the formatformat_name=regex_pattern. Theformat_name is the name of the custom regex format used in the schema, andregex_pattern is the regex pattern that the value in the JSON file must match.

For validating a.yaml file with a.yaml schema

Note: can also be.yml files, both work

The following is a sample yaml file to input into the validator schema which will be seen below:

---person:name:first_name:monalisaage:2000employed:truehobbies:    -tennis    -football

The schema used to validate the input file from above:

---person:name:first_name:type:stringlength:# define min and max length (optional)min:2max:10age:type:numberrequired:true# make this field required (optional)employed:type:booleanhobbies:    -type:stringenum:[football, basketball, tennis]# only accept these values (optional)

Details on the fields seen in the schema above:

• type - The type of the field (e.g.string,number,boolean, etc)
• length - The length of the field withmin andmax constraints
• required - Whether or not the field is required
• enums - An array of values that the field can be

There are three main ways you can go about excluding files from being validated with this Action:

• json_exclude_regex - A regex string that will be used to excludeJSON files from being validated
• yaml_exclude_regex - A regex string that will be used to excludeYAML files from being validated
• exclude_file -best way to exclude files - A file that contains a list of files to exclude from being validated ingitignore format

It should be strongly noted that bothjson_exclude_regex andyaml_exclude_regex options get unwieldy very quickly and are not recommended. Theexclude_file option is the best way to exclude files from being validated. Especially if you have a large repository with many files.

Example of anexclude_file's contents:

# exclude all files in the test/ directorytest/# exclude a yaml file at an exact pathsrc/cool-path/example.yaml# exclude all json files with some glob matching*.test.json

If the file path to yourexclude_file isexclude.txt, you would set theexclude_file input toexclude.txt like so:

# checkout the repository-uses:actions/checkout@v5-name:json-yaml-validateuses:GrantBirki/json-yaml-validate@vX.X.X# replace with the latest versionwith:exclude_file:exclude.txt# gitignore style file that contains a list of files to exclude

Below is a very simple example of a violation warning that you might see in this Action in your Action's logs or as a comment on a pull request:

[  {"file":"./test/test2.json","errors": [      {"path":null,"message":"Invalid JSON"      }    ]  },  {"file":"./test/test3.yaml","errors": [      {"path":"person.age","message":"person.age must be of type String."      }    ]  }]

The example above contains two violations - one for a JSON file and one for a YAML file. Here is what each of the fields mean:

• file - The full path to file that the violation occurred in
• errors - An array of errors that occurred in the file
  • path - The path to the error in the file (if applicable) - Note: This isnot the file path but rather the path place within the file that the error occurred
  • message - The error message

In the example above, thepath for the JSON file isnull and the message saysInvalid JSON. This means that the entire file could not be parsed as JSON. Likewise, if you seenull for thepath and the message saysInvalid YAML, this means that the entire file could not be parsed as YAML.

This section documents known issues and workarounds / fixes

If you plan on using your.gitignore file, you should always include a trailing slash when excluding a directory. For example, instead ofnode_modules usenode_modules/. This will ensure the Action correctly detects the directory as a directory and not a file.