Formatting Conventions

This guidance describes syntactic conventions for formatting statements and expressions of Clinical Quality Language (CQL) that encourage consistency, readability, maintainability, and reusability of the resulting CQL. Throughout the discussing, the following simplified syntax element definitions are used. Formal definitions of these elements can be found in the CQL Specification.

Whitespace - Whitespace defines the separation between all tokens in the language (e.g. spaces, tabs, returns, etc.)
Comment - Comments are ignored by the language, allowing for descriptive text to be included
Literal - Literals allow basic values to be represented within the language
Symbol - Symbols such as +, -, *, and /
Keyword - Grammar-recognized keywords such as define and where
Identifier - User-defined identifiers

Case-Related Conventions

CQL is a case-sensitive language, meaning that the grammar uses the case of letters when comparing identifiers and keywords. For example, the keyword define must be expressed with all lower case letters, Define is not recognized. This aspect of CQL encourages consistency and reduces the potential for naming clashes with keywords in the language.

This discussion defines the following terms to describe different approaches to casing:

lowercase - All letters are lowercase
camelCase - First letters of words are capitalized, except the first word, with no whitespace characters allowed
PascalCase - First letters of words are capitalized, including words not capitalized in Title Case like "and" and "of", with no whitespace characters allowed
Title Case - Standard title casing including spaces and tabs, but no other whitespace characters allowed

CQL-Defined Casing

These casings are defined by the specification, so they are not conventions per se, but are highlighted here for completeness.

Keywords within CQL are always lowercase.

System library functions are always PascalCase.

System type names are always PascalCase.

Spacing Conventions

CQL treats all whitespace as a single token, meaning that it doesn't matter whether you use spaces or tabs to separate keywords and other tokens, so long as you have some whitespace as defined by the rules of the language. This allows authors to format their expressions using whatever conventions are appropriate for their environment. While this flexibility is beneficial in that it allows CQL to be used in a wide variety of settings, it can also lead to inconsistent formatting, reducing readability. As such, these simple conventions are recommended to ensure consistent formatting:

Use spaces to indent, rather than tabs. The use of spaces ensures that indent levels remain consistent across different renderings.

Indent using two spaces for related content. This makes it visually clear where the dependencies are in any given expression and helps to organize statements and clauses.

Always use a space after a comma. This helps to visually separate items in a list.

Never use a space before or after a period. The period in CQL is a qualifier, and adding whitespace disconnects the content visually, implying a separation that is not present.

To help maintain readability of CQL, lines should fit reasonably within standard view screens. Around 100 characters per line is a good rule of thumb.

Operators and Functions

CQL distinguishes between operators, which use symbols such as +, *, and and, and functions, which use identifiers followed by parentheses to provide the arguments to the function.

Operators

Operators are always keywords, and always lowercase.

Binary operators (operators with two arguments) are always infix.

Unary operators (operators with one argument) are always prefix.

Always use a space before and after operators.

Functions

When defining a function, always use a PascalCase identifier.

Functions always use parentheses, even if the function has no arguments.

If the function has no arguments, do not put a space between the opening and closing parentheses.

Never put a space between the function name and the argument list, or between the opening and closing parentheses and the arguments.

Always use spaces after commas to separate arguments.

If necessary, an argument list can be continued across multiple lines, but keep the opening parenthesis on the same line as the function identifier, and indent subsequent lines one level.

When continuing an argument list, do not attempt to right-align indented content, as this leads to unnecessary maintenance to preserve the alignment.

Literals

Literals in CQL allow for the expression of values of each of the system-defined types.

Quantities

For Quantities, always put a space between the numerical value and the unit:

45 'mg'
28 'mm[Hg]'

TODO: Add discussion about case-sensitivity of the UCUM string. CQL allows both, need to determine the impact and whether we should make a specific recommendation.

Intervals

Intervals can be expressed based on any type that supports ordered comparison (Integer, Decimal, DateTime, Time, Quantity).

Intervals use standard mathematical notation to indicate whether the boundaries are open or closed: OPEN boundaries do not include the endpoint and are represented by ( ).
CLOSED boundaries include the endpoint and are represented by [ ].

Interval[1, 5]
Interval(1, 9)
Interval[@2015-01-01T00:00:00.0Z, @2016-01-01T00:00:00.0Z)

Never put a space before or after the opening or closing boundary.

Always put a space after the comma.

Lists and Tuples

Lists in CQL can contain elements of any type. Lists are similar to column elements in a spreadsheet or database.

Always separate the contents of the list with a space to help visually distinguish braces {} from parentheses ():

{ 1, 2, 3 }
Sum({ 1, 2, 3 })

Tuples in CQL contain named elements of any type. Tuples are similar to row elements in a spreadsheet or database.

Always separate the contents of the tuple with a space:

{ name: 'Patrick', birthDate: @2014-01-01 }

Do not put a space between the tuple element name and the value specifier (:), but always put a space between the value specifier and the value.

The Tuple keyword is optional, but this means that the empty tuple has a special construct:

{ } // empty list
{ : } // empty Tuple

Queries

The central expression construct of CQL is the query. The query construct in CQL is clause-based:

<primary source> <alias>
    <with or without clauses>
    <where clause>
    <return clause>
    <sort clause>

In general, simple queries can fit on a single line:

["Encounter, Performed": "Inpatient"] Encounter where duration in days of Encounter.period >= 120

If a query, or a clause of a query, needs more than one line, continue the clauses indented beneath the query or clause:

"Pharyngitis Encounters with Antibiotics" Pharyngitis
    with ["Laboratory Test, Performed": "Group A Streptococcus Test"] Test
        such that Test.result is not null
            and Test.startDateTime in Interval[Pharyngitis.startTime - 3 days, Pharyngitis.stopDateTime + 3 days]

When a query needs multiple lines, each clause should start on a new line indented one level.

Multi-line Formatting

When expressions are longer than will fit on a single, they should be broken up into multiple lines. For continuity, multi-line expressions should be indented below the start of the expression. For example, a multi-line conditional test would be formatted as

["Encounter, Performed": "Inpatient Encounter"] Encounter
  where Encounter.principalDiagnosis in "Ischemic Stroke"
    and Encounter.relevantPeriod during "Measurement Period"

When parentheses or other grouping delimiters ((), {}, []) are involved, the beginning parenthesis should start the expression, and the ending parenthesis should be on a new line, indented to the same level as the start of the expression:

  "Inpatient-Encounter" Encounter
    where exists ( Encounter.diagnoses Diagnosis 
        where Diagnosis in "Single Live Birth"
          or Diagnosis in "Single Live Born Newborn Born in Hospital"
    )

Syntax Highlighting

Syntax highlighting is an important aspect of readability. In order to enable different environments to provide consistent highlighting, the following syntactic categories are defined for CQL: