Module params 

Shared $sql-run parameter extraction.

Both the REST handler in helios-rest and the standalone sof-server walk a FHIR Parameters body for the same set of operation parameters (_format, _limit, _since, patient, group, subjectCanonical, subjectReference, subjectResource, resource, header, plus the Parquet options). This module owns the field-name list and the accepted JSON shapes so a new parameter name only needs to be added in one place.

Subject naming

SQL on FHIR 3.0.0-ballot consolidated $viewdefinition-run and $sqlquery-run into a single system-level $sql-run, which names what it acts on through a subject rather than through the request path. The three subject parameters are mutually exclusive and one is required:

Parameter	Names the subject by
subjectCanonical	Canonical URL, optionally with a |version suffix
subjectReference	Literal location — relative on this server, or absolute
subjectResource	Inline resource (POST only)

subjectCanonical and subjectReference are deliberately distinct: a canonical URL is an identity, a literal reference is a location, and the same string can be neither or both. The pre-ballot viewResource / viewReference pair conflated the two and is not accepted.

The extractor is permissive: missing / wrong-typed value[X] fields produce None/empty rather than an error. Strict callers (sof-server) run an additional validation pass on the same JSON for bounds checks (e.g. _limit upper bound, compression allowed values).

Structs

ExtractedRunParams

SoF v2 $viewdefinition-run parameters lifted out of a JSON Parameters resource. Scalar fields hold the first occurrence; patient, group, inline_resources collect every entry (spec is 0..*).

Functions

body_has_subject

Returns true when body names a subject the caller can run — either a bare ViewDefinition resource or a Parameters body carrying one of the three subject parameters.

extract_run_params_from_json

Walks a JSON Parameters body (or any object with a parameter array) and pulls every SoF v2 run-operation field into ExtractedRunParams.

split_csv_refs

Splits a comma-separated reference string into trimmed, non-empty entries. Used by both sof-server and HFS REST to lower a single ?group=Group/a,Group/b query value into the spec’s 0..* shape. Returns an empty Vec when the input is None or yields no non-empty entries.