Align $sqlquery-run server with SQLQueryRun OperationDefinition

Update the stored OperationDefinition and reference handler to match the
spec defined in input/fsh/operations.fsh:

- Make _format required (1..1); return 400 when absent instead of
  defaulting to JSON.
- Constrain queryResource to the SQLQuery Library profile via the
  operationdefinition-allowed-type extension.
- Declare the source parameter (0..1 string) and reject it with 422
  not-supported, since this reference implementation has no external
  data source concept.
- Rename the output parameter from result (0..* Binary) to return
  (1..1) and declare Binary and Parameters as allowed types, matching
  the two body shapes the handler already produces.

Add tests covering the new validation rules and the updated shape of
the published OperationDefinition.

Author: johngrimes

sof-js/metadata/OperationDefinition/$sqlquery-run.json

@@ -7,63 +7,87 @@
   "code": "sqlquery-run",
   "status": "active",
   "kind": "operation",
-  "description": "Execute a SQL query defined within a Library resource against materialised ViewDefinitions.",
+  "description": "Execute a SQLQuery Library against ViewDefinition tables.",
   "system": true,
   "type": true,
   "instance": true,
   "resource": ["Library"],
   "parameter": [
     {
-      "name": "queryResource",
+      "name": "_format",
+      "use": "in",
+      "min": 1,
+      "max": "1",
+      "type": "code",
+      "documentation": "Output format for the result (json, ndjson, csv, parquet, fhir). Use fhir to return results as a FHIR Parameters resource.",
+      "binding": {
+        "strength": "extensible",
+        "valueSet": "http://sql-on-fhir.org/ValueSet/output-format"
+      }
+    },
+    {
+      "name": "header",
       "use": "in",
       "min": 0,
       "max": "1",
-      "type": "Resource",
-      "documentation": "The Library resource containing the SQL query and relatedArtifact dependencies inline."
+      "type": "boolean",
+      "documentation": "Include CSV headers (default true). Applies only when csv output is requested."
     },
     {
       "name": "queryReference",
       "use": "in",
       "min": 0,
       "max": "1",
       "type": "Reference",
-      "documentation": "A reference to a stored Library resource that contains the SQL query."
+      "documentation": "Reference to a SQLQuery Library stored on the server."
     },
     {
-      "name": "parameters",
+      "name": "queryResource",
       "use": "in",
       "min": 0,
       "max": "1",
-      "type": "Parameters",
-      "documentation": "Named parameter bindings to pass to the SQL query as a FHIR Parameters resource."
+      "type": "Resource",
+      "extension": [
+        {
+          "url": "http://hl7.org/fhir/StructureDefinition/operationdefinition-allowed-type",
+          "valueUri": "https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery"
+        }
+      ],
+      "documentation": "Inline SQLQuery Library resource to execute."
     },
     {
-      "name": "_format",
+      "name": "parameters",
       "use": "in",
       "min": 0,
       "max": "1",
-      "type": "code",
-      "documentation": "Output format - json, ndjson, csv, or fhir.",
-      "binding": {
-        "strength": "extensible",
-        "valueSet": "http://sql-on-fhir.org/ValueSet/output-format"
-      }
+      "type": "Parameters",
+      "documentation": "Input parameters for the query. Parameters are bound by name to parameters declared in the SQLQuery Library (Library.parameter.name). Parameter types are mapped using the appropriate value[x] type matching the declared parameter type."
     },
     {
-      "name": "header",
+      "name": "source",
       "use": "in",
       "min": 0,
       "max": "1",
-      "type": "boolean",
-      "documentation": "Whether to include the header row in CSV output. Defaults to true."
+      "type": "string",
+      "documentation": "External data source containing the ViewDefinition tables."
     },
     {
-      "name": "result",
+      "name": "return",
       "use": "out",
-      "min": 0,
-      "max": "*",
-      "type": "Binary",
-      "documentation": "The query result in the requested format."
+      "min": 1,
+      "max": "1",
+      "type": "Resource",
+      "extension": [
+        {
+          "url": "http://hl7.org/fhir/StructureDefinition/operationdefinition-allowed-type",
+          "valueUri": "Binary"
+        },
+        {
+          "url": "http://hl7.org/fhir/StructureDefinition/operationdefinition-allowed-type",
+          "valueUri": "Parameters"
+        }
+      ],
+      "documentation": "Query results. Returns Binary for flat formats (csv, json, ndjson, parquet) or Parameters for _format=fhir."
     }
   ]
 }

sof-js/src/server/sqlquery-run.js

@@ -620,7 +620,14 @@ async function handleSqlQueryRun(req, res, options = {}) {
   const createdTables = []
   try {
     const params = req.body
-    const format = getParameterValue(params, '_format', 'Code') || 'json'
+    const format = getParameterValue(params, '_format', 'Code')
+    if (!format) {
+      throw badRequestError('_format is required')
+    }
+    const source = getParameterValue(params, 'source', 'String')
+    if (source) {
+      throw notSupportedError('The source parameter is not supported by this server')
+    }
     const headerParam = getParameterValue(params, 'header', 'Boolean')
     const includeHeader = headerParam !== false && headerParam !== 'false'
 
@@ -751,6 +758,10 @@ function buildParametersFromBody(body) {
     parameter.push({ name: 'header', valueBoolean: false })
   }
 
+  if (body.source) {
+    parameter.push({ name: 'source', valueString: body.source })
+  }
+
   return { resourceType: 'Parameters', parameter }
 }
 

sof-js/tests/server/sqlquery-run.test.js

@@ -451,6 +451,86 @@ describe('$sqlquery-run operation', () => {
     expect(body.resourceType).toBe('OperationOutcome')
   })
 
+  test('missing _format returns 400', async () => {
+    // The spec declares _format as 1..1, so a request without it must be
+    // rejected rather than silently defaulting to JSON.
+    const response = await fetch('http://localhost:3004/Library/$sqlquery-run', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/fhir+json' },
+      body: JSON.stringify({
+        resourceType: 'Parameters',
+        parameter: [{ name: 'queryReference', valueReference: { reference: 'Library/patient-bp-query' } }],
+      }),
+    })
+
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.resourceType).toBe('OperationOutcome')
+    expect(body.issue[0].code).toBe('invalid')
+  })
+
+  test('source parameter returns 422 not-supported', async () => {
+    // This reference implementation has no external data source concept, so
+    // supplying `source` should be rejected explicitly rather than ignored.
+    const response = await fetch('http://localhost:3004/Library/$sqlquery-run', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/fhir+json' },
+      body: JSON.stringify({
+        resourceType: 'Parameters',
+        parameter: [
+          { name: '_format', valueCode: 'json' },
+          { name: 'source', valueString: 'http://example.com/data' },
+          { name: 'queryReference', valueReference: { reference: 'Library/patient-bp-query' } },
+        ],
+      }),
+    })
+
+    expect(response.status).toBe(422)
+    const body = await response.json()
+    expect(body.resourceType).toBe('OperationOutcome')
+    expect(body.issue[0].code).toBe('not-supported')
+  })
+
+  test('OperationDefinition exposes spec-aligned parameters', async () => {
+    // The stored OperationDefinition must reflect the FSH source: _format is
+    // required, queryResource carries an allowed-type extension for the
+    // SQLQuery profile, source is declared, and the output is `return` with
+    // Binary or Parameters allowed types.
+    const response = await fetch('http://localhost:3004/OperationDefinition/$sqlquery-run')
+    expect(response.status).toBe(200)
+
+    const body = await response.json()
+    const byName = Object.fromEntries(body.parameter.map((p) => [p.name, p]))
+
+    expect(byName._format).toBeDefined()
+    expect(byName._format.min).toBe(1)
+    expect(byName._format.max).toBe('1')
+
+    expect(byName.queryResource).toBeDefined()
+    const allowedTypeUrl = 'http://hl7.org/fhir/StructureDefinition/operationdefinition-allowed-type'
+    const queryResourceAllowed = (byName.queryResource.extension || [])
+      .filter((e) => e.url === allowedTypeUrl)
+      .map((e) => e.valueUri)
+    expect(queryResourceAllowed).toContain('https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery')
+
+    expect(byName.source).toBeDefined()
+    expect(byName.source.type).toBe('string')
+    expect(byName.source.min).toBe(0)
+    expect(byName.source.max).toBe('1')
+
+    expect(byName.return).toBeDefined()
+    expect(byName.return.use).toBe('out')
+    expect(byName.return.min).toBe(1)
+    expect(byName.return.max).toBe('1')
+    const returnAllowed = (byName.return.extension || [])
+      .filter((e) => e.url === allowedTypeUrl)
+      .map((e) => e.valueUri)
+    expect(returnAllowed).toContain('Binary')
+    expect(returnAllowed).toContain('Parameters')
+
+    expect(byName.result).toBeUndefined()
+  })
+
   test('invalid SQL returns 422', async () => {
     const response = await fetch('http://localhost:3004/$sqlquery-run', {
       method: 'POST',