Skip to content

ecl.md

Latest commit

 

History

History
236 lines (188 loc) · 11.1 KB

ecl.md

File metadata and controls

236 lines (188 loc) · 11.1 KB
Raw

ECL Implementation Status

This document tracks which Expression Constraint Language features Hermes supports. For usage examples with the HTTP API, see search-and-ecl.md.

Hermes parses the full ECL v2.2 grammar. The parser accepts all valid ECL expressions; limitations are in the evaluator, which throws an exception for unsupported clauses. This means adding support for a feature never requires changing the grammar — only adding evaluation logic.

ECL Core and Extended profiles

ECL v2.3 (March 2026) introduced two conformance profiles, defined by separate ABNF grammars in the IHTSDO ECL repository:

  • ECL Core — a minimal subset for terminology servers. Covers hierarchy operators, refinements (expression, numeric, string and boolean comparison), compound expressions, attribute groups (without cardinality), dot notation, memberOf, concept active filter, history supplements, and comments. No cardinality, no reverse flag, no description or member filters.
  • ECL Extended — everything in Core plus cardinality, reverse flag, description/concept/member filters, dialect filters, alternate identifiers, and reference set field selection.

Hermes implements most of ECL Core. The remaining Core gaps — all planned — are: string and boolean concrete refinements, > * and >! * wildcards, disjunction (OR) and parenthesized conditions within attribute groups, and two v2.3 additions (^R refsetContainingAny and active = *). Hermes also implements most of ECL Extended. See the summary table below for complete status.

Summary

Feature Profile Status
Descendant of (<) Core Yes
Descendant or self of (<<) Core Yes
Child of (<!) Core Yes
Child or self of (<<!) Core Yes
Ancestor of (>) Core Yes
Ancestor or self of (>>) Core Yes
Parent of (>!) Core Yes
Parent or self of (>>!) Core Yes
Top of set (!!>) Core Yes
Bottom of set (!!<) Core Yes
Wildcard (*) Core Yes
Wildcard > *, >! * Core Planned
Concept references with pipe terms Core Yes
Conjunction (AND, ,) Core Yes
Disjunction (OR) Core Yes
Exclusion (MINUS) Core Yes
Nested expressions ( ) Core Yes
Attribute refinement (:) Core Yes
Expression comparison (=, !=) Core Yes
Numeric concrete (#value) Core Yes
String concrete ("value") Core Planned
Boolean concrete (true/false) Core Planned
Attribute groups { } Core Yes
Dot notation (.) Core Yes
MemberOf (^) Core Yes
MemberOf with wildcard (^ *) Core Yes
RefsetContainingAny (^R) Core Planned
Concept active filter Core Yes
Active filter wildcard (active = *) Core Planned
History supplements Core Yes
Comments (/* */) Core Yes
Attribute cardinality ([min..max]) Extended Yes
Attribute group cardinality Extended Planned
Cardinality + reverse flag Extended Planned
[0..0] with != Extended Planned
Reverse flag (R) Extended Yes
Refset field selection (^ [field]) Extended No
Description term filter Extended Yes
Description type filter Extended Yes
Description dialect filter (= only) Extended Yes
Description active filter Extended Yes
Description module filter Extended Planned
Description effectiveTime filter Extended No
Description ID filter Extended Planned
Description language filter Extended No
Concept definition status filter Extended No
Concept module filter Extended No
Concept effectiveTime filter Extended No
Member active filter Extended Yes
Member module filter Extended Yes
Member effectiveTime filter Extended Yes
Member field filters (no time) Extended Yes
Alternate identifiers Extended No

Supported features

Hierarchy operators

All ten hierarchy operators are supported: <, <<, <!, <<!, >, >>, >!, >>!, !!>, and !!<. Wildcards work with << *, >> *, < *, <! *, <<! *, and >>! *. Wildcards with > * and >! * are planned.

Compound expressions

Conjunction (AND and ,), disjunction (OR), and exclusion (MINUS) are all supported, including nested parenthesized expressions.

Refinements

Attribute refinements with expression comparison operators (=, !=) and numeric concrete values (#250, #62.5) with all comparison operators (=, !=, <, <=, >, >=) are supported.

String concrete refinements (e.g., 3460481009 = "PANADOL") and boolean concrete refinements (e.g., * : * = true) are not yet supported.

Attribute groups

Attribute groups with same-group semantics are supported. Multiple attributes within { } are conjunctive (AND). Disjunction (OR) within groups and parenthesized group conditions are not yet supported.

Cardinality

Cardinality constraints on individual attributes are supported: [0..0], [1..1], [0..1], [2..*], etc. Group cardinality ([1..3] { ... }), combined cardinality with reverse flag ([3..3] R 127489000 = *), and [0..0] with != (universal quantification) are not yet supported.

Dot notation

Single and chained dot notation for attribute value navigation is supported: . 363698007 and . 363698007 . 116680003.

MemberOf

MemberOf (^) is supported with concept IDs (^ 723264001), wildcards (^ * for all installed reference sets), and nested expressions (^ (<< 723264001)). Member filter constraints can be applied to refine results.

Reference set field selection (^ [targetComponentId] ...) is not supported.

Reverse flag

The reverse flag (R) is supported on simple attributes. It is not yet supported in combination with cardinality constraints.

Description filters

Supported description filters:

  • Term filter: match (term = "heart attack") and wildcard (term = wild:"*sclero*") with locale-aware case folding
  • Type filter: by token (type = syn, type = fsn, type = def) and by ID (typeId = 900000000000013009)
  • Dialect filter: by alias (dialect = en-gb) and by ID (dialectId = 999001261000000100), including dialect sets (dialect = (en-gb en-us)). Only the = operator is supported; != is not yet implemented, nor are per-dialect acceptability annotations (e.g. dialect = (en-gb preferred))
  • Active filter: active = true / active = 1

Concept filters

Only the active filter is supported ({{ C active = true }}). Definition status, module, and effectiveTime filters are not planned — see below.

Member filters

All member filter types are supported:

  • Active filter: {{ M active = true }}
  • Module filter: {{ M moduleId = ... }} with = and !=
  • EffectiveTime filter: with all comparison operators
  • Field filters: numeric, boolean, string (typed search), and expression comparison on arbitrary reference set member fields (e.g., {{ M mapTarget = "J45.9" }}). Time comparison on arbitrary fields is not yet supported (only the dedicated effectiveTime filter handles dates)

History supplements

All history profiles are supported: {{ +HISTORY }}, {{ +HISTORY-MIN }}, {{ +HISTORY-MOD }}, {{ +HISTORY-MAX }}, and custom history subsets ({{ +HISTORY (subexpression) }}).

Comments

Block comments (/* ... */) are supported.

Planned

Features that will be implemented:

Feature Notes
> * and >! * Return all non-leaf concepts. Trivial to add.
Per-dialect acceptability annotations dialect = (en-gb preferred) syntax parses but the evaluator does not yet treat the acceptability token as distinct from a dialect alias.
String concrete refinements e.g., 3460481009 = "PANADOL". Concrete string values in attribute refinements.
Boolean concrete refinements e.g., * : * = true.
OR within attribute groups Disjunction inside { } syntax.
Parenthesized group conditions { (attr = val, attr2 = val) } syntax.
Attribute group cardinality [1..3] { 127489000 = < 105590001 }. Cardinality on groups, not individual attributes.
Cardinality + reverse flag [3..3] R 127489000 = *. Combined constraint.
[0..0] with != Universal quantification. Requires care to implement correctly.
Dialect filter != Dialect filters currently only support the = operator.
Description module filter The index already stores module-id; only evaluator wiring is needed.
Description ID filter The index already stores description-id with query helpers in place.

ECL v2.3 features

These require upgrading the ABNF grammar from v2.2 to v2.3:

Feature Notes
^R (refsetContainingAny) Inverse of memberOf — concepts that contain matching reference set members.
Active filter wildcard (active = *) Match both active and inactive. Trivial addition.
Simplified concrete string matching concreteString replaces typedSearchTerm in attribute value matching. Simplifies both grammar and evaluator.

Not currently supported

These features are parsed by the grammar but aren't currently implemented. Most would require expanding the search index — increasing database size for all users — to serve use cases that are primarily relevant to authoring tools rather than clinical or analytic use. Others, such as the language filter, are omitted because they are deprecated in the ECL specification and superseded by better-supported constructs. If you have a use case for one of these features, please open an issue and explain the clinical, analytic, or interoperability need — none of these are closed doors.

Feature Rationale
Concept definition status filter Requires indexing definition status. Primarily useful in authoring (distinguishing primitive from fully defined concepts).
Concept module filter Requires indexing module ID on concepts. Authoring and release management use case.
Concept effectiveTime filter Requires indexing effective time on concepts. Authoring and release management use case.
Description effectiveTime filter Requires indexing effective time on descriptions. Authoring and release management use case.
Alternate identifiers Requires external identifier mapping infrastructure (e.g., LOINC scheme aliases). Cross-terminology mapping is handled via reference set member filters instead.
Refset field selection ^ [targetComponentId] ... — returns specific fields from reference set members rather than concepts. Complex to implement and a niche use case.
Language filter Deprecated in the ECL specification and semantically weaker than dialect filters. language = en only matches the coarse two-letter description language code; it cannot express language reference set membership or acceptability (for example en-GB preferred vs acceptable). Hermes intentionally supports dialect filters instead, because they match how SNOMED CT language selection is performed in practice.