CQL Serialization - cqframework/clinical_quality_language GitHub Wiki

CQL Serialization

This page documents a proposed CQL serialization format using JSON serialization as specified in rfc8259.

CQL Types

  • Boolean
  • Integer
  • Long
  • Decimal
  • String
  • Date
  • DateTime
  • Time
  • Quantity
  • Ratio
  • Vocabulary
    • CodeSystem
    • ValueSet
  • Code
  • Concept
  • Interval
  • List
  • Tuple
  1. Any JSON-mapped primitive type can be represented directly as the JSON serialization:
    1. Boolean
    2. Integer
    3. Decimal (with the exception that a decimal SHALL be present)
    4. String
  2. Any value can be represented as a class value:
    1. A JSON object with a nominated element @type that is the CQL type specifier for the type of the value
      1. For tuple types specifically, the @type element is optional, and if specified, does not have to be the full tuple type, it can be just "Tuple"
    2. For primitive types, a nominated element value that is the JSON-mapped primitive value, or a String that is the CQL literal for the value
    3. For structured types, the set of elements in the structure
    4. For Interval types, low, lowClosed, high, and highClosed
    5. For Ratio types, numerator, and denominator
    6. For Quantity types, value and unit

Examples

Boolean

define CQLBooleanExample: true

true

or as a class:

{
  "@type": "System.Boolean",
  "value": true
}

Code

codesystem ExampleCodeSystem: 'http://hl7.org/fhir/uv/cql/CodeSystem/example'
code ExampleCode: 'example-code' from ExampleCodeSystem

define CQLCodeExample: ExampleCode

{
  "@type": "System.Code",
  "code": "example-code",
  "system": "http://hl7.org/fhir/uv/cql/CodeSystem/example"
}

CodeSystem

codesystem ExampleCodeSystem: 'http://hl7.org/fhir/uv/cql/CodeSystem/example'

define CQLCodeSystemExample: ExampleCodeSystem

{
  "@type": "System.CodeSystem",
  "id": "http://hl7.org/fhir/uv/cql/CodeSystem/example",
  "name": "ExampleCodeSystem"
}

Concept

codesystem ExampleCodeSystem: 'http://hl7.org/fhir/uv/cql/CodeSystem/example'
code ExampleCode: 'example-code' from ExampleCodeSystem
concept ExampleConcept: { ExampleCode }

define CQLConceptExample: ExampleConcept

{
  "@type": "System.Concept",
  "codes": [
    {
      "@type": "System.Code",
      "code": "example-code",
      "system": "http://hl7.org/fhir/uv/cql/CodeSystem/example"
    }
  ]
}

Date

define CQLDateExample: @2024-01-01

{
  "@type": "System.Date",
  "value": "@2024-01-01"
}

DateTime

define CQLDateTimeExample: @2024-01-01T10:30:00Z

{
  "@type": "System.DateTime",
  "value": "@2024-01-01T10:30:00Z"
}

Decimal

define CQLDecimalExample: 10.0

10.0

NOTE: When rendered as a JSON-mapped primitive, decimal values SHALL include a decimal point

or as a structured value:

{
  "@type": "System.Decimal",
  "value": 10.0
}

Long

define CQLLongExample: 10L

{
  "@type": "System.Long",
  "value": 10
}

Integer

define CQLIntegerExample: 10

10

or as a class:

{
  "@type": "System.Integer",
  "value": 10
}

Quantity

define CQLQuantityExample: 10 'mg'

{
  "@type": "System.Quantity",
  "value": 10,
  "unit": "mg"
}

Ratio

define CQLRatioExample: 5 'mg' : 10 'mg'

{
  "@type": "System.Ratio",
  "numerator":
    {
      "@type": "System.Quantity",
      "value": 5,
      "unit": "mg"
    },
  "denominator":
    {
      "@type": "System.Quantity",
      "value": 10,
      "unit": "mg"
    }
}

String

define CQLStringExample: 'John'

"John"

or as a class:

{
  "@type": "System.System",
  "value": "John"
}

Time

define CQLTimeExample: @T10:30:00

{
  "@type": "System.Time",
  "value": "@T10:30:00"
}

ValueSet

valueset ExampleValueSet: 'http://hl7.org/fhir/uv/cql/ValueSet/example'

define CQLValueSetExample: ExampleValueSet

{
  "@type": "System.ValueSet",
  "id": "http://hl7.org/fhir/uv/cql/ValueSet/example",
  "name": "ExampleValueSet"
}

Vocabulary

parameter ExampleVocabulary Vocabulary default ExampleValueSet

define CQLVocabularyExample: ExampleVocabulary

{
  "@type": "System.Vocabulary",
  "id": "http://hl7.org/fhir/uv/cql/ValueSet/example",
  "name": "ExampleValueSet"
}

Interval<Date>

define CQLDateIntervalExample: Interval[@2024-01-01, @2024-01-31]

{
  "@type": "Interval<System.Date>",
  "low":
    {
      "@type": "System.Date",
      "value": "@2024-01-01"
    },
  "lowClosed": true
  "high":
    {
      "@type": "System.Date",
      "value": "@2024-01-31"
    },
  "highClosed": true
}

Interval<DateTime>

define CQLDateTimeIntervalExample: Interval[@2024-01-01T10:30:00Z, @2024-01-31T10:30:00Z]

{
  "@type": "Interval<System.DateTime>",
  "low":
    {
      "@type": "System.DateTime",
      "value": "@2024-01-01T10:30:00Z"
    },
  "lowClosed": true
  "high":
    {
      "@type": "System.DateTime",
      "value": "@2024-01-31T10:30:00Z"
    },
  "highClosed": true
}

Interval<Time>

define CQLTimeIntervalExample: Interval[@T10:30:00, @T11:30:00]

{
  "@type": "Interval<System.Time>",
  "low":
    {
      "@type": "System.Time",
      "value": "@T10:30:00"
    },
  "lowClosed": true
  "high":
    {
      "@type": "System.Time",
      "value": "@T11:30:00"
    },
  "highClosed": true
}

Interval<Integer>

define CQLIntegerIntervalExample: Interval[5, 10]

{
  "@type": "Interval<System.Integer>",
  "low": 5
  "lowClosed": true
  "high": 10
  "highClosed": true
}

Interval<Quantity>

define CQLQuantityIntervalExample: Interval[5 'mg', 10 'mg']

{
  "@type": "Interval<System.Quantity>",
  "low":
    {
      "@type": "System.Quantity",
      "value": 5.0,
      "unit": "mg"
    },
  "lowClosed": true
  "high":
    {
      "@type": "System.Quantity",
      "value": 10.0,
      "unit": "mg"
    },
  "highClosed": true
}

List

define CQLListExample: { 1, 2, 3, 4, 5 }

[ 1, 2, 3, 4, 5 ]

Tuple

define CQLTupleExample: { X: 1, Y: 1 }

{
  "X": 1,
  "Y": 1
}

Choice List

define CQLChoiceListExample: List<Choice<Integer, Decimal>> { 1, 1.0 }

[ 1, 1.0 ]

Tuple List

define CQLTupleListExample: { { X: 1, Y: 1 }, { X: 1, Y: 2 }, { X: 1, Y: 3 } }

[
  { "X": 1, "Y": 1 },
  { "X": 1, "Y": 2 },
  { "X": 1, "Y": 3 }
]

Complex Tuple

define CQLComplexTupleExample: { id: 1, name: 'Patrick', address: { { street: '123 Spinning Ave', city: 'Dayton', state: 'OH' } } }

{
  "id": 1,
  "name": "Patrick",
  "address": [
    {
      "street": "123 Spinning Ave",
      "city": "Dayton",
      "state": "OH"
    }
  ]
}

Complex Tuple List

define CQLComplexTupleExample: { id: 1, name: 'Patrick', address: { { street: '123 Spinning Ave', city: 'Dayton', state: 'OH' } } }
define CQLComplexTupleListExample: { CQLComplexTupleExample }

[
  {
    "id": 1,
    "name": "Patrick",
    "address": [
      {
        "street": "123 Spinning Ave",
        "city": "Dayton",
        "state": "OH"
      }
    ]
  }
]

Empty List

define CQLComplexTupleExample: { id: 1, name: 'Patrick', address: { { street: '123 Spinning Ave', city: 'Dayton', state: 'OH' } } }
define CQLComplexTupleListExample: { CQLComplexTupleExample }
define CQLEmptyListExample: CQLComplexTupleListExample E where false

[ ]