Skip to main content

​
Overview

The JSON output format provides machine-readable, structured output suitable for integration with other tools, CI/CD systems, and automated workflows. Vale outputs alerts as a JSON object with file paths as keys and arrays of alert objects as values.
Use JSON output when you need to parse Vale’s results programmatically or integrate with other tools in your workflow.

​
Usage

Enable JSON output with the --output flag: 
vale --output=JSON document.md
The output format value is case-sensitive. Use JSON in all caps.

​
Output Structure

The JSON output is an object where:
  • Keys: File paths (strings)
  • Values: Arrays of alert objects
{
  "/path/to/document.md": [
    {
      "Action": {
        "Name": "replace",
        "Params": ["the"]
      },
      "Check": "Vale.Spelling",
      "Description": "",
      "Line": 12,
      "Link": "",
      "Message": "Did you really mean 'teh'?",
      "Severity": "error",
      "Span": [5, 8],
      "Match": "teh"
    },
    {
      "Action": {
        "Name": "",
        "Params": []
      },
      "Check": "Vale.ReadabilityGrade",
      "Description": "Aim for 8th grade or lower.",
      "Line": 45,
      "Link": "https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests",
      "Message": "Grade level (12.3) too high!",
      "Severity": "warning",
      "Span": [1, 120],
      "Match": "The quick brown fox jumps..."
    }
  ],
  "/path/to/another-file.md": [
    {
      "Action": {
        "Name": "suggest",
        "Params": ["use", "utilize"]
      },
      "Check": "Vale.Terms",
      "Description": "Use simpler alternatives.",
      "Line": 8,
      "Link": "",
      "Message": "Consider using 'use' instead of 'utilize'.",
      "Severity": "suggestion",
      "Span": [15, 22],
      "Match": "utilize"
    }
  ]
}

​
Alert Object Fields

Each alert object in the arrays contains the following fields:
​
Action
object
Suggested action to fix the alert.
​
Name
string
The type of action (e.g., “replace”, “suggest”, “remove”).
​
Params
array
Array of parameters for the action, such as replacement suggestions.
​
Check
string
required
The name of the rule that generated this alert (e.g., “Vale.Spelling”, “Google.Acronyms”).
​
Description
string
Additional context or explanation for why this alert is meaningful. May be empty.
​
Line
integer
required
The line number where the issue was found (1-indexed).
​
Link
string
A URL to reference material or documentation about this rule. May be empty.
​
Message
string
required
The human-readable alert message describing the issue.
​
Severity
string
required
The severity level of the alert. One of:
  • "error": Critical issues that cause Vale to exit with a non-zero status
  • "warning": Important issues that should be addressed
  • "suggestion": Optional improvements
​
Span
array
required
A two-element array [start, end] indicating the column positions of the match within the line (0-indexed).
​
Match
string
required
The actual text that triggered the alert.
Some fields like Offset, Limit, and Hide are excluded from JSON output (marked with json:"-" in the source code).

​
Implementation Details

The JSON output is generated by the PrintJSONAlerts function in cmd/vale/json.go:10-23: 
func PrintJSONAlerts(linted []*core.File) bool {
    alertCount := 0
    formatted := map[string][]core.Alert{}
    
    for _, f := range linted {
        for _, a := range f.SortedAlerts() {
            if a.Severity == "error" {
                alertCount++
            }
            formatted[f.Path] = append(formatted[f.Path], a)
        }
    }
    
    fmt.Println(getJSON(formatted))
    return alertCount != 0
}
The JSON output is formatted with 2-space indentation for readability. Alerts are sorted by position before being added to the output.

​
Exit Code Behavior

When using JSON output, Vale’s exit code follows the same rules as other formats:
  • Exit 0: No errors found (warnings and suggestions are OK)
  • Exit 1: One or more errors found
vale --output=JSON document.md
echo $?  # prints 1 if errors found, 0 otherwise

​
Integration Examples

​
Using jq to Filter Results

Extract only errors using jq: 
vale --output=JSON *.md | jq '.[][] | select(.Severity == "error")'

​
Count Total Alerts

vale --output=JSON *.md | jq '[.[][]] | length'

​
Extract All Error Messages

vale --output=JSON *.md | jq -r '.[][] | select(.Severity == "error") | .Message'

​
Group by Severity

vale --output=JSON *.md | jq '[.[][]] | group_by(.Severity)'
Combine JSON output with tools like jq, python, or node for custom processing and reporting.

​
Common Use Cases

​
CI/CD Integration

Parse JSON output in your CI pipeline to create custom reports:
GitHub Actions Example
- name: Run Vale
  run: |
    vale --output=JSON docs/ > vale-results.json
    
- name: Process Results
  run: |
    python scripts/process-vale-results.py vale-results.json

​
IDE Integration

Many IDEs and text editors use JSON output to display inline linting results. The structured format makes it easy to:
  • Highlight issues in the editor
  • Show tooltips with error messages
  • Provide quick-fix actions based on the Action field

​
Custom Reporting

Generate custom HTML, Markdown, or other report formats by parsing the JSON output:
Node.js Example
const fs = require('fs');
const results = JSON.parse(fs.readFileSync('vale-output.json'));

for (const [file, alerts] of Object.entries(results)) {
  console.log(`\n## ${file}`);
  alerts.forEach(alert => {
    console.log(`- Line ${alert.Line}: ${alert.Message}`);
  });
}
When parsing JSON output in scripts, remember that an empty result is a valid JSON object ({}) with zero keys.

​
Comparison with Other Formats

FeatureJSONCLILine
Human-readable❌✅✅
Machine-parsable✅❌⚠️
Includes colors❌✅❌
Shows Action hints✅❌❌
Includes metadata✅⚠️❌
File grouping✅✅❌
  • Use --output=CLI for human-readable output
  • Use --output=line for simple line-based output
  • Use --sort to sort results by file path before JSON encoding
  • Use custom templates for complete control over output format

Build docs developers (and LLMs) love

Get started for freeTalk to us