$id: https://github.com/CMSgov/qpp-measures-data/blob/master/measures/2017/measures-schema.yaml
$schema: http://json-schema.org/schema#
type: array
items: { $ref: '#/definitions/measure' }

definitions:
  measure:
    type: object
    properties:
      measureId:
        type: string
        description: For quality measures, the measureId is the same as the quality number. For an advancing care information (ACI) measure, the measureId is the measure identifier for the ACI measure, and for an improvement activity (IA) measure, the measureId is the measure identifier for the IA measure.
      title: { type: string }
      description: { type: string }
      category:
        description: 'QPP scoring category to which the measure belongs: Improvement Activities, Quality, Advancing Care Information, and Cost.'
        enum: [ia, quality, aci, 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.
        items: { $ref: '#/definitions/measureSpecification' }
      measureSets:
        description: ACI measures can belong to the transition measure set. Quality measures can belong to multiple measure sets that represent different specialties.
        type: array
        items: { $ref: '#/definitions/measureSets' }
    required: [measureId, title, description, category, metricType, firstPerformanceYear, lastPerformanceYear]
    oneOf:
      - { $ref: '#/definitions/iaMeasure' }
      - { $ref: '#/definitions/aciMeasure' }
      - { $ref: '#/definitions/qualityMeasure' }
      - { $ref: '#/definitions/aggregateCostMeasure' }

  iaMeasure:
    type: object
    properties:
      category: { enum: [ia] }
      weight:
        description: Determines the points granted for attesting to the measure.
        enum: [null, medium, high]
        default: medium
      subcategoryId:
        description: IA category which the measure incentivizes.
        oneOf: [{ $ref: '#/definitions/subcategoryIds' }]
      cehrtEligible:
        description: If true, attesting to the measure will qualify the provider for an ACI CEHRT bonus.
        type: boolean
        default: false
    required: [weight, subcategoryId, cehrtEligible]

  aciMeasure:
    type: object
    properties:
      category: { enum: [aci] }
      reportingCategory:
        description: The reporting category of the ACI measure.
        enum: [preAttestation, base, registryBonus, performanceBonus, cehrtBonus]
      weight:
        description: Determines the performance score points granted for attesting to the measure.
        enum: [0, 5, 10, 20]
      objective:
        description: ACI 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 ACI score.
        type: boolean
        default: false
      isBonus:
        description: If true, attesting to the measure will qualify the provider for ACI bonus points.
        type: boolean
        default: false
      substitutes:
        description: Identifiers of other ACI measure that can be used instead of the current meausre.
        oneOf: [{ $ref: '#/definitions/arrayOfStringIdentifiers' }]
    required: [weight, objective, isRequired, isBonus, measureSets]

  aggregateCostMeasure:
    type: object
    properties:
      category: { enum: [cost] }
      isInverse:
          description: If true, a lower performance rate correlates with better performance.
          type: boolean
          default: false
      overallAlgorithm:
          description: Formula to determine the overall performance rate, given multiple strata of performance rates. Only applicable to multiPerformanceRate measures.
          type: string
      submissionMethods:
          description: Possible methods for submitting performance data for the measure.
          type: array

  qualityMeasure:
    type: object
    properties:
      category: { enum: [quality] }
      nationalQualityStrategyDomain: { type: ['null', string] }
      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]
      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
      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]
      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' }
      isRegistryMeasure:
        description: If true, this measure was authored by a QCDR (Qualified Clinical Data Registry).
        type: boolean
        default: false
      isRiskAdjusted:
        type: boolean
        default: false
      cpcPlusGroup:
        description: CPC+ group which the measure belongs
        type: string
    # measures with metricType multiPerformanceRate must also have the properties overallAlgorithm and strata; other metricTypes do not
    oneOf: [
      {
        properties: {
          metricType: { enum: [multiPerformanceRate, registryMultiPerformanceRate] }
        },
        required: [overallAlgorithm, strata]
      },{
        properties: {
          metricType: { enum: [singlePerformanceRate, nonProportion, cahps, registrySinglePerformanceRate, costScore] }
        }
      }]
    required: [nationalQualityStrategyDomain, measureType, eMeasureId, nqfEMeasureId, nqfId, isHighPriority, isInverse, primarySteward, measureSets, submissionMethods, isRegistryMeasure]

  performanceStrata:
    type: object
    properties:
      description:
        type: string
      name:
        type: string
        maxLength: 20
      eMeasureUuids:
        type: object
        properties:
          initialPopulationUuid:
            type: string
          denominatorUuid:
            type: string
          numeratorUuid:
            type: string
          denominatorExclusionUuid:
            type: string
          denominatorExceptionUuid:
            type: string

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

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

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

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

  measureSpecification:
    type: object
    properties:
      default:
        type: string
      registry:
        type: string
      claims:
        type: string
      cmsWebInterface:
        type: string

  measureSets:
    enum:
      - transition
      - allergyImmunology
      - anesthesiology
      - cardiology
      - dermatology
      - diagnosticRadiology
      - electrophysiologyCardiacSpecialist
      - emergencyMedicine
      - gastroenterology
      - generalOncology
      - generalPracticeFamilyMedicine
      - generalSurgery
      - hospitalists
      - internalMedicine
      - interventionalRadiology
      - mentalBehavioralHealth
      - neurology
      - obstetricsGynecology
      - ophthalmology
      - orthopedicSurgery
      - otolaryngology
      - pathology
      - pediatrics
      - physicalMedicine
      - plasticSurgery
      - preventiveMedicine
      - radiationOncology
      - rheumatology
      - thoracicSurgery
      - urology
      - vascularSurgery

  eligibilityOption:
    type: object
    properties:
      submissionMethods: { $ref: '#/definitions/qualityCodesSubmissionMethods' }
      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: { $ref: '#/definitions/arrayOfStringIdentifiers' }
      additionalDiagnosisCodes: { $ref: '#/definitions/arrayOfStringIdentifiers' }
      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' }
    required: [submissionMethods]
    anyOf:
      - required: ['procedureCodes']
      - required: ['diagnosisCodes']

  performanceOption:
    type: object
    properties:
      submissionMethods: { $ref: '#/definitions/qualityCodesSubmissionMethods' }
      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' }
    required: [submissionMethods, optionType, qualityCodes]

  codeObject:
    type: object
    properties:
      code:
        description: The HCPCS or CPT code represented as a string.
        type: string
      modifiers:  { $ref: '#/definitions/arrayOfStringIdentifiers' }
      modifierExclusions:  { $ref: '#/definitions/arrayOfStringIdentifiers' }
      placesOfService:  { $ref: '#/definitions/arrayOfStringIdentifiers' }
      placesOfServiceExclusions:  { $ref: '#/definitions/arrayOfStringIdentifiers' }
    required: [code]

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

  arrayOfStringIdentifiers:
    type: array
    items:
      type: string