{"id":15286417,"url":"https://github.com/grantbirki/json-yaml-validate","last_synced_at":"2026-05-09T02:24:26.116Z","repository":{"id":147536181,"uuid":"618809121","full_name":"GrantBirki/json-yaml-validate","owner":"GrantBirki","description":"A GitHub Action to quickly validate JSON and YAML files in a repository","archived":false,"fork":false,"pushed_at":"2025-02-26T22:11:05.000Z","size":5989,"stargazers_count":29,"open_issues_count":12,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T14:13:27.820Z","etag":null,"topics":["actions","ci","json","validation","yaml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrantBirki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-25T12:18:58.000Z","updated_at":"2025-01-31T21:16:35.000Z","dependencies_parsed_at":"2023-12-29T23:26:29.193Z","dependency_job_id":"eff4045a-7aa1-4bc8-b633-79e37db1b3e0","html_url":"https://github.com/GrantBirki/json-yaml-validate","commit_stats":{"total_commits":253,"total_committers":9,"mean_commits":28.11111111111111,"dds":"0.20948616600790515","last_synced_commit":"e42e6ece9b97f2b220274c909a9a98e380c2c9fd"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fjson-yaml-validate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fjson-yaml-validate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fjson-yaml-validate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrantBirki%2Fjson-yaml-validate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrantBirki","download_url":"https://codeload.github.com/GrantBirki/json-yaml-validate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054193,"owners_count":21039952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","ci","json","validation","yaml"],"created_at":"2024-09-30T15:13:55.997Z","updated_at":"2026-05-09T02:24:26.110Z","avatar_url":"https://github.com/GrantBirki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON and YAML - Validator ✅\n\n[![test](https://github.com/grantbirki/json-yaml-validate/actions/workflows/test.yml/badge.svg)](https://github.com/grantbirki/json-yaml-validate/actions/workflows/test.yml)\n[![acceptance](https://github.com/GrantBirki/json-yaml-validate/actions/workflows/acceptance.yml/badge.svg)](https://github.com/GrantBirki/json-yaml-validate/actions/workflows/acceptance.yml)\n[![package-check](https://github.com/grantbirki/json-yaml-validate/actions/workflows/package-check.yml/badge.svg)](https://github.com/grantbirki/json-yaml-validate/actions/workflows/package-check.yml)\n[![lint](https://github.com/grantbirki/json-yaml-validate/actions/workflows/lint.yml/badge.svg)](https://github.com/grantbirki/json-yaml-validate/actions/workflows/lint.yml)\n[![coverage](./badges/coverage.svg)](./badges/coverage.svg)\n\nA GitHub Action to quickly validate JSON and YAML files in a repository\n\n## About 💡\n\nThis action comes pre-packaged with JSON and YAML validation support:\n\n- JSON validation with [ajv](https://github.com/ajv-validator/ajv) - The fastest NodeJS JSON validator\n- YAML parsing and legacy YAML schema validation implemented in native TypeScript\n\nIf you have a repository containing JSON or YAML files and want to validate them extremely quickly, this action is for you!\n\nYou 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.\n\nThis Action is also designed to stay fast while keeping its dependency surface small. It uses native recursive directory discovery for normal scans and Node's native glob expansion when the `files` input is provided.\n\n## Installation 📦\n\nHere is a quick example of how to install this action in any workflow:\n\n```yaml\n# checkout the repository (required for this Action to work)\n- uses: actions/checkout@v6\n\n# validate JSON and YAML files\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n```\n\nPlanning a v5 upgrade? Read the\n[v4 to v5 migration guide](docs/migrating-from-v4-to-v5.md) before updating\nthe action ref.\n\n## Inputs 📥\n\n| Input | Required? | Default | Description |\n| ----- | --------- | ------- | ----------- |\n| `mode` | `false` | `\"fail\"` | The mode to run the action in `\"warn\"` or `\"fail\"` |\n| `comment` | `false` | `\"false\"` | Whether or not to comment on a PR with the validation results - `\"true\"` or `\"false\"` |\n| `comment_on_success` | `false` | `\"false\"` | Whether or not to comment on a PR when all validation checks pass - `\"true\"` or `\"false\"` |\n| `update_comment` | `false` | `\"false\"` | Whether or not to update an existing validation results PR comment authored by `github-actions[bot]` instead of creating a new one - `\"true\"` or `\"false\"` |\n| `base_dir` | `false` | `\".\"` | The base directory to search for JSON and YAML files (e.g. ./src) - Default is `\".\"` which searches the entire repository. The directory must resolve inside the workspace. |\n| `files` | `false` | `\"\"` | List of file paths to validate. File paths may be newline-delimited or provided as a single space-separated line. Matched files must resolve to regular files inside the workspace. |\n| `schema_mappings` | `false` | `\"\"` | YAML list that maps JSON or YAML schema files to explicit file patterns for multi-schema validation |\n| `use_inline_schema` | `false` | `\"false\"` | Whether or not to use local inline JSON Schema references in JSON files and YAML language-server schema comments when YAML is validated as JSON |\n| `use_dot_match` | `false` | `\"true\"` | Whether or not to use dot-matching when searching for files - `\"true\"` or `\"false\"` - If this is true, directories like `.github`, etc will be searched |\n| `json_schema` | `false` | `\"\"` | The full path to the JSON schema file (e.g. ./schemas/schema.json) - Default is `\"\"` which doesn't enforce a strict schema |\n| `json_schema_version` | `false` | `\"draft-07\"` | The version of the JSON schema to use - `\"draft-07\"`, `\"draft-04\"`, `\"draft-2019-09\"`, `\"draft-2020-12\"` |\n| `json_extension` | `false` | `\".json\"` | The file extension for JSON files (e.g. .json) |\n| `json_exclude_regex` | `false` | `\"\"` | A regex to exclude files from validation (e.g. `\".*\\.schema\\.json$\"` to exclude all files ending with `.schema.json`) - Default is `\"\"` which doesn't exclude any files |\n| `use_ajv_formats` | `false` | `\"true\"` | Whether or not to use the [AJV formats](https://github.com/ajv-validator/ajv-formats) with the JSON processor |\n| `yaml_schema` | `false` | `\"\"` | The full path to the YAML schema file (e.g. ./schemas/schema.yaml) - Default is `\"\"` which doesn't enforce a strict schema |\n| `yaml_extension` | `false` | `\".yaml\"` | The file extension for YAML files (e.g. .yaml) |\n| `yaml_extension_short` | `false` | `\".yml\"` | The \"short\" file extension for YAML files (e.g. .yml) |\n| `yaml_exclude_regex` | `false` | `\"\"` | A regex to exclude files from validation (e.g. `\".*\\.schema\\.yaml$\"` to exclude all files ending with `.schema.yaml`) - Default is `\"\"` which doesn't exclude any files |\n| `yaml_as_json` | `false` | `\"false\"` | Whether or not to treat and validate YAML files as JSON files - `\"true\"` or `\"false\"` - Default is `\"false\"`. If this is true, the JSON schema will be used to validate YAML files. Any YAML schemas will be ignored. For this context, a YAML file is any file which matches the yaml_extension or yaml_extension_short inputs. See the [docs](docs/yaml_as_json.md) for more details |\n| `exclude_file` | `false` | `\"\"` | The full path to a file in the repository where this Action is running that contains a list of '.gitignore'-style patterns to exclude files from validation (e.g. ./exclude.txt) |\n| `exclude_file_required` | `true` | `\"true\"` | Whether or not the `exclude_file` must exist if it is used. If this is `true` and the `exclude_file` does not exist, the Action will fail. Set this to `\"false\"` if you do not care when the `exclude_file` exists or not |\n| `use_gitignore` | `true` | `\"true\"` | Whether or not to use the .gitignore file in the root of the repository to exclude files from validation - `\"true\"` or `\"false\"` - Default is `\"true\"` |\n| `git_ignore_path` | `false` | `\".gitignore\"` | The full path to the .gitignore file to use if use_gitignore is set to \"true\" (e.g. ./src/.gitignore) - Default is \".gitignore\" which uses the .gitignore file in the root of the repository |\n| `allow_multiple_documents` | `false` | `\"true\"` | Whether or not to allow multiple documents in a single YAML file - `\"true\"` or `\"false\"` - Default is `\"true\"`. Set to `\"false\"` to reject Kubernetes-style multi-document YAML files. |\n| `ajv_strict_mode` | `false` | `\"true\"` | Whether or not to use strict mode for AJV - \"true\" or \"false\" - Default is \"true\" |\n| `ajv_custom_regexp_formats` | `false` | `\"\"` | List of key value pairs of `format_name=regexp`. Each pair must be on a newline. (e.g. `lowercase_chars=^[a-z]*$` - See below for more details) |\n| `github_token` | `false` | `${{ github.token }}` | The GitHub token used to create an authenticated client - Provided for you by default! |\n\nValidation targets discovered from `base_dir`, `files`, or `schema_mappings`\nare resolved through real paths before they are read. Directories, non-file\nmatches, and symlinks that resolve outside `GITHUB_WORKSPACE` fail validation\ninstead of being read.\n\n## Outputs 📤\n\n| Output | Description |\n| ------ | ----------- |\n| `success` | Whether or not the validation was successful for all files - `\"true\"` or `\"false\"` |\n\n## Usage 🚀\n\nHere are some basic usage examples for this Action\n\n### Basic\n\n```yaml\nname: json-yaml-validate \non:\n  push:\n    branches:\n      - main\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n\njobs:\n  json-yaml-validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n\n      - name: json-yaml-validate\n        id: json-yaml-validate\n        uses: GrantBirki/json-yaml-validate@v5\n```\n\n### Pull Request Comment\n\nHere is a usage example in the context of a pull request with comment mode enabled:\n\n```yaml\nname: json-yaml-validate \non:\n  push:\n    branches:\n      - main\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pull-requests: write # enable write permissions for pull request comments\n\njobs:\n  json-yaml-validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n\n      - name: json-yaml-validate\n        id: json-yaml-validate\n        uses: GrantBirki/json-yaml-validate@v5\n        with:\n          comment: \"true\" # enable comment mode\n```\n\nThe resulting comment will look like this:\n\n![comment-example](docs/assets/comment-example.png)\n\nWhen `update_comment` is set to `\"true\"`, the action only updates an existing\nvalidation results comment authored by `github-actions[bot]`. If no matching\nbot-authored validation comment exists, it creates a new comment instead.\n\n### Schema Validation\n\nThis Action also supports schema validation for both JSON and YAML files.\n\nReferences for JSON Schema validation can be found at the link below. The YAML schema syntax supported by this action is documented in the YAML example that follows.\n\n- [JSON Schema Validation Docs](https://ajv.js.org/json-schema.html#json-schema)\n\n\u003e Note: JSON files use AJV JSON Schema. YAML files use this action's legacy YAML schema dialect, which is intentionally smaller and is not JSON Schema.\n\nAssuming the following repository structure:\n\n```text\n/\n├── schemas/\n│   ├── schema.yml\n│   └── schema.json\n├── data/\n│   ├── test.json\n│   └── test.yml\n└── ...\n```\n\nHere is an example of how to use this feature:\n\n```yaml\n# checkout the repository\n- uses: actions/checkout@v6\n\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n  with:\n    yaml_schema: schemas/schema.yml # validate YAML files against the schema\n    json_schema: schemas/schema.json # validate JSON files against the schema\n```\n\nWhen this Action workflow runs, it will validate all JSON and YAML files in the repository against the schema files in the `schemas/` directory.\n\n\u003e If you want to only validate files in the `data/` directory, you could set the `base_dir` input to `data/`\n\nYAML files may contain multiple documents separated by `---`. This is valid\nYAML and is common for Kubernetes manifests, so `allow_multiple_documents`\ndefaults to `\"true\"`. When `yaml_schema` is set, each YAML document is validated\nagainst the configured schema. Set `allow_multiple_documents: \"false\"` when a\nworkflow should reject files that contain more than one YAML document.\n\n### Multiple Schema Mappings\n\nUse `schema_mappings` when different file groups need different schemas in the same action step. When this input is set, the mappings are authoritative: the action validates only files matched by the mapping entries and does not fall back to `base_dir`, `files`, `json_schema`, or `yaml_schema`. See [schema mappings docs](docs/schema_mappings.md) for the detailed behavior.\n\nEach mapping entry requires:\n\n- `type`: either `json` or `yaml`\n- `schema`: the schema file for that entry\n- `files`: one file pattern, or a list of file patterns\n- `json_schema_version`: optional for JSON mappings, defaulting to the top-level `json_schema_version`\n\n```yaml\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n  with:\n    schema_mappings: |\n      - type: json\n        schema: ./schemas/index-schema.json\n        files:\n          - ./data/index_*.json\n        json_schema_version: draft-07\n      - type: json\n        schema: ./schemas/topic-schema.json\n        files:\n          - ./data/topic_*.json\n      - type: yaml\n        schema: ./schemas/config-schema.yaml\n        files:\n          - ./config/*.yaml\n          - ./config/*.yml\n```\n\n`schema_mappings` still uses the global exclude options, AJV options, `yaml_as_json`, and `allow_multiple_documents` where those options apply. YAML schema mappings cannot be used when `yaml_as_json` is `\"true\"` because YAML schemas are ignored in that mode.\n\n### Inline Schemas\n\nUse `use_inline_schema` when files already declare their JSON Schema locally and you do not want to duplicate that mapping in workflow YAML. JSON files can declare a top-level `$schema` value, and YAML files can declare a leading `# yaml-language-server: $schema=...` comment when `yaml_as_json` is `\"true\"`.\n\n```yaml\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n  with:\n    use_inline_schema: \"true\"\n    yaml_as_json: \"true\"\n```\n\nInline schema references are local-only. Relative schema paths are resolved from the file being validated, absolute schema paths must stay inside the workspace, and arbitrary remote `http://` or `https://` schemas are rejected instead of fetched. `schema_mappings` and explicit `json_schema` inputs take precedence over inline schemas. See [inline schema docs](docs/inline_schema.md) for detailed behavior.\n\n### JSON Schema Docs\n\nFor validating a `.json` file with a `.json` schema\n\n#### JSON Input Example\n\n```json\n{\n  \"foo\": 1,\n  \"bar\": \"abc\"\n}\n\n```\n\n#### JSON Schema Example\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"foo\": {\n      \"type\": \"integer\"\n    },\n    \"bar\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [\n    \"foo\"\n  ],\n  \"additionalProperties\": false\n}\n```\n\nDetails on the fields seen in the schema above:\n\n- `type` - the type of the value, can be one of `string`, `number`, `integer`, `boolean`, `array`, `object`, `null`\n- `required` - an array of strings, each of which is a property name that is required\n- `additionalProperties` - a boolean value that determines if additional properties are allowed in the object\n\n### JSON Schema with Custom Regex Formats\n\nYou 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.\n\n#### JSON Schema Example with Custom Regex Formats\n\nHere is an example JSON schema that uses custom regex formats:\n\n\u003e For this example, assume that the JSON schema's file path is `./schemas/custom_with_regex.json` from the root of the repository\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"lowercase_char_property\": {\n      \"type\": \"string\",\n      \"format\": \"lowercase_char\"\n    },\n    \"lowercase_alphanumeric_property\": {\n      \"type\": \"string\",\n      \"format\": \"lowercase_alphanumeric\"\n    }\n  },\n  \"required\": [\"lowercase_char_property\", \"lowercase_alphanumeric_property\"],\n  \"additionalProperties\": false\n}\n```\n\n#### JSON Input Example with Custom Regex Formats\n\nHere is an example file that we are going to validate against the schema above:\n\n\u003e For this example, assume that the JSON file's file path is `config/valid.json` from the root of the repository\n\n```json\n{\n  \"lowercase_char_property\": \"valid\",\n  \"lowercase_alphanumeric_property\": \"valid1\"\n}\n```\n\n#### Custom Regex Formats - Action Input\n\nNow 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:\n\n```yaml\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n  id: json-yaml-validate\n  with:\n    json_schema: ./schemas/custom_with_regex.json # \u003c--- the schema file that uses custom regex formats\n    ajv_custom_regexp_formats: |\n      lowercase_char=^[a-z]*$\n      lowercase_alphanumeric=^[a-z0-9]*$\n    # ^ these are the custom regex formats used in the schema that we inject into the Action so they can be used\n    files: |\n      config/valid.json\n    # ^ uses the example file as seen in the section above\n```\n\nThe `ajv_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 format `format_name=regex_pattern`. The `format_name` is the name of the custom regex format used in the schema, and `regex_pattern` is the regex pattern that the value in the JSON file must match.\n\n### YAML Schema Docs\n\nFor validating a `.yaml` file with a `.yaml` schema\n\n\u003e Note: can also be `.yml` files, both work\n\n#### YAML Input Example\n\nThe following is a sample yaml file to input into the validator schema which will be seen below:\n\n```yaml\n---\nperson:\n  name:\n    first_name: monalisa\n  age: 2000\n  employed: true\n  hobbies:\n    - tennis\n    - football\n\n```\n\n#### YAML Schema Example\n\nThe schema used to validate the input file from above:\n\n```yaml\n---\nperson:\n  name:\n    first_name:\n      type: string\n      length: # define min and max length (optional)\n        min: 2\n        max: 10\n  age:\n    type: number\n    required: true # make this field required (optional)\n  employed:\n    type: boolean\n  hobbies:\n    - type: string\n      enum: [football, basketball, tennis] # only accept these values (optional)\n```\n\nDetails on the fields seen in the schema above:\n\n- `type` - The type of the field (e.g. `string`, `number`, `boolean`, etc)\n- `length` - The length of the field with `min` and `max` constraints\n- `required` - Whether or not the field is required\n- `enum` - An array of accepted values for the field\n\n## Excluding Files\n\nThere are three main ways you can go about excluding files from being validated with this Action:\n\n- `json_exclude_regex` - A regex string that will be used to exclude **JSON** files from being validated\n- `yaml_exclude_regex` - A regex string that will be used to exclude **YAML** files from being validated\n- `exclude_file` - **best** way to exclude files - A file that contains a list of files to exclude from being validated in *gitignore* format\n\n\u003e It should be strongly noted that both `json_exclude_regex` and `yaml_exclude_regex` options get unwieldy very quickly and are not recommended. The `exclude_file` option is the best way to exclude files from being validated. Especially if you have a large repository with many files.\n\nExample of an `exclude_file`'s contents:\n\n```python\n# exclude all files in the test/ directory\ntest/\n\n# exclude a yaml file at an exact path\nsrc/cool-path/example.yaml\n\n# exclude all json files with some glob matching\n*.test.json\n```\n\nIf the file path to your `exclude_file` is `exclude.txt`, you would set the `exclude_file` input to `exclude.txt` like so:\n\n```yaml\n# checkout the repository\n- uses: actions/checkout@v6\n\n- name: json-yaml-validate\n  uses: GrantBirki/json-yaml-validate@v5\n  with:\n    exclude_file: exclude.txt # gitignore style file that contains a list of files to exclude\n```\n\n## Violations Structure Explained\n\nBelow 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:\n\n```json\n[\n  {\n    \"file\": \"./test/test2.json\",\n    \"errors\": [\n      {\n        \"path\": null,\n        \"message\": \"Invalid JSON\"\n      }\n    ]\n  },\n  {\n    \"file\": \"./test/test3.yaml\",\n    \"errors\": [\n      {\n        \"path\": \"person.age\",\n        \"message\": \"person.age must be of type String.\"\n      }\n    ]\n  }\n]\n```\n\nThe example above contains two violations - one for a JSON file and one for a YAML file. Here is what each of the fields mean:\n\n- `file` - The full path to file that the violation occurred in\n- `errors` - An array of errors that occurred in the file\n  - `path` - The path to the error in the file (if applicable) - Note: This is **not** the file path but rather the path place within the file that the error occurred\n  - `message` - The error message\n\nIn the example above, the `path` for the JSON file is `null` and the message says `Invalid JSON`. This means that the entire file could not be parsed as JSON. Likewise, if you see `null` for the `path` and the message says `Invalid YAML`, this means that the entire file could not be parsed as YAML.\n\n## Known Issues\n\nThis section documents known issues and workarounds / fixes\n\n### .gitignore directory exclusion\n\nIf you plan on using your `.gitignore` file, you should always include a trailing slash when excluding a directory. For example, instead of `node_modules` use `node_modules/`. This will ensure the Action correctly detects the directory as a directory and not a file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbirki%2Fjson-yaml-validate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrantbirki%2Fjson-yaml-validate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbirki%2Fjson-yaml-validate/lists"}