Merge pull request #59 from abdullah-git1/master

FHIR-27517

spec/01-introduction.adoc

@@ -30,9 +30,9 @@ Considering each of these components separately, the next step involves identify
 [cols=",,,,",options="header"]
 |========================================================================================================================================================================================
 | | Model Type | Quality Information | Computable Expression Logic | Metadata
-| *Clinical Decision Support (CDS)* |Physical and logical |Virtual Medical Record (vMR) |CDS Knowledge Artifact Specification |CDS Knowledge Artifact Specification/Decision Support Service
-1.2+| *Electronic Clinical Quality Measurement (eCQM)* |Physical |Quality Reporting Document Architecture (QRDA) |Health Quality Measure Format (HQMF) |Health Quality Measure Format (HQMF)
-1.1+|Logical |Quality Data Model (QDM) |Quality Data Model (QDM)|
+| *Clinical Decision Support (CDS)* |<<Approach, Physical and Logical>> |https://www.hl7.org/implement/standards/product_brief.cfm?product_id=338[Virtual Medical Record (vMR)] |http://www.hl7.org/implement/standards/product_brief.cfm?product_id=337[CDS Knowledge Artifact Specification] |http://www.hl7.org/implement/standards/product_brief.cfm?product_id=337[CDS Knowledge Artifact Specification] / http://www.hl7.org/implement/standards/product_brief.cfm?product_id=12[Decision Support Service]
+1.2+| *Electronic Clinical Quality Measurement (eCQM)* |<<Approach, Physical>> |http://www.hl7.org/implement/standards/product_brief.cfm?product_id=35[Quality Reporting Document Architecture (QRDA)] |<<Health Quality Measure Format (HQMF),Health Quality Measure Format (HQMF)>> |<<Health Quality Measure Format (HQMF),Health Quality Measure Format (HQMF)>>
+1.1+|<<Approach, Logical>> |http://www.hl7.org/implement/standards/product_brief.cfm?product_id=346[Quality Data Model (QDM)] |http://www.hl7.org/implement/standards/product_brief.cfm?product_id=346[Quality Data Model (QDM)]|
 |========================================================================================================================================================================================
 Table 1‑A - Relationship of the current specifications to each component
 
@@ -61,7 +61,7 @@ The Clinical Quality Framework (CQF) was initially a collaborative community of
 [[approach]]
 == Approach
 
-As discussed in Section 1, one key principle underlying the current harmonization efforts is the separation of responsibilities within an artifact into _metadata_, _clinical information_, and _expression logic_. Focusing on the expression logic component and identifying the requirements common to both quality measurement and decision support, the Clinical Decision Support HL7 Work Group produced a harmonized conceptual requirements document: _HL7 Domain Analysis Model: Harmonization of Health Quality Artifact Reasoning and Expression Logic._ To view this document, refer to the link:11-d-references.html[References] section. These requirements form the basis for the reasoning capabilities that this specification provides.
+As discussed in <<Background, Section 1>>, one key principle underlying the current harmonization efforts is the separation of responsibilities within an artifact into _metadata_, _clinical information_, and _expression logic_. Focusing on the expression logic component and identifying the requirements common to both quality measurement and decision support, the Clinical Decision Support HL7 Work Group produced a harmonized conceptual requirements document: _HL7 Domain Analysis Model: Harmonization of Health Quality Artifact Reasoning and Expression Logic._ To view this document, refer to the link:11-d-references.html[References] section. These requirements form the basis for the reasoning capabilities that this specification provides.
 
 Building on those conceptual requirements, this specification defines the logical and physical layers necessary to achieve the goal of a unified specification for expression logic for use by both the clinical quality and decision support domains.
 
@@ -124,9 +124,9 @@ The specification is written with the following major roles in mind:
 
 Table 1‑B - Major roles that this specification was written for
 
-Note that although Chapter 2 is intended for a non-technical audience, the material is still somewhat technical in nature, and that readers will benefit from some familiarity with and/or training in basic computer language and database language topics.
+Note that although the <<2. Author’s Guide, Author's Guide (Chapter 2)>> is intended for a non-technical audience, the material is still somewhat technical in nature, and that readers will benefit from some familiarity with and/or training in basic computer language and database language topics.
 
-In general, each of these roles will benefit from focusing on different aspects of the specification. In particular, the Author role will be primarily interested in Chapter 2, the Language Guide for the high-level CQL syntax; the Developer role will be primarily interested in Chapters 2 & 3; the Integrator role will be primarily interested in Chapter 4, the formal description of the logical model; and the Implementer role will be primarily interested in Chapters 5, 6, and 7, which discuss the intended execution semantics, translation semantics, and physical representation, respectively, as well as Appendix B, and ELM UML model artifacts.
+In general, each of these roles will benefit from focusing on different aspects of the specification. In particular, the Author role will be primarily interested in <<2. Author’s Guide, Chapter 2>>, the Language Guide for the high-level CQL syntax; the Developer role will be primarily interested in Chapter <<2. Author’s Guide, 2>> & <<3. Developer’s Guide, 3>>; the Integrator role will be primarily interested in <<4. Logical Specification, Chapter 4>>, the formal description of the logical model; and the Implementer role will be primarily interested in Chapters <<5. Language Semantics, 5>>, <<6. Translation Semantics, 6>>, and <<7. Physical Representation, 7>>, which discuss the intended execution semantics, translation semantics, and physical representation, respectively, along with additional reference materials in Appendix A-K.
 
 [[scope-of-the-specification]]
 == Scope of the Specification
@@ -156,7 +156,7 @@ Figure 1‑C - How the CQL and ELM specifications will be used in the sharing us
 [[use-case-assumptions-and-conditions]]
 === Use Case Assumptions and Conditions
 
-It is important for implementers to clearly understand the underlying environmental assumptions, defined in Section 5 of the CQF Use Case document referenced in the previous section, to ensure that these assumptions align to the implementation environment in which content will be exchanged using a knowledge artifact. Failure to meet any of these assumptions could impact implementation of the knowledge artifact.
+It is important for implementers to clearly understand the underlying environmental assumptions, defined in https://oncprojectracking.healthit.gov/wiki/display/TechLabSC/CQF+Use+Cases+-+Discovery[Section 5 of the CQF Use Case document] referenced in the previous section, to ensure that these assumptions align to the implementation environment in which content will be exchanged using a knowledge artifact. Failure to meet any of these assumptions could impact implementation of the knowledge artifact.
 
 [[relationship-to-other-hl7-specifications]]
 == Relationship to Other HL7 Specifications

spec/02-authorsguide.adoc

@@ -83,9 +83,14 @@ The following example illustrates the using declaration:
 using QUICK
 ----
 
-The above declaration specifies that the [.id]#QUICK# model will be used as the data model within the library.
+The above declaration specifies that the [.id]#QUICK# model will be used as the data model within the library. The http://hl7.org/fhir/us/qicore/quick/QUICK-index.html[QUICK data model] will be used for the examples in this section unless specified otherwise.
 
-If necessary, a version specifier can be provided to indicate which version of the data model should be used.
+If necessary, a version specifier can be provided to indicate which version of the data model should be used as shown below:
+
+[source,cql]
+----
+using QUICK version '0.3.0'
+----
 
 [[libraries]]
 === Libraries
@@ -506,7 +511,7 @@ The condition of a [.kw]#where# clause is allowed to contain any arbitrary combi
     and C.indication in "Fever"
 ----
 
-Note that because CQL uses three-valued logic, the result of evaluating any given boolean-valued condition may be _unknown_ ([.kw]#null#). For example, if the list of inpatient encounters from the first example contains some elements whose [.id]#period# attribute is [.kw]#null#, the result of the condition for that element will not be [.kw]#false#, but [.kw]#null#, indicating that it is not known whether or not the duration of the encounter was at least 120 days. For the purposes of evaluating a filter, only elements where the condition evaluates to [.kw]#true# are included in the result, effectively treating the unknown results as [.kw]#false#.  For more discussion on three-valued logic, see the section on <<Missing Information>> in the Author's Guide, as well as the section on <<03-developersguide.adoc#nullological-operators,Nullological Operators>> in the Developer's guide.
+Note that because CQL uses three-valued logic, the result of evaluating any given boolean-valued condition may be _unknown_ ([.kw]#null#). For example, if the list of inpatient encounters from the first example contains some elements whose [.id]#period# attribute is [.kw]#null#, the result of the condition for that element will not be [.kw]#false#, but [.kw]#null#, indicating that it is not known whether or not the duration of the encounter was at least 120 days. For the purposes of evaluating a filter, only elements where the condition evaluates to [.kw]#true# are included in the result, effectively ignoring the entries for which the logical expression evaluates to [.kw]#null#.  For more discussion on three-valued logic, see the section on <<Missing Information>> in the Author's Guide, as well as the section on <<03-developersguide.adoc#nullological-operators,Nullological Operators>> in the Developer's guide.
 
 [[shaping]]
 === Shaping
@@ -571,7 +576,7 @@ Calculated values can also be used to determine the sort:
 
 Note that the properties that can be specified within the [.kw]#sort# clause are determined by the result type of the query. In the above example, [id]#lengthOfStay# can be referenced because it is introduced in the [.kw]#return# clause. Because the sort applies after the query results have been determined, alias references are neither required nor allowed in the sort.
 
-If no [.kw]#sort# clause is provided, the order of the result is undefined and may vary by implementation.
+If no [.kw]#sort# clause is provided, the order of the result is unprescribed and is implementation specific.
 
 The [.kw]#sort# clause may include multiple attributes, each with their own sort order:
 
@@ -586,7 +591,7 @@ When the sort elements do not provide a unique ordering (i.e. there is a possibi
 
 A query may only contain a single [.kw]#sort# clause, and it must always appear last in the query.
 
-When the data being sorted includes [.kw]#nulls#, they are sorted first, meaning they will appear at the beginning of the list when the data is sorted ascending, and at the end of the list when the data is sorted descending.
+When the data being sorted includes [.kw]#nulls#, they are considered lower than any non-null value, meaning they will appear at the beginning of the list when the data is sorted ascending, and at the end of the list when the data is sorted descending.
 
 [[relationships]]
 === Relationships

spec/10-c-referenceimplementations.adoc

@@ -38,4 +38,67 @@ Other CQL-related tools such as a graphical CQL grammar parsetree viewer, a Mode
 
 https://github.com/cqframework/clinical_quality_language/wiki/Community-Projects
 
+[[cql-to-elm-translator-and-formatter]]
+=== CQL-to-ELM Translator and Formatter
 
+* https://github.com/cqframework/clinical_quality_language: CQL-to-ELM Translator
+
+[[javascript-execution-engine]]
+=== JavaScript Execution Engine
+
+* https://github.com/cqframework/cql-execution: Java-Script Execution Engine
+* https://github.com/cqframework/cql-exec-fhir: A FHIR data source provider for the CQL Execution framework
+* https://github.com/cqframework/cql-exec-vsac: A VSAC-enabled value set provider for the CQL Execution framework
+* https://github.com/cqframework/cql-exec-examples: Simple examples demonstrating how to use cql-execution, cql-exec-fhir, and cql-exec-vasc
+
+[[cql-translation-service]]
+=== CQL Translation Service
+
+* https://github.com/cqframework/cql-translation-service: RESTful service for translating CQL to ELM
+
+[[java-execution-engine]]
+=== Java Execution Engine
+
+* https://github.com/dbcg/cql_engine
+
+[[cql-execution-service]]
+=== CQL Execution Service
+
+* https://github.com/dbcg/cql_execution_service
+* https://github.com/AHRQ-CDS/AHRQ-CDS-Connect-CQL-SERVICES: Expose CQL via Custom-API or CDS Hooks interface (built on JavaScript CQL Execution Engine)
+
+[[atom-plugin]]
+=== Atom Plugin
+
+* https://github.com/cqframework/atom-cql-support
+
+[[cds-connect]]
+=== CDS Connect
+
+* https://cds.ahrq.gov/: Repository of CDS including CQL-based artifacts
+* https://cds.ahrq.gov/authoring/: CDS Authoring Tool capable of exporting FHIR-based CQL logic
+* https://github.com/AHRQ-CDS/AHRQ-CDS-Connect-Authoring-Tool: CDS Authoring Tool Source Code
+
+[[cql-testing]]
+=== CQL Testing
+
+* https://github.com/AHRQ-CDS/CQL-Testing-Framework
+
+[[cql-server-side-functionality]]
+=== CQL Server-side Functionality
+
+* https://github.com/samply/blaze: A FHIR® server with internal, fast CQL Evaluation Engine
+* https://github.com/dbcg/cqf-ruler: HAPI FHIR server plugin to enable CQL evaluation and Clinical Reasoning functionality
+* https://github.com/PheMA/cql-on-omop: Translates CQL (ELM) to OMOP for evaluation against an OHDSI repository
+
+[[cql-tooling]]
+=== CQL Tooling
+
+* https://github.com/cqframework/cqf-tooling: Tooling to support CQL library tooling and other handy utilities related to CQL-based FHIR content
+
+[[formatting-and-usage]]
+== Formatting and Usage
+
+Because of the flexibility and broad applicability of CQL, it necessarily covers a breadth of topics. The Clinical Quality Framework Initiative provides recommendations and guidance to ensure consistent and appropriate use of CQL in the following wiki:
+
+* https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Formatting-and-Usage-Topics

spec/cql/cql.g4

@@ -10,17 +10,21 @@ import fhirpath;
 /*
  * Parser Rules
  */
-
-library
+ 
+definition
     :
-    libraryDefinition?
     usingDefinition*
     includeDefinition*
     codesystemDefinition*
     valuesetDefinition*
     codeDefinition*
     conceptDefinition*
     parameterDefinition*
+    ;
+
+library
+    :
+    libraryDefinition?
     statement*
     EOF
     ;

spec/index.adoc

@@ -24,7 +24,7 @@ link:license.html[License]
 
 http://cql.hl7.org/history.html[Version History]
 
-link:00-executivesummary.html[0. Executive Summary]
+link:00-executivesummary.html[Executive Summary]
 
 [[organization-of-this-specification]]
 == Organization of this Specification
@@ -45,7 +45,7 @@ link:06-translationsemantics.html[Chapter 6] – Translation Semantics describes
 
 link:07-physicalrepresentation.html[Chapter 7] – Physical Representation is reference documentation for the XML schema used to persist ELM.
 
-link:08-a-cqlsyntax.html[Appendix A – CQL Syntax Formal Specification] discusses the ANTLR4 grammar for the Clinical Quality Language.
+link:08-a-cqlsyntax.html[Appendix A] – CQL Syntax Formal Specification discusses the ANTLR4 grammar for the Clinical Quality Language.
 
 link:09-b-cqlreference.html[Appendix B] – CQL Reference provides a complete reference for the types and operators available in CQL, and is intended to be used by authors and developers alike.
 

spec/tests.md

@@ -14,7 +14,7 @@ This is the same test format used by the FHIRPath specification.
 
 <a href="tests.zip">Test Source</a>.
 
-Note that these tests have not been fully updated to the 1.4 specification.
+Note that these tests have not been fully updated to the 1.5 specification.
 
 At this point, the tests cover the following sections of the specification:
 
@@ -35,5 +35,3 @@ At this point, the tests cover the following sections of the specification:
 
 The tests defined here are informative, not normative aspects of the specification. If there is a discrepancy between the behavior of a test and the specification, the specification should be considered the source of truth.
 {:.note-info}
-
-

spec/v1.5-changelog.adoc

@@ -3,7 +3,7 @@
 :backend: xhtml
 :toc:
 
-== Normative Ballot Changes
+== Normative/Trial-Use Ballot Changes
 
 === Compatible, Substantive