Merge branch 'main' into async-pattern-alignment

Resolves a conflict in operations.md by keeping this branch's 303 See
Other polling pattern for the bulk export flow; main's side of the
conflict was an indentation-only change.

Author: johngrimes

input/fsh/operations.fsh

@@ -38,12 +38,14 @@ Description: "Export a view definition. User can provide view definition referen
 * parameter[0].part[1].min = 0
 * parameter[0].part[1].max = "1"
 * parameter[0].part[1].type = #Reference
+* parameter[0].part[1].targetProfile = Canonical(ViewDefinition)
 * parameter[0].part[1].documentation = "Reference to a ViewDefinition stored on the server."
 * parameter[0].part[2].name = #viewResource
 * parameter[0].part[2].use = #in
 * parameter[0].part[2].min = 0
 * parameter[0].part[2].max = "1"
-* parameter[0].part[2].type = #Resource
+* parameter[0].part[2].type = #CanonicalResource
+* parameter[0].part[2].targetProfile = Canonical(ViewDefinition)
 * parameter[0].part[2].documentation = "Inline ViewDefinition resource to export."
 
 * parameter[1].name = #clientTrackingId
@@ -254,6 +256,7 @@ Description: "Execute a view definition against supplied or server data."
 * parameter[2].scope[0] = #system
 * parameter[2].scope[1] = #type
 * parameter[2].type = #Reference
+* parameter[2].targetProfile = Canonical(ViewDefinition)
 * parameter[2].documentation = "Reference to a ViewDefinition stored on the server."
 
 * parameter[3].name = #viewResource
@@ -384,7 +387,9 @@ Description: "Execute a SQLQuery Library against ViewDefinition tables."
 * parameter[2].scope[0] = #system
 * parameter[2].scope[1] = #type
 * parameter[2].type = #Reference
-* parameter[2].documentation = "Reference to a SQLQuery Library stored on the server."
+* parameter[2].targetProfile[0] = Canonical(SQLQuery)
+* parameter[2].targetProfile[1] = Canonical(SQLView)
+* parameter[2].documentation = "Reference to a SQLQuery or SQLView Library stored on the server."
 
 * parameter[3].name = #queryResource
 * parameter[3].use = #in
@@ -393,7 +398,9 @@ Description: "Execute a SQLQuery Library against ViewDefinition tables."
 * parameter[3].scope[0] = #system
 * parameter[3].scope[1] = #type
 * parameter[3].type = #Library
-* parameter[3].documentation = "Inline SQLQuery Library resource to execute."
+* parameter[3].targetProfile[0] = Canonical(SQLQuery)
+* parameter[3].targetProfile[1] = Canonical(SQLView)
+* parameter[3].documentation = "Inline SQLQuery or SQLView Library resource to execute."
 
 * parameter[4].name = #parameters
 * parameter[4].use = #in
@@ -459,7 +466,7 @@ Description: "Export SQLQuery Library results asynchronously using the FHIR Asyn
 * parameter[0].max = "*"
 * parameter[0].scope[0] = #system
 * parameter[0].scope[1] = #type
-* parameter[0].documentation = "One or more SQLQuery Libraries to export. Each repetition identifies a single query. Applies at system and type level only; at instance level the bound Library identified by the request URL is the query source and this parameter does not apply."
+* parameter[0].documentation = "One or more SQLQuery or SQLView Libraries to export. Each repetition identifies a single query. Applies at system and type level only; at instance level the bound Library identified by the request URL is the query source and this parameter does not apply."
 * parameter[0].part[0].name = #name
 * parameter[0].part[0].use = #in
 * parameter[0].part[0].min = 0
@@ -471,13 +478,17 @@ Description: "Export SQLQuery Library results asynchronously using the FHIR Asyn
 * parameter[0].part[1].min = 0
 * parameter[0].part[1].max = "1"
 * parameter[0].part[1].type = #Reference
-* parameter[0].part[1].documentation = "Reference to a SQLQuery Library stored on the server."
+* parameter[0].part[1].targetProfile[0] = Canonical(SQLQuery)
+* parameter[0].part[1].targetProfile[1] = Canonical(SQLView)
+* parameter[0].part[1].documentation = "Reference to a SQLQuery or SQLView Library stored on the server."
 * parameter[0].part[2].name = #queryResource
 * parameter[0].part[2].use = #in
 * parameter[0].part[2].min = 0
 * parameter[0].part[2].max = "1"
-* parameter[0].part[2].type = #Resource
-* parameter[0].part[2].documentation = "Inline SQLQuery Library resource to execute."
+* parameter[0].part[2].type = #Library
+* parameter[0].part[2].targetProfile[0] = Canonical(SQLQuery)
+* parameter[0].part[2].targetProfile[1] = Canonical(SQLView)
+* parameter[0].part[2].documentation = "Inline SQLQuery or SQLView Library resource to execute."
 * parameter[0].part[3].name = #parameters
 * parameter[0].part[3].use = #in
 * parameter[0].part[3].min = 0
@@ -504,12 +515,14 @@ Description: "Export SQLQuery Library results asynchronously using the FHIR Asyn
 * parameter[1].part[1].min = 0
 * parameter[1].part[1].max = "1"
 * parameter[1].part[1].type = #Reference
+* parameter[1].part[1].targetProfile = Canonical(ViewDefinition)
 * parameter[1].part[1].documentation = "Reference to a ViewDefinition stored on the server."
 * parameter[1].part[2].name = #viewResource
 * parameter[1].part[2].use = #in
 * parameter[1].part[2].min = 0
 * parameter[1].part[2].max = "1"
-* parameter[1].part[2].type = #Resource
+* parameter[1].part[2].type = #CanonicalResource
+* parameter[1].part[2].targetProfile = Canonical(ViewDefinition)
 * parameter[1].part[2].documentation = "Inline ViewDefinition resource."
 
 // Input parameters — export control (from $viewdefinition-export)

input/pagecontent/OperationDefinition-ViewDefinitionRun-notes.md

@@ -8,26 +8,26 @@
 When using the GET method, the following limitations apply:
 
 1. **No Request Body Parameters**: GET requests cannot include parameters that require a request body:
-    - Cannot provide `viewResource` parameter (inline ViewDefinition)
-    - Cannot provide `resource` parameter (direct resources to transform)
+   - Cannot provide `viewResource` parameter (inline ViewDefinition)
+   - Cannot provide `resource` parameter (direct resources to transform)
 2. **Available Parameters**: Only parameters that can be passed as query parameters are supported:
-    - `_format` - Output format specification
-    - `header` - Include CSV headers (for CSV format)
-    - `patient` - Filter by patient reference
-    - `group` - Filter by group membership
-    - `_since` - Filter by last updated time
-    - `_limit` - Limit number of result rows
-    - `source` - External data source
+   - `_format` - Output format specification
+   - `header` - Include CSV headers (for CSV format)
+   - `patient` - Filter by patient reference
+   - `group` - Filter by group membership
+   - `_since` - Filter by last updated time
+   - `_limit` - Limit number of result rows
+   - `source` - External data source
 
 3. **Use Cases**: GET is suitable for:
-    - Instance-level invocations where the ViewDefinition is identified by the URL path
-    - Simple filtering and formatting of server data
-    - Quick queries without complex configuration
+   - Instance-level invocations where the ViewDefinition is identified by the URL path
+   - Simple filtering and formatting of server data
+   - Quick queries without complex configuration
 
 4. **When POST is Required**: Use POST instead of GET when you need to:
-    - Provide an inline ViewDefinition via `viewResource` parameter
-    - Supply resources directly via `resource` parameter for transformation
-    - Pass complex parameter values that cannot be represented as query strings
+   - Provide an inline ViewDefinition via `viewResource` parameter
+   - Supply resources directly via `resource` parameter for transformation
+   - Pass complex parameter values that cannot be represented as query strings
 
 #### Data Sources
 
@@ -135,7 +135,7 @@ Optional filtering parameters:
 ##### View Reference/Resource Clarification {#viewreference-clarification}
 
 Only one of the `viewReference` or `viewResource` parameters can be provided.
-When invoking this operation at the instance level (e.g. ViewDefinition/{id}/$run), the server SHALL automatically infer the `viewReference` parameter from the path parameter.
+When invoking this operation at the instance level (e.g. ViewDefinition/{id}/$viewdefinition-run), the server SHALL automatically infer the `viewReference` parameter from the path parameter.
 
 The `viewReference` parameter MAY be specified using any of the following formats:
 
@@ -222,7 +222,7 @@ resources and every unwrapped bundle entry.
 ##### Example 1: Instance-level GET with CSV output
 
 ```http
-GET /ViewDefinition/patient-demographics/$run HTTP/1.1
+GET /ViewDefinition/patient-demographics/$viewdefinition-run HTTP/1.1
 Accept: text/csv
 ```
 
@@ -240,7 +240,7 @@ pt-3,1992-07-08,Williams,Robert
 ##### Example 2: Type-level POST with inline ViewDefinition
 
 ```http
-POST /ViewDefinition/$run HTTP/1.1
+POST /ViewDefinition/$viewdefinition-run HTTP/1.1
 Accept: application/json
 Content-Type: application/fhir+json
 
@@ -278,7 +278,7 @@ Content-Type: application/json
 ##### Example 3: POST with direct resources
 
 ```http
-POST /ViewDefinition/$run HTTP/1.1
+POST /ViewDefinition/$viewdefinition-run HTTP/1.1
 Accept: text/csv
 Content-Type: application/fhir+json
 
@@ -340,7 +340,7 @@ pt-2,2012-03-30,Doe,John
 ##### Example 4: GET with filters
 
 ```http
-GET /ViewDefinition/encounters/$run?patient=Patient/123&_limit=10&_format=ndjson HTTP/1.1
+GET /ViewDefinition/encounters/$viewdefinition-run?patient=Patient/123&_limit=10&_format=ndjson HTTP/1.1
 ```
 
 ```http
@@ -360,7 +360,7 @@ against each entry. This request is equivalent to Example 3, which passed the
 two Patients as discrete `resource` values.
 
 ```http
-POST /ViewDefinition/$run HTTP/1.1
+POST /ViewDefinition/$viewdefinition-run HTTP/1.1
 Accept: text/csv
 Content-Type: application/fhir+json
 
@@ -429,7 +429,7 @@ All error responses (4xx and 5xx) SHOULD include an `OperationOutcome` resource
 When the server does not support certain parameters, it should return `400 Bad Request`:
 
 ```http
-GET /ViewDefinition/123/$run?_since=2021-01-01 HTTP/1.1
+GET /ViewDefinition/123/$viewdefinition-run?_since=2021-01-01 HTTP/1.1
 Accept: application/json
 ```
 
@@ -455,7 +455,7 @@ Content-Type: application/fhir+json
 When the provided ViewDefinition is invalid, return `422 Unprocessable Entity`:
 
 ```http
-POST /ViewDefinition/$run HTTP/1.1
+POST /ViewDefinition/$viewdefinition-run HTTP/1.1
 Content-Type: application/fhir+json
 Accept: application/json
 
@@ -498,7 +498,7 @@ Content-Type: application/fhir+json
 When the referenced ViewDefinition does not exist:
 
 ```http
-GET /ViewDefinition/non-existent/$run HTTP/1.1
+GET /ViewDefinition/non-existent/$viewdefinition-run HTTP/1.1
 Accept: application/json
 ```
 
@@ -523,7 +523,7 @@ Content-Type: application/fhir+json
 When required parameters are missing:
 
 ```http
-POST /ViewDefinition/$run HTTP/1.1
+POST /ViewDefinition/$viewdefinition-run HTTP/1.1
 Content-Type: application/fhir+json
 Accept: text/csv
 
@@ -554,7 +554,7 @@ Content-Type: application/fhir+json
 When an unsupported format is requested:
 
 ```http
-GET /ViewDefinition/123/$run?_format=xml HTTP/1.1
+GET /ViewDefinition/123/$viewdefinition-run?_format=xml HTTP/1.1
 ```
 
 ```http
@@ -579,7 +579,7 @@ Content-Type: application/fhir+json
 When filtering by a patient that doesn't exist:
 
 ```http
-GET /ViewDefinition/lab-results/$run?patient=Patient/non-existent HTTP/1.1
+GET /ViewDefinition/lab-results/$viewdefinition-run?patient=Patient/non-existent HTTP/1.1
 Accept: application/json
 ```
 

input/pagecontent/operations-capability.md

@@ -7,19 +7,36 @@ The CapabilityStatement.rest.resource array SHALL contain an entry for the ViewD
 - An operation element with:
   - name = "$viewdefinition-export"
   - definition = "http://sql-on-fhir.org/OperationDefinition/$viewdefinition-export"
-- An operation element with:  
-  - name = "$run"
-  - definition = "http://sql-on-fhir.org/OperationDefinition/$run"
+- An operation element with:
+  - name = "$viewdefinition-run"
+  - definition = "http://sql-on-fhir.org/OperationDefinition/$viewdefinition-run"
 
 If the server supports CRUD and search interactions for the ViewDefinition resource type, the interaction array SHALL include the appropriate codes:
 
 - read
-- search-type  
+- search-type
 - write
 - patch
 - delete
 - create
 
+The CapabilityStatement.rest.resource array SHALL also contain an entry for the Library resource type (a SQLQuery is a profile of Library) with:
+
+- An operation element with:
+  - name = "$sqlquery-run"
+  - definition = "http://sql-on-fhir.org/OperationDefinition/$sqlquery-run"
+- An operation element with:
+  - name = "$sqlquery-export"
+  - definition = "http://sql-on-fhir.org/OperationDefinition/$sqlquery-export"
+
+If the server supports CRUD and search interactions for the Library resource type, the interaction array SHALL include the appropriate codes:
+
+- read
+- search-type
+- write
+- patch
+- delete
+- create
 
 ## Example
 
@@ -58,15 +75,32 @@ Content-Type: application/fhir+json
           "definition": "http://sql-on-fhir.org/OperationDefinition/$viewdefinition-export"
         },
         {
-          "name": "$validate",
-          "definition": "http://sql-on-fhir.org/OperationDefinition/$validate"
+          "name": "$viewdefinition-run",
+          "definition": "http://sql-on-fhir.org/OperationDefinition/$viewdefinition-run"
+        }
+      ]
+    },
+    {
+      "type": "Library",
+      "interaction": [
+        { "code": "read" },
+        { "code": "search-type" },
+        { "code": "write" },
+        { "code": "patch" },
+        { "code": "delete" },
+        { "code": "create" }
+      ],
+      "operation": [
+        {
+          "name": "$sqlquery-run",
+          "definition": "http://sql-on-fhir.org/OperationDefinition/$sqlquery-run"
         },
         {
-          "name": "$run",
-          "definition": "http://sql-on-fhir.org/OperationDefinition/$run"
+          "name": "$sqlquery-export",
+          "definition": "http://sql-on-fhir.org/OperationDefinition/$sqlquery-export"
         }
       ]
     }]
   }]
 }
-```
+```

input/pagecontent/operations.md

@@ -12,7 +12,9 @@ The following list of API endpoints are defined:
 
 - CapabilityStatement
 - Operation $viewdefinition-export of ViewDefinition
-- Operation $run of ViewDefinition
+- Operation $viewdefinition-run of ViewDefinition
+- Operation $sqlquery-run of Library
+- Operation $sqlquery-export of Library
 
 ## Use Cases
 
@@ -122,13 +124,27 @@ The server processes the ViewDefinitions asynchronously and provides progress up
 
 See [Operation $viewdefinition-export of ViewDefinition](OperationDefinition-ViewDefinitionExport.html)
 
-### Operation $run of ViewDefinition
+### Operation $viewdefinition-run of ViewDefinition
 
-The `$run` operation provides real-time, synchronous evaluation of ViewDefinitions to transform FHIR resources into tabular format.
+The `$viewdefinition-run` operation provides real-time, synchronous evaluation of ViewDefinitions to transform FHIR resources into tabular format.
 This operation is designed for interactive development, debugging of ViewDefinitions, and real-time data streaming applications.
-It can be invoked at either the type level (ViewDefinition/$run) or instance level (ViewDefinition/{id}/$run), with the ViewDefinition specified either in the request parameters or inferred from the URL path.
+It can be invoked at either the type level (ViewDefinition/$viewdefinition-run) or instance level (ViewDefinition/{id}/$viewdefinition-run), with the ViewDefinition specified either in the request parameters or inferred from the URL path.
 
 The operation supports multiple output formats including JSON, NDJSON, CSV, Parquet, and table formats, with the format determined by the Accept header or \_format parameter.
 It can process either resources provided directly in the request or resources available on the server, with optional filtering by patient, group, or time parameters. The operation may use chunked transfer encoding for large result sets and includes comprehensive error handling through FHIR OperationOutcome resources for validation and processing errors.
 
-See [Operation $run of ViewDefinition](OperationDefinition-ViewDefinitionRun.html)
+See [Operation $viewdefinition-run of ViewDefinition](OperationDefinition-ViewDefinitionRun.html)
+
+### Operation $sqlquery-run of Library
+
+The `$sqlquery-run` operation provides real-time, synchronous execution of a SQLQuery Library against materialised ViewDefinition tables, returning the query results in the requested format.
+It can be invoked at the system, type, or instance level, with the query supplied inline, by reference, or inferred from the URL path at instance level.
+
+See [Operation $sqlquery-run of Library](OperationDefinition-SQLQueryRun.html) and the shared [Common Operation Behavior](operations-common.html).
+
+### Operation $sqlquery-export of Library
+
+The `$sqlquery-export` operation is the asynchronous counterpart to `$sqlquery-run`, exporting SQLQuery Library results into formats such as CSV, NDJSON, or Parquet using the FHIR Asynchronous Bulk Data Request pattern.
+It accepts one or more queries to export and returns export tasks that can be monitored for progress and completion, suiting it to large-scale query execution with results delivered to file storage.
+
+See [Operation $sqlquery-export of Library](OperationDefinition-SQLQueryExport.html) and the shared [Common Operation Behavior](operations-common.html).