How to Structure Your Machine-Readable Files

TechnicalMay 22, 2025•10 min read

Creating a compliant machine-readable pricing file can be challenging, especially for IT teams and vendors who may not be familiar with healthcare compliance requirements. This technical guide provides detailed specifications and examples for creating files that meet CMS standards.

File Format Options

CMS accepts three formats:

  1. JSON (Recommended) - Most structured and validated
  2. CSV - Acceptable but requires careful formatting
  3. XML - Less common but allowed

This guide focuses on JSON as it's the most reliable format and has clear schema validation.

JSON Schema Overview

CMS provides a JSON schema that your file should validate against. Here's the basic structure:

{
  "hospital_name": "string",
  "last_updated_on": "YYYY-MM-DD",
  "version": "string",
  "hospital_location": ["string"],
  "hospital_address": "string",
  "license_information": {
    "license_number": "string",
    "state": "string"
  },
  "affirmation": {
    "affirmation": "boolean",
    "confirm_affirmation": "boolean"
  },
  "standard_charge_information": [
    {
      "description": "string",
      "drug_unit_of_measurement": "string",
      "drug_type_of_measurement": "string",
      "code_information": [
        {
          "code": "string",
          "type": "string"
        }
      ],
      "standard_charges": [
        {
          "minimum": "number",
          "maximum": "number",
          "gross_charge": "number",
          "discounted_cash_price": "number",
          "setting": "string",
          "payers_information": [
            {
              "payer_name": "string",
              "plan_name": "string",
              "standard_charge_dollar": "number",
              "standard_charge_percentage": "number",
              "standard_charge_algorithm": "string",
              "estimated_amount": "number",
              "methodology": "string",
              "billing_class": "string",
              "additional_payer_notes": "string"
            }
          ]
        }
      ]
    }
  ]
}

Required Fields Breakdown

Hospital Metadata (File Header)

{
  "hospital_name": "Memorial General Hospital",
  "last_updated_on": "2025-09-28",
  "version": "2.1.0",
  "hospital_location": ["San Francisco, CA"],
  "hospital_address": "123 Medical Plaza Drive, San Francisco, CA 94102",
  "license_information": {
    "license_number": "CA-123456",
    "state": "CA"
  },
  "affirmation": {
    "affirmation": true,
    "confirm_affirmation": true
  }
}

Key Points:

  • last_updated_on must be ISO 8601 date format (YYYY-MM-DD)
  • hospital_location is an array (can have multiple locations)
  • affirmation fields confirm accuracy of data

Standard Charge Information

Each item/service needs these elements:

1. Description

"description": "Emergency Department Visit - Level 3 (Moderate Severity)"

Must be plain language that average consumer can understand. Avoid medical jargon when possible.

2. Billing Codes

"code_information": [
  {
    "code": "99283",
    "type": "CPT"
  }
]

Supported code types:

  • CPT (Current Procedural Terminology)
  • HCPCS (Healthcare Common Procedure Coding System)
  • DRG (Diagnosis Related Group)
  • MS-DRG
  • R-DRG
  • S-DRG
  • APC (Ambulatory Payment Classification)
  • NDC (National Drug Code)
  • HIPPS
  • LOCAL (hospital-specific codes)

3. Drug Information (if applicable)

"drug_unit_of_measurement": "ML",
"drug_type_of_measurement": "administered"

Required for pharmaceutical items. Common units: ML, MG, EACH, VIAL

4. Standard Charges

This is the most complex and critical section:

"standard_charges": [
  {
    "setting": "inpatient",
    "minimum": 450.00,
    "maximum": 1250.00,
    "gross_charge": 850.00,
    "discounted_cash_price": 680.00,
    "payers_information": [
      {
        "payer_name": "Blue Cross Blue Shield",
        "plan_name": "PPO Gold Plan",
        "standard_charge_dollar": 595.00,
        "methodology": "fee schedule",
        "billing_class": "professional"
      },
      {
        "payer_name": "Aetna",
        "plan_name": "HMO Standard",
        "standard_charge_dollar": 625.00,
        "methodology": "negotiated rate",
        "billing_class": "professional"
      }
    ]
  }
]

Required Elements:

  • minimum: De-identified lowest negotiated rate
  • maximum: De-identified highest negotiated rate
  • gross_charge: Chargemaster/list price
  • discounted_cash_price: Self-pay discount rate
  • payers_information: Actual negotiated rates for each payer

Common Mistake: Showing only gross_charge without payer-specific rates. This will trigger enforcement.

Complete Example: Emergency Services

{
  "hospital_name": "Memorial General Hospital",
  "last_updated_on": "2025-09-28",
  "version": "2.1.0",
  "hospital_location": ["San Francisco, CA"],
  "hospital_address": "123 Medical Plaza Drive, San Francisco, CA 94102",
  "license_information": {
    "license_number": "CA-123456",
    "state": "CA"
  },
  "affirmation": {
    "affirmation": true,
    "confirm_affirmation": true
  },
  "standard_charge_information": [
    {
      "description": "Emergency Department Visit - Level 3 (Moderate Severity)",
      "code_information": [
        {
          "code": "99283",
          "type": "CPT"
        }
      ],
      "standard_charges": [
        {
          "setting": "outpatient",
          "minimum": 450.00,
          "maximum": 1250.00,
          "gross_charge": 850.00,
          "discounted_cash_price": 680.00,
          "payers_information": [
            {
              "payer_name": "Blue Cross Blue Shield",
              "plan_name": "PPO Gold",
              "standard_charge_dollar": 595.00,
              "methodology": "fee schedule",
              "billing_class": "professional"
            },
            {
              "payer_name": "Aetna",
              "plan_name": "HMO Standard",
              "standard_charge_dollar": 625.00,
              "methodology": "negotiated rate",
              "billing_class": "professional"
            },
            {
              "payer_name": "Medicare",
              "plan_name": "Traditional Medicare",
              "standard_charge_dollar": 485.00,
              "methodology": "fee schedule",
              "billing_class": "professional"
            },
            {
              "payer_name": "Medicaid",
              "plan_name": "Medi-Cal",
              "standard_charge_dollar": 425.00,
              "methodology": "fee schedule",
              "billing_class": "professional"
            }
          ]
        }
      ]
    },
    {
      "description": "Basic Metabolic Panel Blood Test (8 tests)",
      "code_information": [
        {
          "code": "80048",
          "type": "CPT"
        }
      ],
      "standard_charges": [
        {
          "setting": "outpatient",
          "minimum": 25.00,
          "maximum": 95.00,
          "gross_charge": 75.00,
          "discounted_cash_price": 45.00,
          "payers_information": [
            {
              "payer_name": "Blue Cross Blue Shield",
              "plan_name": "PPO Gold",
              "standard_charge_dollar": 35.00,
              "methodology": "fee schedule",
              "billing_class": "professional"
            },
            {
              "payer_name": "Aetna",
              "plan_name": "HMO Standard",
              "standard_charge_dollar": 38.00,
              "methodology": "negotiated rate",
              "billing_class": "professional"
            }
          ]
        }
      ]
    }
  ]
}

Technical Implementation Tips

1. Data Sources

Most hospitals pull pricing data from:

  • Chargemaster system: For gross charges
  • Contract management system: For payer-specific rates
  • Patient accounting system: For cash prices
  • Coding database: For CPT/HCPCS codes

2. Automation

Generate files programmatically rather than manually:

Python Example:

import json
from datetime import date

def generate_pricing_file(hospital_data, pricing_data):
    output = {
        "hospital_name": hospital_data["name"],
        "last_updated_on": date.today().isoformat(),
        "version": "2.1.0",
        "hospital_location": hospital_data["locations"],
        "standard_charge_information": []
    }

    for item in pricing_data:
        charge_item = {
            "description": item["description"],
            "code_information": item["codes"],
            "standard_charges": [{
                "gross_charge": item["gross"],
                "discounted_cash_price": item["cash"],
                "minimum": item["min_rate"],
                "maximum": item["max_rate"],
                "payers_information": item["payers"]
            }]
        }
        output["standard_charge_information"].append(charge_item)

    return json.dumps(output, indent=2)

3. Validation

Before publishing, validate your JSON:

Using online validators:

  • JSONLint.com
  • jsonformatter.org

Using command line:

# Python
python -m json.tool pricing.json

# Node.js
node -e "JSON.parse(require('fs').readFileSync('pricing.json', 'utf8'))"

4. File Size Considerations

Large hospitals may have files exceeding 100MB. Optimize by:

  • Compressing with gzip (serve as .json.gz)
  • Splitting into multiple files (by department or service type)
  • Using efficient encoding (avoid excessive whitespace)

But ensure compression doesn't require special tools to access.

5. Hosting Requirements

  • Direct access: File must be directly downloadable
  • No authentication: No login or API keys required
  • HTTPS: Secure connections recommended
  • CORS headers: Allow cross-origin requests
  • Proper MIME type: application/json

Example nginx config:

location /pricing.json {
    add_header Access-Control-Allow-Origin *;
    add_header Content-Type application/json;
    add_header Cache-Control "public, max-age=3600";
}

Common Technical Errors

Error 1: Trailing Commas

{
  "field": "value",   // ❌ Trailing comma
}

Error 2: Single Quotes

{
  'field': 'value'  // ❌ Use double quotes
}

Error 3: Numbers as Strings

{
  "gross_charge": "850.00"  // ❌ Should be number
}

Correct:

{
  "gross_charge": 850.00  // ✓ Numeric type
}

Error 4: Missing Required Fields

Always include minimum, maximum, gross_charge, discounted_cash_price, and payers_information.

Testing Your File

Before going live:

  1. Validate JSON syntax
  2. Check all required fields present
  3. Test external accessibility (from outside your network)
  4. Verify file downloads directly
  5. Check file size is reasonable
  6. Test on mobile devices

Maintenance

Files require ongoing maintenance:

  • Update when contracts change: Don't wait for annual deadline
  • Monitor for accessibility: Files can break due to web updates
  • Track regulatory changes: CMS may update requirements
  • Version control: Keep history of all file versions
  • Regular validation: Check weekly at minimum

Resources

  • CMS JSON Schema: cms.gov/files/zip/hospitalstandardchargedatafilejsonschema.zip
  • Sample files: cms.gov/hospital-price-transparency-resources
  • Technical FAQ: cms.gov/hospital-price-transparency-faq

Conclusion

Creating compliant machine-readable files requires attention to technical detail, but following this structure will ensure your hospital meets CMS requirements and avoids costly violations. Automate where possible, validate regularly, and maintain detailed documentation of your process.

← Back to all articles

Stay Compliant with HealthPriceWatch

Avoid costly CMS penalties with automated daily compliance monitoring. Get alerted to issues before CMS does.

Start Your Free Audit