$id: https://github.com/CMSgov/qpp-measures-data/blob/master/measures/2025/measures-schema.yaml
$schema: http://json-schema.org/draft-07/schema
type: array
items: { $ref: '#/definitions/measure' }
uniqueItemProperties: ['measureId'] # used by ajv-keywords

definitions:
  measure:
    title: 'Measure'
    type: object
    anyOf:
      - { $ref: '#/definitions/iaMeasure' }
      - { $ref: '#/definitions/piMeasure' }
      - { $ref: '#/definitions/qualityMeasure' }
      - { $ref: '#/definitions/aggregateCostMeasure' }

  baseMeasure:
    title: 'Base Measure'
    type: object
    additionalProperties: false
    properties:
      measureId:
        type: string
        description: For quality measures, the measureId is the same as the quality number. For a Promoting Interoperability (PI, formerly ACI) measure, the measureId is the measure identifier for the PI measure, and for an improvement activity (IA) measure, the measureId is the measure identifier for the IA measure.
      title: 
        type: string
        description: The name of the measure.
      description: 
        type: string
        description: A description of the measure for more detail with key words/phrases.
      category:
        description: 'QPP scoring category to which the measure belongs: Improvement Activities, Quality, Promoting Interoperability (formerly Advancing Care Information), and Cost.'
        enum: [ia, quality, pi, cost]
      metricType:
        description: Type of measurement that the measure requires in order to attest.
        enum: [boolean, proportion, singlePerformanceRate, multiPerformanceRate, registrySinglePerformanceRate, registryMultiPerformanceRate, nonProportion, cahps, costScore]
      firstPerformanceYear:
        description: Year in which the measure was introduced.
        type: integer
        default: 2017
      lastPerformanceYear:
        description: Year in which the measure was deprecated.
        type: [integer, 'null']
        default: 'null'
      measureSpecification:
        description: URL link for Measure Specification PDF to download by Submission Method.
        anyOf:
          - { $ref: '#/definitions/measureSpecification' }
          - { type: 'null' }
      measureSets:
        description: Quality measures can belong to multiple measure sets that represent different specialties.
        type: array
        items: { $ref: '#/definitions/measureSets' }
      allowedPrograms:
        description: Programs to which the measure can be submitted.
        type: array
        items: { $ref: '#/definitions/programs' }
      allowedRegistrationTypes:
        description: Entity types which the measure is eligible for registration.
        type: array
        items: { $ref: '#/definitions/allowedRegistrationTypes'}
    required: [measureId, title, description, category, metricType, firstPerformanceYear, lastPerformanceYear, allowedRegistrationTypes]

  iaMeasure:
    $merge:
      source:
        { $ref: '#/definitions/baseMeasure' }
      with:
        title: 'IA Measure'
        type: object
        additionalProperties: false
        properties:
          category:
            enum: [ia]
          subcategoryId:
            description: IA category which the measure incentivizes.
            oneOf: [{ $ref: '#/definitions/subcategoryIds' }]
        required: [subcategoryId]

  piMeasure:
    $merge:
      source:
        { $ref: '#/definitions/baseMeasure' }
      with:
        title: 'PI Measure'
        type: object
        additionalProperties: false
        properties:
          category:
            enum: [pi]
          reportingCategory:
            description: The reporting category of the PI measure.
            enum: [required, bonus, exclusion, null]
          objective:
            description: PI category which the measure incentivizes.
            oneOf: [{ $ref: '#/definitions/objectives' }]
          isRequired:
            description: If true, attesting to the measure is required in order to receive a non-zero PI score.
            type: boolean
            default: false
          isBonus:
            description: If true, attesting to the measure will qualify the provider for PI bonus points.
            type: boolean
            default: false
          substitutes:
            description: Identifiers of other PI measures that can be used instead of the current measure.
            oneOf: [{ $ref: '#/definitions/arrayOfStringIdentifiers' }]
          exclusion:
            description: Identifiers of other PI measures that can be submitted instead of current measure. Cannot submit both current measure and the exclusion measure.
          preprod:
            description: Identifiers of associated PRE and PROD PI measures.
        required: [objective, isRequired, isBonus, measureSets]

  aggregateCostMeasure:
    $merge:
      source:
        { $ref: '#/definitions/baseMeasure' }
      with:
        title: 'Cost Measure'
        type: object
        additionalProperties: false
        properties:
          category:
            enum: [cost]
          isInverse:
            description: If true, a lower performance rate correlates with better performance.
            type: boolean
            default: false
          dataDisplayFormat:
            description: Defines how the data is to be displayed by the UI.
            oneOf: [ { $ref: '#/definitions/dataDisplayFormat' } ]
          submissionMethods:
            description: Possible methods for submitting performance data for the measure.
            type: array
        required: [dataDisplayFormat]

  qualityMeasure:
    $merge:
      source:
        { $ref: '#/definitions/baseMeasure' }
      with:
        title: 'Quality Measure'
        type: object
        additionalProperties: false
        properties:
          category:
            enum: [quality]
          measureType:
            description: Quality category which the measure incentivizes.
            oneOf: [{ $ref: '#/definitions/measureTypes' }]
          eMeasureId:
            description: Identifier for Electronic Clinical Quality Measures (ECQM).
            type: ['null', string]
          eMeasureUuid:
            description: UUID for Electronic Clinical Quality Measures (ECQM).
            type: string
          nqfEMeasureId:
            description: Identifier for measure specified in the Health Quality Measure Format (HQMF).
            type: ['null', string]
          nqfId:
            description: Identifier for the National Quality Forum (NQF) measure.
            type: ['null', string]
          isClinicalGuidelineChanged:
            description: If true, at least one submission method is listed in clinicalGuidelinesChanged.
            type: boolean
          clinicalGuidelineChanged:
            type: array
            description: List of submissionMethods that have been suppressed for this year due to potentially no longer aligning with best practices or could lead to patient harm.
            items: { $ref: '#/definitions/methods' }
          isHighPriority:
            description: If true, can be used in the place of an outcome measure to satisfy quality category requirements.
            type: boolean
            default: false
          isInverse:
            description: If true, a lower performance rate correlates with better performance.
            type: boolean
            default: false
          dataDisplayFormat:
            description: Defines how the data is to be displayed by the UI.
            oneOf: [ { $ref: '#/definitions/dataDisplayFormat' } ]
          overallAlgorithm:
            description: Formula to determine the overall performance rate, given multiple strata of performance rates. Only applicable to multiPerformanceRate measures.
            enum: [simpleAverage, weightedAverage, sumNumerators, overallStratumOnly, split]
          strata:
            description: Population segments for which the measure requires reporting data. Only applicable to multiPerformanceRate measures.
            type: array
            items: { $ref: '#/definitions/performanceStrata' }
          primarySteward:
            description: Organization who submits and maintains the measure.
            type: string
          submissionMethods:
            description: Possible methods for submitting performance data for the measure.
            type: array
            items: { $ref: '#/definitions/methods' }
          eligibilityOptions:
            description: Eligibility options mirror denominator options in QCDR measure specifications. Each option comprises a set of codes used to identify eligible instances of the associated measure.
            type: array
            items: { $ref: '#/definitions/eligibilityOption' }
          performanceOptions:
            description: Performance options mirror numerator options in QCDR measure specifications. Each option comprises a set of codes used to identify instances of performance met, performance not met, performance exclusion or performance exception.
            type: array
            items: { $ref: '#/definitions/performanceOption' }
          requiredForPrograms:
            description: Programs that the measure is required to be submitted to
            type: array
            items: { $ref: '#/definitions/programs' }
          allowedVendors:
            description: List of QCDR Registries that are allowed to submit the QCDR measure
            type: array
            items: { type: string, pattern: '^\d{7}$' }
          isRegistryMeasure:
            description: If true, this measure was authored by a QCDR (Qualified Clinical Data Registry).
            type: boolean
            default: false
          isRiskAdjusted:
            type: boolean
            description: Risk adjustment refers to the inclusion of risk factors associated with a measure score in a statistical model of measured entity performance captured at the person, facility, community, or other levels. Measure developers often risk adjust outcome measures, however not all outcome measures need risk adjustment.
            default: false
          isIcdImpacted:
            type: boolean
            description: If true, at least one submission method is listed in icdImpacted.
            default: false
          icdImpacted:
            type: array
            description: List of submissionMethods where ICD 10 codes for the measure changed during the submission year. Used to indicate that submissions data should be truncated to only the first nine months of the performance year when the ICD 10 codes were unchanged. Typically impacts claims submissionMethod. Does not impact registry submissionMethod.
            items: { $ref: '#/definitions/methods' }
          historic_benchmarks:
            type: object
            description: The submissionMethods of the measure which have had their benchmarks removed or flattened for the current year. A benchmark is marked as flat if the measure is determined to have the potential to result in inappropriate treatment of patients if the top decile is higher than 90%, or if inverse less than 10%. 
            propertyNames: { $ref: '#/definitions/methods' }
            patternProperties:
              "":
                enum: [removed, flat]
          companionMeasureId:
            default: []
            description: List of measureIds to establish a link between the base and Medicare CQM measures.
            oneOf: [{ $ref: '#/definitions/arrayOfStringIdentifiers' }]
          isSevenPointCapRemoved:
            type: boolean
            description: If true, at least one submission method is listed in sevenPointCapRemoved.
            default: false
          sevenPointCapRemoved:
            type: array
            description: List of submissionMethods that have been identified for application of the alternative benchmark defined by Policy.
            items: { $ref: '#/definitions/methods' }

        # measures with metricType multiPerformanceRate must also have the properties overallAlgorithm and strata; other metricTypes do not
        # Note: Need to add back required: [overallAlgorithm, strata] for multiPerformanceRate, registryMultiPerformanceRate once strata data for 007 has been received
        oneOf: [
          {
            properties: {
              metricType: { enum: [multiPerformanceRate, registryMultiPerformanceRate] },
              strata: {
                type: 'array',
                minItems: 1,
                items: { $ref: '#/definitions/performanceStrata' }
              }
            },
            required: [overallAlgorithm, strata]
          },
          {
            properties: {
              metricType: { enum: [singlePerformanceRate, nonProportion, cahps, registrySinglePerformanceRate, costScore] }
            }
          }
        ]
        required: [measureType, eMeasureId, nqfEMeasureId, nqfId, isHighPriority, isInverse, dataDisplayFormat, primarySteward, submissionMethods, isRegistryMeasure, isIcdImpacted]

  performanceStrata:
    type: object
    additionalProperties: false
    properties:
      description:
        type: string
        description: A detailed description of the strata, outlining exactly which type of patients it applies to.
      name:
        type: string
        description: a one-word tag, unique to the strata.
        maxLength: 20
      eMeasureUuids:
        type: object
        properties:
          initialPopulationUuid:
            type: string
            maxLength: 36
          denominatorUuid:
            type: string
            maxLength: 36
          numeratorUuid:
            type: string
            maxLength: 36
          denominatorExclusionUuid:
            type: string
            maxLength: 36
          denominatorExceptionUuid:
            type: string
            maxLength: 36
          strata:
            type: array
            items:
              type: string
              maxLength: 36
    required: [description]

  subcategoryIds:
    enum:
      - null
      - achievingHealthEquity
      - behavioralAndMentalHealth
      - beneficiaryEngagement
      - careCoordination
      - emergencyResponseAndPreparedness
      - expandedPracticeAccess
      - patientSafetyAndPracticeAssessment
      - populationManagement

  objectives:
    enum:
      - null
      - attestation
      - publicHealthAndClinicalDataRegistryReporting
      - healthInformationExchange
      - electronicPrescribing
      - coordinationOfCareThroughPatientEngagement
      - patientElectronicAccess
      - protectPatientHealthInformation
      - publicHealthReporting
      - medicationReconciliation
      - patientSpecificEducation
      - secureMessaging
      - publicHealthAndClinicalDataExchange
      - providerToPatientExchange

  measureTypes:
    enum:
      - efficiency
      - intermediateOutcome
      - outcome
      - patientEngagementExperience
      - process
      - structure
      - patientReportedOutcome

  dataDisplayFormat:
    enum:
      - currency
      - percentage
      - decimal

  methods:
    enum:
      - administrativeClaims
      - claims
      - certifiedSurveyVendor
      - electronicHealthRecord
      - registry

  measureSpecification:
    type: object
    additionalProperties: false
    properties:
      default:
        type: string
        pattern: '^https:.*'
      registry:
        type: string
        pattern: '^https:.*'
      claims:
        type: string
        pattern: '^https:.*'
      measureInformation:
        type: string
        pattern: '^https:.*'
      electronicHealthRecord:
        type: string
        pattern: '^https:.*'

  allowedRegistrationTypes:
    enum:
      - apm
      - group
      - subgroup
      - individual

  measureSets:
    enum:
      - transition # PI only
      - allergyImmunology
      - anesthesiology
      - cardiology
      - dentistry
      - dermatology
      - diagnosticRadiology
      - electrophysiologyCardiacSpecialist
      - emergencyMedicine
      - gastroenterology
      - generalSurgery
      - hospitalists
      - infectiousDisease
      - internalMedicine
      - interventionalRadiology
      - mentalBehavioralHealth
      - nephrology
      - neurology
      - neurosurgical
      - obstetricsGynecology
      - ophthalmology
      - optometry
      - orthopedicSurgery
      - otolaryngology
      - pathology
      - pediatrics
      - physicalMedicine
      - plasticSurgery
      - podiatry
      - preventiveMedicine
      - radiationOncology
      - rheumatology
      - thoracicSurgery
      - urology
      - vascularSurgery
      - familyMedicine
      - oncology
      - physicalTherapyOccupationalTherapy
      - geriatrics
      - urgentCare
      - skilledNursingFacility
      - generalPracticeFamilyMedicine
      - endocrinology
      - nutritionDietician
      - pulmonology
      - chiropracticMedicine
      - clinicalSocialWork
      - audiology
      - speechLanguagePathology
      - certifiedNurseMidwife

  eligibilityOption:
    type: object
    additionalProperties: false
    properties:
      sexCode:
        description: Gender identifier in the case of measures that apply to one gender only.
        enum: [M, F]
      minAge:
        description: The minimum patient age required for eligibility.
        type: number
      maxAge:
        description: The maximum patient age required for eligibility.
        type: number
      diagnosisCodes: 
        type: array
        description: List of diagnosis codes and procedures of the patient.
        items:
          type: string
      additionalDiagnosisCodes: 
        type: array
        description: Additional list of diagnosis codes and procedures of the patient for eligibility.
        items:
          type: string
      procedureCodes:
        description: A list of HCPCS or CPT codes, at least one of which must be present to meet the eligibility option.
        type: array
        items: { $ref: '#/definitions/codeObject' }
      additionalProcedureCodes:
        description: A list of HCPCS or CPT codes, at least one of which must be present to meet the eligibility option. If present, this field imposes a requirement in addition to the one from the procedureCodes field.
        type: array
        items: { $ref: '#/definitions/codeObject' }
      optionGroup:
        description: An identifier for grouping eligibility options together that need to be met together.
        type: string
      diagnosisExclusionCodes:
        type: array
        description: Additional list of diagnosis exclusion codes and procedures of the patient for eligibility.
        items:
          type: string
    anyOf:
      - required: ['procedureCodes']
      - required: ['diagnosisCodes']

  performanceOption:
    type: object
    additionalProperties: false
    properties:
      optionType:
        description: The specific performance option corresponding to the quality codes (performance met, performance not met, etc.).
        enum: [performanceMet, performanceNotMet, eligiblePopulationExclusion, eligiblePopulationException]
      qualityCodes:
        description: A list of quality codes, all of which must be present to meet the performance option.
        type: array
        items: { $ref: '#/definitions/codeObject' }
      optionGroup:
        description: An identifier for grouping eligibility options together that need to be met together.
        type: string
    required: [optionType, qualityCodes]

  programs:
    enum:
      - mips
      - app1
      - appPlus
      - ssp
      - G0053
      - G0054
      - G0055
      - G0057
      - G0058
      - G0059
      - M0001
      - M0002
      - M0004
      - M0005
      - M1366
      - M1367
      - M1368
      - M1369
      - M1370
      - M1420
      - M1421
      - M1422
      - M1423
      - M1424
      - M1425

  codeObject:
    type: object
    additionalProperties: false
    properties:
      code:
        description: The HCPCS or CPT code represented as a string.
        type: string
      modifiers:
        type: array
        description: List of modifier codes that are relevant to a claim, regarding additional information about a patient encounter.
        items:
          type: string
      modifierExclusions:
        type: array
        description: List of modifier codes that are excluded because they are opposites of the measure and thus cannot be submitted in the same measurementSet.
        items:
          type: string
      placesOfService:
        type: array
        description: List of Place of Service Codes which are two-digit codes placed on health care professional claims to indicate the setting in which a service was provided.
        items:
          type: string
      placesOfServiceExclusions:
        type: array
        description: List of Place of Service Codes that are excluded.
        items:
          type: string
    required: [code]

  qualityCodesSubmissionMethods:
    type: array
    items:
      enum:
        - claims
        - registry

  arrayOfStringIdentifiers:
    type: array
    items:
      type: string