Upcoming v3.0 Development and Release Process

[shaselton-usds]

Upcoming v3.0 Development and Release Process

Again, exciting news, everyone!

With the Transparency in Coverage 2026 final rule now published, it's time to start on the next major version of the TiC schema. Just as we did for v2.0 (#781), I wanted to use this space to outline the development, branching, merging, and release strategy for v3.0, and to gather feedback from the community and contributors. The process will look familiar. We've also made a few changes based on what we learned during v2.x, described below. As always, we encourage your questions, comments, and suggestions.

Background

The Departments published the Transparency in Coverage final rule on October 6, 2026 (91 FR 63748), following the proposed rule from December 2025 (CMS-9882-P). The final rule changes what the machine-readable files must contain and how they are organized, and many of those changes can't be expressed in the v2.x schema. That makes this a major version: v3.0 will include breaking changes across the files.

Here's a high-level summary of what v3.0 needs to support:

• In-network Rate Files organized by provider network, with a common provider network name and a provider network identifier along with plan and policy information (name, HIOS ID or EIN, product type) will be found in the Table of Contents.
• Allowed Amount Files organized by health insurance market, covering a six-month reporting period that begins nine months before publication, with a new 11-claim threshold minimum.
• Three new contextual files: a Utilization File, a Taxonomy File, and a plain text file at the website's root directory.
• An attestation in each machine-readable file, encoding the name of the official responsible for the data.
• Quarterly updates for the In-network Rate and Allowed Amount Files.
• JSON as the single file format. Consistent with the final rule's requirement for a single, non-proprietary, open-standards format, v3.0 will be published as JSON only.

As with v2.0, many of the schema changes also come from your observations of current MRFs and from stakeholder feedback. Beyond the rule's requirements, our goals for v3.0 are to make files more consistently valid, more reliably comparable across plans and issuers, and easier to validate in a streaming pipeline.

Development Process: Branching and Isolation

The main goal during this time is to keep v2.x stable while v3.0 is under development. This follows the same approach as v2.0. While it generally follows standard development lifecycle practices, minor deviations may occur. You can expect development to largely look like this:

Branching Strategy

Master Branch

• The master branch will continue to host the stable v2.x schema for all of the MRFs. v2.x remains the required schema until the final rule's applicability dates.
• Only critical bug fixes and security patches will be merged here. Each will result in a minor/patch release and a new tag.

Develop Branch

• The develop branch will continue to be the staging branch for master and the current v2.x.

v3.0 Development Branch

• develop-v3.0 will be the primary development branch for v3.0 updates.
• All new features, breaking changes, and v3.0 updates will be committed to (or merged into) this branch.
• Feature branches for individual v3.0 updates will be created off develop-v3.0 and merged back upon completion and review.
• Each file will have its own feature branch, named v3.0/<file> to match the schema's directory, and its own pull request into develop-v3.0:
  • v3.0/table-of-contents
  • v3.0/in-network-rates
  • v3.0/allowed-amounts
  • v3.0/utilization
  • v3.0/taxonomy
• Changes that apply to every file (such as the attestation and shared definitions) will go through their own pull request, v3.0/shared, and merge first, so that each file's pull request builds on them instead of repeating them.
• Merging into develop-v3.0 does not mean a schema is final. Files remain open to change until the first release candidate is cut, and feedback after a merge can be raised as an issue or a new pull request against develop-v3.0.
• Contributors outside CMS are welcome to propose changes by opening a pull request from a fork against develop-v3.0 or against any of the feature branches above.
• Versions apply to the repository as a whole, not to individual schemas. The Utilization and Taxonomy Files are new in v3, and they start at the repository version in which they are first released, not at 1.0.
• Each file's schema will be opened as a pull request against develop-v3.0, with its README, examples, and validator changes in the same pull request. Schema-specific feedback is best left on that file's pull request, and feedback on the process is welcome here.

Release Candidates (RC) and Final v3.0.0 Release

• When the develop-v3.0 branch is deemed production-ready, a release candidate (e.g. 3.0.0-rc.1) will be cut from develop-v3.0.
• These RCs are intended for final review and testing.
• Once the RC is stable and passes all final checks, the develop-v3.0 branch will be merged into master.
• The master branch will be tagged as v3.0.0 and a new release will be cut.

Timeline

The final rule applies in two phases, and v3.0 development will follow the same order. Schema 3.0 will be delivered in two releases: v3.0.0 for the Phase 1 files, and v3.1.0 adding the Phase 2 files.

Phase	Applies	Files	First posting
1	March 6, 2027	Table of Contents, In-network Rate, Allowed Amount, and the attestation	April 1, 2027, then quarterly
2	September 6, 2027	Taxonomy File and root text file	October 1, 2027
		Utilization File	July 1, 2028, then annually

What's in each phase

Phase	File	What changes	Release
1	Table of Contents	Lists each plan's name, HIOS ID or EIN, and product type, and links each plan to its provider networks and each network to its In-network Rate Files	v3.0.0
1	In-network Rate File	One file per provider network, with a common network name and network identifier; percentage-of-billed-charges rates; excludes provider-rate combinations unlikely to be reimbursed given the provider's specialty	v3.0.0
1	Allowed Amount File	One file per health insurance market; six-month reporting period beginning nine months before publication; 11-claim threshold	v3.0.0
1	All files	Attestation and the name of the official responsible; JSON only; quarterly updates for the In-network Rate and Allowed Amount Files	v3.0.0
2	In-network Rate File	Outlier, stop-loss, and similar payment provisions (payment_provisions) are reported. The fields are already in v3.0.0 as optional; see the note below.	v3.0.0 (optional), v3.1.0 (required)
2	Taxonomy File	New: the plan's or issuer's mapping of billing codes to provider specialties (NUCC taxonomy codes) used to exclude unlikely provider-rate combinations	v3.1.0
2	Utilization File	New: providers reimbursed for each item or service in the most recent plan year	v3.1.0
2	Root text file	New: a .txt file at the website's root with the source page URL, a direct link to the files, and a point of contact	v3.1.0

Why payment provisions are in v3.0.0 but required in Phase 2. The fields for outlier, stop-loss, and similar provisions are part of the v3.0.0 In-network Rate schema as optional fields. Including these fields now shows users the full structure they will be building toward and allows files that are ready to report them early. Because the fields are already in place, v3.1.0 makes no structural change to them; Phase 2 only makes reporting them expected.

Phase 2 also requires a "Price Transparency" or "Transparency in Coverage" link in the website footer. That is a website requirement, not a schema change.

Draft schemas for each phase will be available at the start of that phase's development window, so that you can begin building before each release is finalized. Phase 1's window is already open: the v3.0/shared, v3.0/table-of-contents, v3.0/in-network-rates, and v3.0/allowed-amounts branches come first.

Closing Thoughts

We welcome your thoughts and questions on this process, and your involvement in the development of v3.0.0. Thank you for all of your contributions in this next phase of development, and for the feedback on v2.x that shaped much of what's coming.

[tdfow]

@shaselton-usds thanks for sharing the branch information. Just to confirm, what is being addressed in Phase 1's window? Should we only being seeing the structure of deveop-v3.0 and v3.0/table-of-contents or will the other branches be expected? It seems the 2.0 information has been copied to the develop-v3.0 but not seeing any update information. I do see updates in v3.0/table-of-contents. Should we see the other drafts in Phase 1?

[shaselton-usds]

Hi @tdfow!

Yes, you will see the changes initially in the specific branches and will eventually make its way into the actual develop-v3.0 branch.

Here are all the current v3.0 branches that you can start to go through and provide feedback on:

[Orange-1234]

Will there be a meeting scheduled any time soo to discuss v3.0?

[JR-CMS]

Yes, we just finalized our webinar series for Schema version 3.0. Please see more information here: https://regtap.cms.gov/reg_events_view.php?class=779

[clovis517]

Thanks @shaselton-usds !

How do we go about requesting changes or additions to the valid values?

Initial ask : add "estimated loss" and "estimated operating loss" to the valid values for "threshold_measure" and "payment_basis".
Example of the type of payment_provision this would support:
"80% of Estimated DRG operating loss exceeding $50,000"
where Estimated DRG Operating Loss = DRG Operating Amount (DRG Weight * Operating Rate) minus operating "cost_to_charge_ratio" object * billed (covered) charges.

[shaselton-usds]

Hi @clovis517!

The Phase 1 schemas have been posted to their respective development branches v3.0/<file>, so take a look there for some of the changes.

You are more than welcome and encouraged to requesting changes or make suggestions. It will only help. You can either open a discussion, open an issue and point to the appropriate branch. Let me know if you need anymore help on this front.

[tdfow]

@shaselton-usds @JR-CMS When will the CMS Schema Validator changes be available for schema 3.0.0?

[shaselton-usds]

The current validator works off of tagged versions of the schema. Following that process, we can expect the validator to be available to validate v3.0 files when the schema is locked down and tagged for release.

[tdfow]

I hope that CMS realizes the issues and risks to the community for not having finalized versions of the schemas for 3.0 until the February date to align with having schema 3.0 in production for disclosure on April 1, 2027.
I would think for the majority of the community, this means changes to support all applicable schemas for April would need to be "production ready" by Feb/March timeframe, which shortens the window even to a small window.

With CMS not having finalized schemas, examples and other guidance not available until Feb or later then the community must rely on getting insights/drafts of proposed schemas in October (this month) to assess and then CMS will have a webinar on November 5 to share 3.0 schema information. How much time has CMS allotted for having all the guidance defined? You would think that the clock for the applicability date would taken the availability of the 'final' schemas into consideration before setting an applicability date.

Will CMS consider future changes to potentially publish the draft schemas with any future MRF proposals? This approach would at least prepare the community if these short timelines are given on final rules. Until there are draft schemas, the community can't perform appropriate analysis and begin conversations to get clarity to identify all the impacted components, the database needs, the changes needed to support two major versions, to obtain the source information for 'newly' introduced topics that were not in the prior version, etc.

Can CMS provide their feedback on the likelihood of changes from draft to final based on the information posted to date in the /v3.0 drafts?

I would hope that CMS in the future will have considerations to either publish the draft schemas to accompany a proposal for new or major schema version changes or provide a reasonable timeline to implement major changes. I also feel the commentors should be noted as to whether they are representing the producers or consumers, as consumers always want the files early, whereas the producers understand the effort to implement, test and support proposed changes.

[tdfow]

@shaselton-usds @JR-CMS For analysis purposes, when will the initial drafts for taxonomy and utilization be available, as it is important to see potential gaps in data needs while we are addressing the other drafted schema requirements to help us identify data needs for these files. At least if we have rough drafts---it is better than assumptions we are guessing. As with the other files 3.0 schemas, there were many new fields added to the schema that were not really referenced in the proposal---and until you see how the data is organized, you may still have additional changes to consider. Appreciate any 'early' insights to these new files.