Skip to content

Refactor service_code to allow multiple patterns #883

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
clovis517 wants to merge 7 commits into from
Closed

Refactor service_code to allow multiple patterns #883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3c37877
Documentation Fix (#847)
shaselton-usds Oct 8, 2025
d6ebcfd
Refactor service_code to allow multiple patterns
clovis517 Dec 4, 2025
d1524c2
Update regex pattern for array items
clovis517 Dec 4, 2025
d95ae15
Update the service_code array pattern to constrain it to currently as…
clovis517 Dec 10, 2025
c7b8812
Updating Schema v2.0 (#886)
shaselton-usds Dec 19, 2025
f0a7c6b
Develop (#897)
shaselton-usds Jan 8, 2026
2de9e27
Merge branch 'CMSgov:master' into master
clovis517 Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions Gemfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,28 @@
GEM
remote: https://rubygems.org/
specs:
base64 (0.3.0)
bigdecimal (3.2.2)
diff-lcs (1.4.4)
bigdecimal (4.0.1)
diff-lcs (1.6.2)
hana (1.3.7)
json_schemer (2.2.1)
base64
json_schemer (2.5.0)
bigdecimal
hana (~> 1.3)
regexp_parser (~> 2.0)
simpleidn (~> 0.2)
regexp_parser (2.10.0)
rspec (3.10.0)
rspec-core (~> 3.10.0)
rspec-expectations (~> 3.10.0)
rspec-mocks (~> 3.10.0)
rspec-core (3.10.1)
rspec-support (~> 3.10.0)
rspec-expectations (3.10.1)
regexp_parser (2.11.3)
rspec (3.13.2)
rspec-core (~> 3.13.0)
rspec-expectations (~> 3.13.0)
rspec-mocks (~> 3.13.0)
rspec-core (3.13.6)
rspec-support (~> 3.13.0)
rspec-expectations (3.13.5)
diff-lcs (>= 1.2.0, < 2.0)
rspec-support (~> 3.10.0)
rspec-mocks (3.10.2)
rspec-support (~> 3.13.0)
rspec-mocks (3.13.7)
diff-lcs (>= 1.2.0, < 2.0)
rspec-support (~> 3.10.0)
rspec-support (3.10.3)
rspec-support (~> 3.13.0)
rspec-support (3.13.6)
simpleidn (0.2.3)

PLATFORMS
Expand Down
9 changes: 2 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,16 +93,12 @@ The associated names for those files are:
* `in-network-rates`
* `allowed-amounts`

There are also two optional machine-readable files that can be leveraged to significantly decrease file sizes of the required machine-readable files:
There is also one optional machine-readable file that can be leveraged to significantly decrease file sizes of the required machine-readable files:
* [Table of Contents](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/table-of-contents)
* [Provider Reference](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/provider-reference)

**Table of Contents File**
The Table of Contents file can be leveraged to combine common negotiated rates across multiple in-network files. By breaking out [common negotiated rates into separate files](https://github.com/CMSgov/price-transparency-guide/blob/master/README.md#multiple-plans-per-file) to use in multiple In-Network files, plans can avoid having to duplicate data.

**Provider Reference**
Defining provider networks outside of the In-Network file can have significant benefits in the overall file size that is produced. The provider reference file allows the user to define common provider networks externally to the In-Network file that can be referenced from within the In-Network file. This allows large provider networks to be defined once and be used in multiple locations.

Timing Updates For Machine-Readable Files
-----------------------------------------
According to the [TiC Final Rules](https://www.federalregister.gov/d/2020-24591/p-1516) and the schema requirements, plans and issuers are required to update the machine-readable files monthly and populate the attribute `last_updated_on`. The Departments consider “monthly” to refer to reasonably consistent periods of approximately 30 days, but are not specifying a particular day of the month.
Expand Down Expand Up @@ -141,14 +137,13 @@ For example, the following would be the required naming for CMS building a JSON
Schema Validator Tool
=====================

CMS developed a [downloadable schema validator tool](https://github.com/CMSgov/price-transparency-guide-validator) that plans and developers can use to assess whether their machine readable files are compliant with the Transparency in Coverage JSON schema. The validator tool and instructions can be accessed here. The tool can be used to validate in-network and allowed amount files, as well as provider references and table of contents files. Note that the tool tests for attributes required under version 1.0 of the JSON schema and for syntax errors, but does not test the accuracy of the data in the schema. It is designed to run on local computers and can be used to validate files of any size (there is no file size limit). At this point in time, the validator tool can only be used to validate JSON files.
CMS developed a [downloadable schema validator tool](https://github.com/CMSgov/price-transparency-guide-validator) that plans and developers can use to assess whether their machine readable files are compliant with the Transparency in Coverage JSON schema. The validator tool and instructions can be accessed here. The tool can be used to validate in-network and allowed amount files, as well as table of contents files. Note that the tool tests for attributes required under version 1.0 of the JSON schema and for syntax errors, but does not test the accuracy of the data in the schema. It is designed to run on local computers and can be used to validate files of any size (there is no file size limit). At this point in time, the validator tool can only be used to validate JSON files.

Schemas
=======
* [In-Network Rates](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/in-network-rates)
* [Allowed Amounts](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/allowed-amounts)
* [Table of Contents](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/table-of-contents)
* [Provider Reference](https://github.com/CMSgov/price-transparency-guide/tree/master/schemas/provider-reference)

Examples
========
Expand Down
2 changes: 1 addition & 1 deletion VERSION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.6.2
2.1.0
2 changes: 1 addition & 1 deletion examples/allowed-amounts/allowed-amounts-multiple-plan-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"reporting_entity_name": "cms",
"reporting_entity_type": "cms",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"out_of_network": [
{
"name": "Established Patient Office or Other Outpatient Services",
Expand Down
2 changes: 1 addition & 1 deletion examples/allowed-amounts/allowed-amounts-single-plan-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"plan_id": "1111111111",
"plan_market_type": "individual",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"out_of_network": [
{
"name": "Established Patient Office or Other Outpatient Services",
Expand Down
208 changes: 208 additions & 0 deletions examples/in-network-rates/in-network-rates-all-negotiated-types-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
{
"reporting_entity_name": "Comprehensive Health Insurance",
"reporting_entity_type": "health insurance issuer",
"plan_name": "Plan D PPO",
"issuer_name": "Comprehensive Health Issuer",
"plan_sponsor_name": "Comprehensive Employee Group",
"plan_id_type": "ein",
"plan_id": "4444444444",
"plan_market_type": "group",
"last_updated_on": "2024-01-15",
"version": "2.0.0",
"provider_references": [
{
"provider_group_id": 1,
"network_name": ["Comprehensive Health Network"],
"provider_groups": [
{
"npi": [1234567890, 2345678901, 3456789012],
"tin": {
"type": "ein",
"value": "12-3456789",
"business_name": "Premier Medical Associates"
}
},
{
"npi": [4567890123],
"tin": {
"type": "ein",
"value": "23-4567890",
"business_name": "Regional Healthcare Group"
}
}
]
},
{
"provider_group_id": 2,
"network_name": ["Comprehensive Health Plus Network"],
"provider_groups": [
{
"npi": [5678901234, 6789012345],
"tin": {
"type": "ein",
"value": "34-5678901",
"business_name": "City General Hospital"
}
}
]
}
],
"in_network": [
{
"negotiation_arrangement": "ffs",
"name": "Office Visit, Established Patient, Moderate Complexity",
"billing_code_type": "CPT",
"billing_code_type_version": "2024",
"billing_code": "99214",
"description": "Office or other outpatient visit for evaluation and management of an established patient",
"negotiated_rates": [
{
"provider_references": [1],
"negotiated_prices": [
{
"setting": "outpatient",
"negotiated_type": "negotiated",
"negotiated_rate": 150.00,
"expiration_date": "2024-12-31",
"service_code": ["11"],
"billing_class": "professional",
"additional_information": "Standard negotiated rate for established patient office visits"
}
]
}
]
},
{
"negotiation_arrangement": "ffs",
"name": "Outpatient Physical Therapy",
"billing_code_type": "CPT",
"billing_code_type_version": "2024",
"billing_code": "97110",
"description": "Therapeutic exercises to develop strength, endurance, range of motion and flexibility",
"negotiated_rates": [
{
"provider_references": [1],
"negotiated_prices": [
{
"setting": "outpatient",
"negotiated_type": "percentage",
"negotiated_rate": 65.0,
"expiration_date": "2024-12-31",
"service_code": ["11", "22"],
"billing_class": "professional",
"additional_information": "65% of billed charges arrangement"
}
]
}
]
},
{
"negotiation_arrangement": "ffs",
"name": "Medical/Surgical Intensive Care Unit (ICU) Daily Rate",
"billing_code_type": "RC",
"billing_code_type_version": "2024",
"billing_code": "0200",
"description": "Intensive Care Unit - General Classification",
"negotiated_rates": [
{
"provider_references": [2],
"negotiated_prices": [
{
"setting": "inpatient",
"negotiated_type": "per diem",
"negotiated_rate": 5500.00,
"expiration_date": "2024-12-31",
"billing_class": "institutional",
"additional_information": "Daily per diem rate for ICU stay"
}
]
}
]
},
{
"negotiation_arrangement": "ffs",
"name": "Laboratory Test - Comprehensive Metabolic Panel",
"billing_code_type": "CPT",
"billing_code_type_version": "2024",
"billing_code": "80053",
"description": "Comprehensive metabolic panel blood test",
"negotiated_rates": [
{
"provider_references": [1],
"negotiated_prices": [
{
"setting": "outpatient",
"negotiated_type": "derived",
"negotiated_rate": 45.00,
"expiration_date": "2024-12-31",
"service_code": ["11", "81"],
"billing_class": "professional",
"additional_information": "Derived price for internal accounting and reconciliation purposes"
}
]
}
]
},
{
"negotiation_arrangement": "ffs",
"name": "Knee Replacement Surgery",
"billing_code_type": "CPT",
"billing_code_type_version": "2024",
"billing_code": "27447",
"description": "Arthroplasty, knee condyle and plateau, medial and lateral compartments",
"negotiated_rates": [
{
"provider_references": [1, 2],
"negotiated_prices": [
{
"setting": "inpatient",
"negotiated_type": "fee schedule",
"negotiated_rate": 8500.00,
"expiration_date": "2024-12-31",
"service_code": ["21", "22"],
"billing_class": "professional",
"additional_information": "Fee schedule rate used to determine participant cost-sharing liability"
},
{
"setting": "inpatient",
"negotiated_type": "negotiated",
"negotiated_rate": 12000.00,
"expiration_date": "2024-12-31",
"billing_class": "institutional"
}
]
}
]
},
{
"negotiation_arrangement": "ffs",
"name": "Emergency Department Visit, High Severity",
"billing_code_type": "CPT",
"billing_code_type_version": "2024",
"billing_code": "99285",
"description": "Emergency department visit for evaluation and management of a patient with high severity",
"negotiated_rates": [
{
"provider_references": [2],
"negotiated_prices": [
{
"setting": "outpatient",
"negotiated_type": "percentage",
"negotiated_rate": 75.5,
"expiration_date": "2024-12-31",
"service_code": ["23"],
"billing_class": "professional"
},
{
"setting": "outpatient",
"negotiated_type": "negotiated",
"negotiated_rate": 2500.00,
"expiration_date": "2024-12-31",
"billing_class": "institutional"
}
]
}
]
}
]
}
2 changes: 1 addition & 1 deletion examples/in-network-rates/in-network-rates-bundle-single-plan-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
"plan_id": "0000000000",
"plan_market_type": "individual",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"provider_references": [
{
"provider_group_id": 1,
Expand Down
3 changes: 2 additions & 1 deletion examples/in-network-rates/in-network-rates-capitation-single-plan-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
"reporting_entity_name": "cms",
"reporting_entity_type": "cms",
"plan_name": "medicaid",
"issuer_name": "CMS Medicaid Issuer",
"plan_id_type": "hios",
"plan_id": "1111111111",
"plan_market_type": "individual",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"provider_references": [
{
"provider_group_id": 1,
Expand Down
2 changes: 1 addition & 1 deletion examples/in-network-rates/in-network-rates-fee-for-service-single-plan-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"plan_id": "1111111111",
"plan_market_type": "group",
"last_updated_on": "2020-08-27",
"version": "1.2.0",
"version": "2.0.0",
"provider_references": [
{
"provider_group_id": 1,
Expand Down
2 changes: 1 addition & 1 deletion examples/in-network-rates/in-network-rates-multiple-plans-sample.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"reporting_entity_name": "cms",
"reporting_entity_type": "cms",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"provider_references":[{
"provider_group_id": 1,
"network_name": ["ACME Choice Provider Group"],
Expand Down
4 changes: 2 additions & 2 deletions examples/in-network-rates/in-network-rates-no-npi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"plan_id": "1111111111",
"plan_market_type": "individual",
"last_updated_on": "2020-08-27",
"version": "1.0.0",
"version": "2.0.0",
"provider_references": [
{
"provider_group_id": 1,
Expand All @@ -18,7 +18,7 @@
"npi": [1111111111],
"tin": {
"type": "npi",
"value": "0"
"value": "1234567890"
}
}
]
Expand Down
16 changes: 0 additions & 16 deletions examples/provider-reference/provider-reference.json
View file
Open in desktop

This file was deleted.

6 changes: 3 additions & 3 deletions schemas/allowed-amounts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
| **reporting_entity_type** | Entity Type | String | The type of entity that is publishing the machine-readable file (a group health plan, health insurance issuer, or a third party with which the plan or issuer has contracted to provide the required information, such as a third-party administrator, a health care claims clearinghouse, or a health insurance issuer that has contracted with a group health plan sponsor). | Yes |
| **issuer_name** | Issuer Name | String | The name of the plan's issuer. | No |
| **plan_name** | Plan Name | String | The plan's name. | No |
| **plan_id_type** | Plan Id Type | String | Allowed values: "EIN" and "HIOS" | No |
| **plan_id** | Plan ID | String | The 10-digit Health Insurance Oversight System (HIOS) identifier, or, if the 10-digit HIOS identifier is not available, the 5-digit HIOS identifier, or if no HIOS identifier is available, the Employer Identification Number (EIN)for each plan or coverage offered by a plan or issuer. | No |
| **plan_sponsor_name** | Plan Sponsor Name | String | If the `plan_id_type` is "EIN", the common business name of the plan sponsor | No |
| **plan_id_type** | Plan Id Type | String | Allowed values: "ein" and "hios" | No |
| **plan_id** | Plan ID | String | The 10-digit Health Insurance Oversight System (HIOS) identifier, or, if the 10-digit HIOS identifier is not available, the 5-digit HIOS identifier, or if no HIOS identifier is available, the Employer Identification Number (EIN) for each plan or coverage offered by a plan or issuer. | No |
| **plan_sponsor_name** | Plan Sponsor Name | String | If the `plan_id_type` is "ein", the common business name of the plan sponsor | No |
| **plan_market_type** | Market Type | String | Allowed values: "group" and "individual" | No |
| **out_of_network** | Out Of Network | Array | An array of [out-of-network object types](#out-of-network-object) | Yes |
| **last_updated_on** | Last Updated On | String | The date in which the file was last updated. Date must be in an ISO 8601 format (i.e. YYYY-MM-DD) | Yes |
Expand Down
Loading
Loading