FHIRPath Specification
3.1.0 - STU 3
FHIRPath Specification
3.1.0 - STU 3
FHIRPath Specification, published by Implementable Technology Specifications WG. This guide is not an authorized publication; it is the continuous build for version 3.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/FHIRPath/ and changes regularly. See the Directory of published versions
| Page standards status: Informative |
| Id | Expectation | Rule |
|---|---|---|
| SHALL MAY SHOULD SHOULD NOT | ||
| §1 | SHALL | dec1:Implementations can provide support for larger decimals and higher precision, but SHALL provide at least the range and precision defined here. |
| §2 | SHALL | dec1:Implementations can provide support for larger decimals and higher precision, but SHALL provide at least the range and precision defined here.§1 |
| §3 | SHALL | tm1:Implementations can provide support for higher precision, but SHALL provide at least the range and precision defined here. |
| §4 | SHALL | tm1:Implementations can provide support for higher precision, but SHALL provide at least the range and precision defined here.§3 |
| §5 | SHALL | dt1:Implementations can provide support for larger ranges and higher precision, but SHALL provide at least the range and precision defined here. |
| §6 | MAY | v1:Other specifications MAY introduce their own variables |
| §7 | MAY | ic2:If the input collection contains multiple items, the evaluation of the expression will end and signal an error to the calling environment. However element selectors can return multiples where the object's structure supports it for that element. If not the engine MAY throw an error. |
| §8 | SHOULD | r1:Implementations SHOULD include safety mechanisms to prevent infinite loops. |
| §9 | SHOULD | r1:Implementations SHOULD include safety mechanisms to prevent infinite loops.§8 |
| §10 | SHOULD MAY | r4:Implementations SHOULD include safety mechanisms to prevent infinite loops. An implementation MAY impose a limit on the number of iterations, or MAY statically analyze the expression to ensure it navigates to child elements within the hierarchical structure. |
| §11 | SHOULD MAY | r4:Implementations SHOULD include safety mechanisms to prevent infinite loops. An implementation MAY impose a limit on the number of iterations, or MAY statically analyze the expression to ensure it navigates to child elements within the hierarchical structure.§10 |
| §12 | SHALL | fmt1:Implementations SHALL support at least 3 digits (milliseconds); support for additional digits is optional. |
| §13 | SHALL | uc1:When an operation requires one of its arguments to be converted to the "most granular" unit, implementations SHALL select the smaller unit of measurement. |
| §14 | SHALL | uc1:When an operation requires one of its arguments to be converted to the "most granular" unit, implementations SHALL select the smaller unit of measurement.§13 |
| §15 | SHALL | uc2:If converting to/from years or months you SHALL use the shortest conversion chain possible (i.e. don't convert from days to months to years when you can go from direct days to years). |
| §16 | SHALL | uc2:If converting to/from years or months you SHALL use the shortest conversion chain possible (i.e. don't convert from days to months to years when you can go from direct days to years).§15 |
| §17 | SHOULD | mch1:Regular expressions SHOULD function consistently, regardless of any culture- and locale-specific settings in the environment, SHOULD be case-sensitive, use 'single line' mode and allow Unicode characters. |
| §18 | SHOULD | mch1:Regular expressions SHOULD function consistently, regardless of any culture- and locale-specific settings in the environment, SHOULD be case-sensitive, use 'single line' mode and allow Unicode characters.§17 |
| §19 | SHOULD | mch2:Regular expressions SHOULD function consistently, regardless of any culture- and locale-specific settings in the environment, SHOULD be case-sensitive, use 'single line' mode and allow Unicode characters. |
| §20 | SHOULD NOT | dcd1:It SHOULD NOT replace with the unicode replacement character or allow ill formed UTF-8 content. |
| §21 | SHOULD | trc1:This log SHOULD be made available to the user in some appropriate fashion. |
| §22 | SHOULD | trc1:This log SHOULD be made available to the user in some appropriate fashion.§21 |
| §23 | SHOULD | n1:implementations SHOULD consider providing options appropriate for their environment. |
| §24 | SHOULD | n1:implementations SHOULD consider providing options appropriate for their environment.§23 |
| §25 | SHOULD | n2:To ensure deterministic evaluation, these operators SHOULD return the same value regardless of how many times they are evaluated within any given expression (i.e. now() SHOULD always return the same DateTime in a given expression, timeOfDay() SHOULD always return the same Time in a given expression, and today() SHOULD always return the same Date in a given expression.) |
| §26 | SHALL | q6:Implementations are not required to fully support operations on units, but they SHALL at least respect units, recognizing when units differ. |
| §27 | SHALL | q7:Implementations are not required to fully support operations on units, but they SHALL at least respect units, recognizing when units differ. |
| §28 | SHALL | cmp1:Implementations are not required to fully support operations on units, but they SHALL at least respect units, recognizing when units differ. |
| §29 | MAY | b1:implementations MAY use short-circuit evaluation to reduce computation |
| §30 | MAY | b1:implementations MAY use short-circuit evaluation to reduce computation§29 |
| §31 | SHALL | m1:Implementations are not required to fully support operations on units, but they SHALL at least respect units, recognizing when units differ. |
| §32 | SHALL | m3:Implementations that to not support processing UCUM units SHALL return empty when unable to correctly handle the units. |
| §33 | SHALL | ad1:Implementations are not required to fully support operations on units, but they SHALL at least respect units, recognizing when units differ. |
| §34 | SHOULD | dta2:Implementers SHOULD produce a warning when decimal fractions are ignored in date/time arithmetic operations. |
| §35 | SHALL | sum1:All items in the input collection SHALL be the same type, otherwise an exception is thrown. |
| §36 | SHALL | min1:All items in the input collection SHALL be the same type, otherwise an exception is thrown. |
| §37 | SHALL | max1:All items in the input collection SHALL be the same type, otherwise an exception is thrown. |
| §38 | SHALL | avg1:All items in the input collection SHALL be the same type, otherwise an exception is thrown. |
| §39 | SHOULD | rt1:the default run-time behavior of a compliant FHIRPath implementation SHOULD be weakly typed. |
| §40 | SHOULD | rt1:the default run-time behavior of a compliant FHIRPath implementation SHOULD be weakly typed.§39 |
| §41 | SHOULD | mdl1:tooling SHOULD respect the case-sensitive settings for each model. |
| §df1 | SHOULD | When computing the difference between datetime values with different timezone offsets, implementations SHOULD normalize the timezone when a precision of hour, minute, second, or millisecond is requested. |
| §dta1 | SHALL | calculations involving date/times and calendar durations SHALL use calendar semantics as specified in [ISO8601]. |
| §dta3 | SHOULD | Authors SHOULD consider applying appropriate rounding functions (round(), floor(), truncate(), or ceiling()) to quantity-valued inputs with decimal values before using them in date/time arithmetic expressions where quantity values might not be whole numbers. |
| §dur1 | SHOULD | When computing the duration between DateTime values with different timezone offsets, implementations SHOULD normalize the timezone when a precision of hour, minute, second, or millisecond is requested. |
| §ic1 | MAY | If the «typename» is omitted, an implementation MAY use a type appropriate to the context, or an anonymous type. |
| §if1 | SHALL | The criterion expression SHALL evaluate to a Boolean, consistent with singleton evaluation of collections. |
| §if2 | SHOULD | In other words, true-result SHOULD only be evaluated if the criterion evaluates to true, and otherwise-result SHOULD only be evaluated otherwise. |
| §imp1 | MAY | Note that implies MAY use short-circuit evaluation in the case that the first operand evaluates to false. |
| §m2 | SHALL | Implementations that do support units SHALL do so as specified by the [UCUM] specification. |
| §q1 | SHALL | Implementations SHALL support equality, equivalence, comparison and arithmetic operations on quantities with units where the units are the same value, case-sensitively. |
| §q2 | MAY | Implementations that do NOT support UCUM unit conversion MAY return empty ({ }) for calculations involving quantities with different units, except for equivalence, which returns false when a required conversion is not supported. |
| §q3 | SHALL | Implementations that DO support UCUM conversions SHALL support implicit conversions where operations between quantities with different units are performed, and also explicitly through toQuantity(unit). |
| §q4 | SHALL | If the unit argument is provided, it SHALL be the string representation of a UCUM code (or a FHIRPath calendar duration keyword). |
| §q5 | SHOULD | If the unit argument is provided, it SHOULD be handled in the same way it is in the toQuantity() function above, except that where an empty result would result, false is returned. |