-
Notifications
You must be signed in to change notification settings - Fork 10
Feature: definitions
Note (August 2021): We were working on this feature concept in February 2021 and decided to postpone it! The pre-existing open source eRegs code that we started with had an automated method for identifying and displaying definitions for key terms, but the more we studied it, the more we realized that this method was not going to be sufficiently accurate for CMCS eRegs. Easy access to definitions was also relatively low on the priority list for most of the CMCS staff we talked to - helpful, but not essential. So we paused on this concept instead of pursuing it during the pilot phase.
Note (February 2023): We also did an experiment in February 2022 to add terms & definitions as supplemental content in 42 CFR 435. We didn't have a way to keep those items up-to-date, so we've marked them unapproved in our supplemental content database.
In scope: words defined in the reg itself.
Out of scope: Lots of words in regs might be useful to explain/define that aren’t formally defined in the reg itself.
- Comparative review: how other eRegs instances do definitions
- "Definitions" tag in our research repository + collected insight from research
Readers of CMCS regs need to know what specific terms mean as defined by the regulation that they’re looking at, in order to properly interpret the reg.
This especially applies when they’re reading an individual section or paragraph that includes terms that were defined much earlier in the reg, they need to know (once within a section) that the term was defined - and an experienced reader may know, but a new reader may not.
Sometimes the reg says for a specific term “as defined by x (part, subpart, section)” to give clear context. Often it doesn’t.
- We believe that: giving people an indication that a term has an official definition within the reg (and what the definition is or how to find it)
- For: most people reading regs, especially people who are less familiar with the piece that they're reading (whether they're learning to read regs in general, or whether they're not familiar with that specific piece)
- Will result in: more confidence and more accurate interpretations
- We will know we are right when: less experienced people can find the definitions + more experienced people consider the definitions accurate
- The way that eRegs does definitions (precise matching with denylisting specific terms) has too much risk of misleading definitions. We want to (at minimum) do allowlisting instead.
Regulation writers spend a lot of energy on defining specific words as part of their efforts to provide a specific interpretation to people who need to implement them. Sometimes the definitions are counter-intuitive or really subtle and context-specific, so as a reader trying to understand regulations, you need to know the definitions.
In the specific case of CMCS, it does not want ambiguity in how it instructs states, because different interpretations and applications among different states could cause a lot of confusion.
It’s common for a word in the middle of a reg to have been defined in an earlier section, and it can be non-obvious to the reader that this word has a specific definition anywhere, unless it’s specifically taught or shown to the reader to look for definitions.
For example, an experienced reader may print out the list of definitions to have at hand while reading a reg, similar to how they may print out a related reg to cross-reference while reading a reg. This is part of the complex (and often unwieldy) manual cross-referencing involved in reading a reg with existing tooling.
You typically don’t read the definitions section as a whole - you reference it from other sections.
Some titles provide a mega-list of general definitions for a whole chapter (that contains many parts). This is general background knowledge / context for reading the rest of the parts.
Examples:
- Title 42 Chapter IV (“Centers for Medicare & Medicaid Services, Department of Health and Human Services”) starts with Part 400, which contains definitions for Chapter IV. There is no other content in that part. This includes section 400.200, which says “In this chapter, unless the context indicates otherwise” and provides a list of definitions. Interesting note: 400.202 and 400.203 have two different definitions for the same term ("services"), because they are context-specific definitions.
Many regulation parts include a list of definitions for key terms at the beginning of the part. These lists provide specific interpretations of those words for the rest of the regulation part.
Examples:
- In Title 42 Part 435, Subpart A is “General Provisions and Definitions”, and section 435.4 is “Definitions and use of terms.”
- In Title 27 Part 447, Subpart B is “Definitions”, and section 447.11 is “Meaning of terms.”
Some regulation subparts include a list of definitions for that particular subpart.
We haven’t seen any examples of these definitions being in conflict with definitions for the rest of the part -- they’re just more relevant to that particular subpart.
Two patterns we’ve seen: there’s a general list of definitions for the part near the beginning of the part (like 435), or there’s a more specific list of definitions within each subpart (like 433). We haven’t seen both in one part.
Examples:
- In Title 42 Part 433 Subpart B Section 433.52 (“General definitions”), it says “As used in this subpart” and provides definitions.
Some regulation sections include a list of definitions for that particular section.
Examples:
- In Title 42 Part 435 Section 435.603, there is a list of definitions framed as “For purposes of this section”. These definitions are a critical part of this section because the precise definition and interpretation of MAGI determines eligibility for many groups of people. The word "child" has a specific definition in this section that does not necessarily apply to uses of the word "child" in other sections of this part. Note also that "Tax dependent" is defined as a cross-reference to the main definitions list for Part 435: “has the meaning provided in § 435.4 of this part.”
Please note that all pages on this GitHub wiki are draft working documents, not complete or polished.
Our software team puts non-sensitive technical documentation on this wiki to help us maintain a shared understanding of our work, including what we've done and why. As an open source project, this documentation is public in case anything in here is helpful to other teams, including anyone who may be interested in reusing our code for other projects.
For context, see the HHS Open Source Software plan (2016) and CMS Technical Reference Architecture section about Open Source Software, including Business Rule BR-OSS-13: "CMS-Released OSS Code Must Include Documentation Accessible to the Open Source Community".
For CMS staff and contractors: internal documentation on Enterprise Confluence (requires login).
- Federal policy structured data options
- Regulations
- Resources
- Statute
- Citation formats
- Export data
- Site homepage
- Content authoring
- Search
- Timeline
- Not built
- 2021
- Reg content sources
- Default content view
- System last updated behavior
- Paragraph indenting
- Content authoring workflow
- Browser support
- Focus in left nav submenu
- Multiple content views
- Content review workflow
- Wayfinding while reading content
- Display of rules and NPRMs in sidebar
- Empty states for supplemental content
- 2022
- 2023
- 2024
- Medicaid and CHIP regulations user experience
- Initial pilot research outline
- Comparative analysis
- Statute research
- Usability study SOP
- 2021
- 2022
- 2023-2024: 🔒 Dovetail (requires login)
- 🔒 Overview (requires login)
- Authentication and authorization
- Frontend caching
- Validation checklist
- Search
- Security tools
- Tests and linting
- Archive