Vcl

You are an expert in the FHIR ValueSet Compose Language (VCL), a domain-specific language for expressing ValueSet.compose content as a compact, URL-safe string. VCL is inspired by SNOMED CT's Expression Constraint Language and is defined in the FHIR IG Guidance.

When to use VCL

Use VCL when the goal is to convey a ValueSet.compose rule in a single string, typically inside a URL passed to $expand or $validate-code. VCL covers everything compose can express: code system selection, enumerated codes, filters, included sub-ValueSets, exclusions, and property navigation - across one or many code systems.

Choose VCL over alternatives when:

• The ValueSet is short-lived or query-time only and a full ValueSet resource would be heavyweight.
• The expression spans multiple code systems and needs to be carried in a URL.
• The use case is dynamic generation (e.g. an autocomplete that builds expressions on the fly).

Prefer SNOMED CT ECL (see the snomed-ecl skill) when working purely within SNOMED CT and the existing http://snomed.info/sct?fhir_vs=ecl/... syntax is sufficient. ECL is richer for SNOMED-specific concept-model navigation; VCL is broader but simpler.

Lexical rules

• Whitespace (spaces, tabs) is ignored except inside quoted values. Newlines and carriage returns are not permitted.
• Codes and values use unquoted form (SCODE) when they consist only of alphanumerics, hyphens, and underscores starting with an alphanumeric. Anything else (periods, slashes, colons, spaces) requires double quotes.
• Inside quoted values, only " and \ are escapable, written as \" and \\.
• URIs require an ASCII-letter scheme. Round brackets inside a URI must be percent-encoded (%28, %29) because brackets delimit the systemUri.
• A URI may carry a version pinned with |, e.g. http://loinc.org|2.74.

Codes and the wildcard

Set operators

There is no operator precedence between , and ;. Always use brackets when mixing them.

(A;B),C       // (A or B) and C
A;(B,C)       // A or (B and C)
(A;B)-C       // (A or B) minus C

Filter operators

Filters are written as property OP value. They map directly to ValueSet.compose.include.filter triples (property, op, value).

The ^ operator inside a filter checks property values against an enumerated set, an external ValueSet, or a nested filter. As a top-level expression, ^URI includes all codes from another ValueSet.

System URI prefix

A code system is selected by prefixing a systemUri in round brackets:

(http://loinc.org)4548-4
(http://snomed.info/sct)73211009
(http://snomed.info/sct|http://snomed.info/sct/32506021000036107/version/20230831)73211009

The system applies to the immediately following expression. Combine multiple systems with ;, , or -:

(http://loinc.org)(41995-2;4548-4) - (http://loinc.org)29557-6

Property navigation

The . operator (read as "of") flips a filter so the property is taken from a left-hand set of codes:

B.codeprop                    // values of `codeprop` on code B
{concept < B}.codeprop        // values of `codeprop` over all descendants of B
{B.codeprop1}.codeprop2       // chained navigation

This is the inverse of the ordinary property = code form and is useful for "give me everything pointed to by these codes".

Including another ValueSet

^http://hl7.org/fhir/ValueSet/payeetype

Maps to a compose.include.valueSet entry. Combine with codes, filters or other ValueSets through the usual set operators.

Implicit ValueSet URL form

VCL is most often used inside an implicit ValueSet URL passed to $expand:

http://fhir.org/VCL?v1=[percent-encoded-expression]

Rules:

• The base URL is http://fhir.org/VCL. The query parameter is v1 (the version of the VCL syntax).
• The expression must be percent-encoded. Servers SHALL percent-decode v1 before parsing.
• Round brackets must be encoded as %28 and %29; curly braces as %7B and %7D; the caret ^ as %5E.

Example - all LOINC codes whose parent is one of two codes:

http://fhir.org/VCL?v1=(http://loinc.org)(parent%5E%7BLP46821-2,LP259418-4%7D)

Decoded expression:

(http://loinc.org)(parent^{LP46821-2,LP259418-4})