# CQL Options - Using CQL With FHIR v3.0.0-ballot

## Resource Profile: CQL Options 

 
A parameters profile that defines supported CQL-to-ELM translator options used to translate CQL. Complete documentation of these options can be found in the [Usage](https://github.com/cqframework/clinical_quality_language/blob/v3.9.0/Src/java/cql-to-elm/OVERVIEW.md#usage) topic of the CQL-to-ELM translator overview. 

**Usages:**

* Refer to this Profile: [CQL Group Definition](StructureDefinition-cql-groupdefinition.md), [CQL Library](StructureDefinition-cql-library.md), [ELM JSON Library](StructureDefinition-elm-json-library.md) and [ELM XML Library](StructureDefinition-elm-xml-library.md)
* Examples for this Profile: [Parameters/cql-options-example](Parameters-cql-options-example.md)

You can also check for [usages in the FHIR IG Statistics](https://packages2.fhir.org/xig/resource/hl7.fhir.uv.cql|current/StructureDefinition/StructureDefinition-cql-options.json)

### Formal Views of Profile Content

 [Description Differentials, Snapshots, and other representations](http://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#structure-definitions). 

 

Other representations of profile: [CSV](../StructureDefinition-cql-options.csv), [Excel](../StructureDefinition-cql-options.xlsx), [Schematron](../StructureDefinition-cql-options.sch) 



## Resource Content

```json
{
  "resourceType" : "StructureDefinition",
  "id" : "cql-options",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
    "valueInteger" : 1
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
    "valueCode" : "cds"
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
    "valueCode" : "trial-use"
  }],
  "url" : "http://hl7.org/fhir/uv/cql/StructureDefinition/cql-options",
  "identifier" : [{
    "system" : "urn:ietf:rfc:3986",
    "value" : "urn:oid:2.16.840.1.113883.4.642.40.37.42.13"
  }],
  "version" : "3.0.0-ballot",
  "name" : "CQLOptions",
  "title" : "CQL Options",
  "status" : "active",
  "experimental" : false,
  "date" : "2026-08-14T03:31:27+10:00",
  "publisher" : "HL7 International / Clinical Decision Support",
  "contact" : [{
    "telecom" : [{
      "system" : "url",
      "value" : "http://www.hl7.org/Special/committees/dss"
    }]
  }],
  "description" : "A parameters profile that defines supported CQL-to-ELM translator options used to translate CQL. Complete documentation of these options can be found in the [Usage](https://github.com/cqframework/clinical_quality_language/blob/v3.9.0/Src/java/cql-to-elm/OVERVIEW.md#usage) topic of the CQL-to-ELM translator overview.",
  "jurisdiction" : [{
    "coding" : [{
      "system" : "http://unstats.un.org/unsd/methods/m49/m49.htm",
      "code" : "001",
      "display" : "World"
    }]
  }],
  "fhirVersion" : "4.0.1",
  "mapping" : [{
    "identity" : "v2",
    "uri" : "http://hl7.org/v2",
    "name" : "HL7 v2 Mapping"
  },
  {
    "identity" : "rim",
    "uri" : "http://hl7.org/v3",
    "name" : "RIM Mapping"
  }],
  "kind" : "resource",
  "abstract" : false,
  "type" : "Parameters",
  "baseDefinition" : "http://hl7.org/fhir/StructureDefinition/Parameters",
  "derivation" : "constraint",
  "differential" : {
    "element" : [{
      "id" : "Parameters",
      "path" : "Parameters",
      "mustSupport" : false
    },
    {
      "id" : "Parameters.parameter",
      "path" : "Parameters.parameter",
      "slicing" : {
        "discriminator" : [{
          "type" : "value",
          "path" : "name"
        }],
        "ordered" : false,
        "rules" : "open"
      }
    },
    {
      "id" : "Parameters.parameter:translator",
      "path" : "Parameters.parameter",
      "sliceName" : "translator",
      "short" : "What translator",
      "definition" : "This parameter indicates what translator should be or was used to translate from CQL to ELM",
      "comment" : "This parameter can be used to capture what translator was used to perform the translation from CQL to ELM, and can also serve as a hint to target environments for which translator to use.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:translator.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "translator"
    },
    {
      "id" : "Parameters.parameter:translator.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }]
    },
    {
      "id" : "Parameters.parameter:enableAnnotations",
      "path" : "Parameters.parameter",
      "sliceName" : "enableAnnotations",
      "short" : "Include annotations?",
      "definition" : "This parameter instructs the translator to include the source CQL as annotations within the ELM. (default is false)",
      "comment" : "Annotations allow implementations to reconstruct the source CQL from translated ELM to support applications such as debugging and code coverage highlighting.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableAnnotations.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableAnnotations"
    },
    {
      "id" : "Parameters.parameter:enableAnnotations.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:enableLocators",
      "path" : "Parameters.parameter",
      "sliceName" : "enableLocators",
      "short" : "Include locators?",
      "definition" : "This parameter instructs the translator to include source line number and character information for each ELM node. (default is false)",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableLocators.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableLocators"
    },
    {
      "id" : "Parameters.parameter:enableLocators.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:disableListDemotion",
      "path" : "Parameters.parameter",
      "sliceName" : "disableListDemotion",
      "short" : "Implicitly convert lists to singletons when possible?",
      "definition" : "This parameter instructs the translator to disallow demotion of list-valued expressions to singletons. (default is false)",
      "comment" : "The list demotion feature of CQL is used to enable functionality related to use with FHIRPath by implicitly converting list-valued expressions to singletons when possible.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:disableListDemotion.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "disableListDemotion"
    },
    {
      "id" : "Parameters.parameter:disableListDemotion.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:disableListPromotion",
      "path" : "Parameters.parameter",
      "sliceName" : "disableListPromotion",
      "short" : "Implicitly convert singletons to lists when possible?",
      "definition" : "This parameter instructs the translator to disallow promotion of singletons to list-valued expressions. (default is false)",
      "comment" : "The list promotion feature of CQL is used to enable functionality related to use with FHIRPath by implicitly converting singleton expressions to list-valued expressions when possible.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:disableListPromotion.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "disableListPromotion"
    },
    {
      "id" : "Parameters.parameter:disableListPromotion.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:disableMethodInvocation",
      "path" : "Parameters.parameter",
      "sliceName" : "disableMethodInvocation",
      "short" : "Disable method-style invocation?",
      "definition" : "This parameter instructs the translator to disallow method-style invocation. (default is false)",
      "comment" : "The method-style invocation feature of CQL is used to enable functionality related to use with FHIRPath.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:disableMethodInvocation.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "disableMethodInvocation"
    },
    {
      "id" : "Parameters.parameter:disableMethodInvocation.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:enableDateRangeOptimization",
      "path" : "Parameters.parameter",
      "sliceName" : "enableDateRangeOptimization",
      "short" : "Optimize date ranges when possible?",
      "definition" : "This parameter instructs the translator to optimize date range filters by moving them inside retrieve expressions. (default is false)",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableDateRangeOptimization.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableDateRangeOptimization"
    },
    {
      "id" : "Parameters.parameter:enableDateRangeOptimization.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:enableResultTypes",
      "path" : "Parameters.parameter",
      "sliceName" : "enableResultTypes",
      "short" : "Include result types?",
      "definition" : "This parameter instructs the translator to include inferred result types in the output ELM. (default is false)",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableResultTypes.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableResultTypes"
    },
    {
      "id" : "Parameters.parameter:enableResultTypes.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:enableDetailedErrors",
      "path" : "Parameters.parameter",
      "sliceName" : "enableDetailedErrors",
      "short" : "Include detailed errors?",
      "definition" : "This instructs the translator to include detailed error information. By default, the translator only reports root-cause errors.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableDetailedErrors.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableDetailedErrors"
    },
    {
      "id" : "Parameters.parameter:enableDetailedErrors.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:disableListTraversal",
      "path" : "Parameters.parameter",
      "sliceName" : "disableListTraversal",
      "short" : "Disallow list traversal?",
      "definition" : "This parameter instructs the translator to disallow traversal of list-valued expressions. (default is false)",
      "comment" : "With FHIR-based knowledge artifacts, disabling this feature is not recommended, since it would prevent the use of FHIRPath expressions involving multi-cardinality (i.e. list-valued) elements.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:disableListTraversal.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "disableListTraversal"
    },
    {
      "id" : "Parameters.parameter:disableListTraversal.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:signatureLevel",
      "path" : "Parameters.parameter",
      "sliceName" : "signatureLevel",
      "short" : "Include signatures?",
      "definition" : "This parameter controls whether the signature element of a FunctionRef will be populated. None (default) | Differing | Overloads | All. Differing will include invocation signatures that differ from the declared signature. Overloads will include declaration signatures when the operator or function has more than one overload with the same number of arguments as the invocation.",
      "comment" : "Note that without this information included, ELM that makes use of function overloads may be ambiguous at runtime, so this parameter should be used with at least Overloads.",
      "min" : 0,
      "max" : "1",
      "constraint" : [{
        "key" : "cop-1",
        "severity" : "error",
        "human" : "SignatureLevel parameter must be None, Differing, Overloads, or All",
        "expression" : "value in ( 'None' | 'Differing' | 'Overloads' | 'All' )",
        "xpath" : "exists(f:value)"
      }]
    },
    {
      "id" : "Parameters.parameter:signatureLevel.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "signatureLevel"
    },
    {
      "id" : "Parameters.parameter:signatureLevel.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }],
      "condition" : ["cop-1"]
    },
    {
      "id" : "Parameters.parameter:translatorVersion",
      "path" : "Parameters.parameter",
      "sliceName" : "translatorVersion",
      "short" : "What version",
      "definition" : "This parameter indicates what version of the CQL-to-ELM translator used to perform the translation.",
      "comment" : "This parameter is not an input to the translator, it is included in the list of options that is stored with translated ELM as an indication of what version was used to perform the translation.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:translatorVersion.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "translatorVersion"
    },
    {
      "id" : "Parameters.parameter:translatorVersion.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }]
    },
    {
      "id" : "Parameters.parameter:format",
      "path" : "Parameters.parameter",
      "sliceName" : "format",
      "short" : "What format (XML and/or JSON)",
      "definition" : "This parameter indicates what format the ELM should be output in.",
      "min" : 0,
      "max" : "2",
      "constraint" : [{
        "key" : "cop-2",
        "severity" : "error",
        "human" : "Format parameter must be XML or JSON",
        "expression" : "value in ( 'XML' | 'JSON' )",
        "xpath" : "exists(f:value)"
      }]
    },
    {
      "id" : "Parameters.parameter:format.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "format"
    },
    {
      "id" : "Parameters.parameter:format.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }],
      "condition" : ["cop-2"]
    },
    {
      "id" : "Parameters.parameter:compatibilityLevel",
      "path" : "Parameters.parameter",
      "sliceName" : "compatibilityLevel",
      "short" : "What compatibility level",
      "definition" : "This parameter indicates what compatibility level the translator should support.",
      "comment" : "By default, the translator will use capabilities from the latest version of CQL. This parameter allows CQL to be constructed that only makes use of capabilities in previous versions. Possible values are the major and minor versions of published versions of the CQL specification (e.g. 1.3, 1.4, 1.5)",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:compatibilityLevel.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "compatibilityLevel"
    },
    {
      "id" : "Parameters.parameter:compatibilityLevel.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }]
    },
    {
      "id" : "Parameters.parameter:enableCqlOnly",
      "path" : "Parameters.parameter",
      "sliceName" : "enableCqlOnly",
      "short" : "Include CQL only?",
      "definition" : "This parameter indicates that library packaging tooling should only include CQL, not ELM, in packaged Library resources.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:enableCqlOnly.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "enableCqlOnly"
    },
    {
      "id" : "Parameters.parameter:enableCqlOnly.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:errorLevel",
      "path" : "Parameters.parameter",
      "sliceName" : "errorLevel",
      "short" : "What error level",
      "definition" : "This parameter indicates the minimum severity error message that will be reported. Info (default) | Warning | Error",
      "min" : 0,
      "max" : "1",
      "constraint" : [{
        "key" : "cop-3",
        "severity" : "error",
        "human" : "ErrorLevel parameter must be Info, Warning, or Error",
        "expression" : "value in ( 'Info' | 'Warning' | 'Error' )",
        "xpath" : "exists(f:value)"
      }]
    },
    {
      "id" : "Parameters.parameter:errorLevel.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "errorLevel"
    },
    {
      "id" : "Parameters.parameter:errorLevel.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "string"
      }],
      "condition" : ["cop-3"]
    },
    {
      "id" : "Parameters.parameter:validateUnits",
      "path" : "Parameters.parameter",
      "sliceName" : "validateUnits",
      "short" : "Validate UCUM units?",
      "definition" : "This parameter instructs the translator to validate UCUM units in quantity literals.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:validateUnits.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "validateUnits"
    },
    {
      "id" : "Parameters.parameter:validateUnits.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:verifyOnly",
      "path" : "Parameters.parameter",
      "sliceName" : "verifyOnly",
      "short" : "Verify only",
      "definition" : "This parameter indicates that the translator should verify the input CQL only, not create ELM output.",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:verifyOnly.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "verifyOnly"
    },
    {
      "id" : "Parameters.parameter:verifyOnly.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:analyzeDataRequirements",
      "path" : "Parameters.parameter",
      "sliceName" : "analyzeDataRequirements",
      "short" : "Analyze data requirements?",
      "definition" : "This parameter indicates whether the packaging for CQL libraries should perform optimizations on data requirements where possible (such as optimizing where clauses into retrieves to improve selectivity of the resulting data requirements).",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:analyzeDataRequirements.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "analyzeDataRequirements"
    },
    {
      "id" : "Parameters.parameter:analyzeDataRequirements.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    },
    {
      "id" : "Parameters.parameter:collapseDataRequirements",
      "path" : "Parameters.parameter",
      "sliceName" : "collapseDataRequirements",
      "short" : "Collapse data requirements?",
      "definition" : "This parameter indicates whether the packaging for CQL libraries should collapse data requirements where possible (i.e. removing duplicate data requirements according to the process described in the [Artifact Data Requirements](https://cql.hl7.org/05-languagesemantics.html#artifact-data-requirements) section of the CQL specification).",
      "min" : 0,
      "max" : "1"
    },
    {
      "id" : "Parameters.parameter:collapseDataRequirements.name",
      "path" : "Parameters.parameter.name",
      "fixedString" : "collapseDataRequirements"
    },
    {
      "id" : "Parameters.parameter:collapseDataRequirements.value[x]",
      "path" : "Parameters.parameter.value[x]",
      "min" : 1,
      "type" : [{
        "code" : "boolean"
      }]
    }]
  }
}

```
