Hospital Price Transparency CLI Validator


CLI for validating CMS Hospital Price Transparency machine-readable files

Getting Started

$3

These were the minimum versions used to develop the CLI tool. It is recommended to keep both Node and NPM up-to-date with the latest releases.

- Node (version 20.x)
- NPM (version 8.5.x)

$3

Install the CLI globally with

``sh
npm install -g @cmsgov/hpt-validator-cli
`

$3

`sh
cms-hpt-validator --help
Usage: cms-hpt-validator [options]

Arguments:
filepath filepath to validate
version version of data dictionary requirements to validate against (choices: "v2.1", "v2.2", "v3.0")

Options:
-V, --version output the CLI version number
-f, --format file format of file (choices: "csv", "json")
-o, --output output format (choices: "table", "json", default: "table")
-e, --error-limit maximum number for errors (default: 1000)
-h, --help display help for command
`

$3

Refer to the Hospital Price Transparency Data Dictionary Repository for documentation of all requirement versions.

$3

Basic usage:

`sh
cms-hpt-validator ./sample.csv v3.0
`

Overriding the default error limit to show 50 errors:

`sh
cms-hpt-validator ./sample.csv v3.0 -e 50
`

Overriding the default error limit to show all errors:

`sh
cms-hpt-validator ./sample.csv v3.0 -e 0
`

Using JSON output format:

`sh
cms-hpt-validator ./sample.csv v3.0 -o json
`

Using JSON output format with limited errors:

`sh
cms-hpt-validator ./sample.csv v3.0 -o json -e 10
`

$3

The CLI supports two output formats:

#### Table Format (default)

The default table format provides a human-readable output with colored text, showing validation results in a structured table format.

#### JSON Format

The JSON format provides machine-readable output that includes:

- File information (path, validator version, timestamp)
- Validation status (valid/invalid)
- Error and alert counts
- Detailed error and alert arrays

Example JSON output:

`json
{
"file": "/path/to/sample.csv",
"version": "1.10.0",
"timestamp": "2025-01-11T17:00:00.000Z",
"valid": false,
"errorCount": 2,
"alertCount": 1,
"errors": [
{
"path": "C4",
"field": "code | 1 | type",
"message": "Invalid code type"
}
],
"alerts": [
{
"path": "D5",
"field": "estimated_amount",
"message": "Nine 9s used for estimated amount"
}
]
}
`

$3

The two current allowable file formats for the HPT MRFs are CSV and JSON. The CLI will auto detect the file format passed into the tool for files that end with .csv or .json and will run the appropriate validator for that file. The CLI can also detect files compressed by gzip. Files ending with the .gz extension will be decompressed before validation. These file format detections can be combined, so files ending with .csv.gz or .json.gz will be decompressed and validated as CSV or JSON, respectively. For other files ending with .gz, use the -f option described above.

Limitations

There may be a situation in which the CLI tool will run out of memory due to the amount of errors that are found in the file being validated. If you run into this NODE error, update the amount of errors to a smaller value that will be allowed to be collected with the -e, --error-limit` flag.

Contributing

Thank you for considering contributing to an Open Source project of the US
Government! For more information about our contribution guidelines, see
CONTRIBUTING.md

Security

For more information about our Security, Vulnerability, and Responsible
Disclosure Policies, see SECURITY.md.

Authors and Maintainers

A full list of contributors can be found on https://github.cms.gov/CMSGov/hpt-validator-cli/graphs/contributors.

Public domain

This project is licensed within in the public domain within the United States,
and copyright and related rights in the work worldwide are waived through the
CC0 1.0 Universal public domain
dedication.

All contributions to this project will be released under the CC0 dedication. By
submitting a pull request or issue, you are agreeing to comply with this waiver
of copyright interest.