SQL on FHIR
3.0.0-ballot - STU 3 Ballot International flag

SQL on FHIR, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 3.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/sql-on-fhir/ and changes regularly. See the Directory of published versions

Resource Profile: SQL Query Library

Official URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery Version: 3.0.0-ballot
Standards status: Trial-use Maturity Level: 2 Computable Name: SQLQuery
Other Identifiers: OID:2.16.840.1.113883.4.642.40.77.42.1

The SQLQuery profile represents a SQL query that runs against ViewDefinition tables. It bundles the SQL, dependencies, and parameters for sharing and versioning.

Scope and Usage

Use SQLQuery for shareable SQL over ViewDefinition outputs and over reusable SQLView queries. Each Library holds one query. For dialect-specific variants, use multiple content attachments while keeping parameters and aliases consistent.

Boundaries and Relationships

SQLQuery does not define table schemas, data extraction, execution behavior, or APIs; those belong to ViewDefinition and its operations. SQLQuery references ViewDefinitions, SQLViews, ValueSets and ConceptMaps; execution environments resolve these to physical or virtual tables. An SQLView is itself a reusable named query that other queries reference as a virtual table source, letting queries build on one another like SQL views (see Query Composition in the Notes tab). A ValueSet is exposed to the SQL as a relation of its member codes, so that a query tests code membership with an ordinary join, and a ConceptMap as a relation of its mappings, so that a query translates codes the same way (see Terminology in SQL).

Resource Content

Dependencies

Use relatedArtifact with type = "depends-on" to list required ViewDefinitions, SQLViews, ValueSets and ConceptMaps. Use label to define the table name in SQL. Each resource may be the canonical URL of a ViewDefinition, of an SQLView, of a ValueSet or of a ConceptMap; the allowed targets are recorded as a targetProfile on relatedArtifact.resource.

"relatedArtifact": [
  { "type": "depends-on", "resource": "https://example.org/ViewDefinition/patient_view", "label": "patient" },
  { "type": "depends-on", "resource": "http://hl7.org/fhir/uv/sql-on-fhir/Library/ActivePatientsView", "label": "active_patients" },
  { "type": "depends-on", "resource": "http://example.org/ValueSet/cardiovascular-disease|2026", "label": "cvd_codes" },
  { "type": "depends-on", "resource": "http://example.org/ConceptMap/sct-to-icd10|2026", "label": "sct_to_icd10" }
]

A ValueSet dependency is read as a relation with the columns system, version, code, display and inactive, and a ConceptMap dependency as a relation with the columns source_system, source_version, source_code, source_display, target_system, target_version, target_code, target_display and relationship, as specified in Terminology in SQL.

Table Aliases

Each dependency requires a label that defines the table name used in SQL. Labels SHALL be unique within the Library and valid SQL identifiers (start with letter or underscore, contain only letters/digits/underscores, avoid reserved words).

Parameters

Declare parameters in Library.parameter with name, type, and use = "in".

"parameter": [
  { "name": "patient_id", "type": "string", "use": "in" },
  { "name": "from_date", "type": "date", "use": "in" }
]

Reference parameters in SQL with colon-prefix placeholders (:name):

WHERE patient.id = :patient_id AND bp.effective_date >= :from_date

Implementations SHALL ensure parameter values are safely bound to queries and not subject to SQL injection. Use parameterized queries or equivalent safe binding mechanisms where available. Simple string interpolation SHALL NOT be used to implement parameter binding.

SQL Attachments

Store the query in content with contentType = "application/sql". The data element (base64-encoded SQL) is required. The sql-text extension MAY carry a plain-text copy for human readability.

"content": [{
  "contentType": "application/sql",
  "extension": [{
    "url": "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text",
    "valueString": "SELECT patient.id, bp.systolic FROM ..."
  }],
  "data": "U0VMRUNUIHBhdGllbnQu..."
}]

The sql-text extension provides human-readable SQL; data provides the machine-processable (base64-encoded) form.

Dialect Variants

For dialect-specific SQL, include separate attachments with a dialect parameter in contentType (e.g., application/sql;dialect=postgresql). Keep aliases and parameter names consistent across variants.

A contentType of application/sql (with no dialect parameter) represents a default variant. It carries no dialect commitment and is intended to be broadly portable, so authors SHOULD restrict it to standard ANSI SQL constructs that work across the engines they expect to target. Implementations MAY treat the default variant as roughly equivalent to ANSI SQL when no dialect-specific variant matches.

When a Library contains multiple content attachments, implementations choose which attachment to execute as follows:

  1. Prefer an attachment whose contentType declares a dialect parameter that matches the executing engine (for example, an engine running PostgreSQL selects application/sql;dialect=postgresql).
  2. If no matching dialect-specific attachment is present, fall back to the default attachment with contentType = "application/sql".
  3. If neither a matching dialect nor a default attachment is available, implementations SHOULD return an error rather than guess at a translation between dialects.

Authors SHOULD include a default application/sql attachment whenever possible so that engines without a dedicated variant still have a portable fallback. All variants within a single Library SHALL be functionally equivalent: they SHALL expose the same parameters, reference the same table aliases, and produce the same logical result set.

Conformance

Terminology: contentType SHOULD come from All SQL Content Type Codes. The binding is extensible: when one of these codes covers the dialect, that code SHALL be used; otherwise, an alternative code MAY be supplied (subject to the constraint that every contentType starts with application/sql).

Constraints:

  • Library type SHALL be LibraryTypesCodes#sql-query
  • Every content.contentType SHALL start with application/sql
  • content.data SHALL be present; the sql-text extension MAY carry a plain-text copy
  • Dependencies SHALL use relatedArtifact with type = "depends-on" and label, each resource referencing a ViewDefinition, an SQLView, a ValueSet or a ConceptMap
  • Parameters SHALL use Library.parameter with use = "in"

For examples and tooling guidance, see the Notes tab below.

Usages:

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description Differentials, Snapshots, and other representations.

NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
Library.implicitRules This element is a modifier element. This element is included in summaries. 0..1 uri A set of rules under which this content was created
Library.contained 0..* Resource Contained, inline Resources
Library.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
Library.status This element is a modifier element. This element is included in summaries. 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
Library.type This element is included in summaries. 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Binding: LibraryType (extensible): The type of knowledge artifact this library contains.
Required Pattern: At least the following
Library.type.id 0..1 string Unique id for inter-element referencing
Library.type.extension 0..* Extension Additional content defined by implementations
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.id 0..1 string Unique id for inter-element referencing
Library.type.coding.extension 0..* Extension Additional content defined by implementations
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.version 0..1 string Version of the system - if relevant
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.type.coding.display 0..1 string Representation defined by the system
Library.type.coding.userSelected 0..1 boolean If this coding was chosen directly by the user
Library.type.text 0..1 string Plain text representation of the concept
Library.relatedArtifact This element must be supported. C 0..* RelatedArtifact Additional documentation, citations, etc
Constraints: lib-2
Library.relatedArtifact.type This element must be supported. This element is included in summaries. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. This element is included in summaries. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.resource This element must be supported. This element is included in summaries. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.name This element must be supported. This element is included in summaries. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. This element is included in summaries. 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
Library.parameter.type This element must be supported. This element is included in summaries. 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
Library.content This element must be supported. This element is included in summaries. 1..* Attachment Contents of the library, either embedded or referenced
Library.content.Slices for extension Content/Rules for all slices
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. This element is included in summaries. C 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible

Example General: text/plain; charset=UTF-8, image/png
Library.content.data This element must be supported. C 1..1 base64Binary SQL query (base64-encoded)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Library.status Base required PublicationStatus 📍6.0.0-snapshot1 FHIR Std.
Library.type Base extensible LibraryType 📦1.0.1 THO v7.4
Library.relatedArtifact.​type Base required RelatedArtifactType 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍6.0.0-snapshot1 FHIR Std.
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning Library Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
lib-2 warning Library.relatedArtifact Dependencies and components of a Library should reference a resource type in ('depends-on' | 'composed-of' | 'part-of') implies ((resource.exists() xor resourceReference.exists()))
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')

This structure is derived from Library

NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: sql-must-be-sql-expressions
Library.type 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Required Pattern: At least the following
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.relatedArtifact This element must be supported. 0..* RelatedArtifact Additional documentation, citations, etc
Library.relatedArtifact.type This element must be supported. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.resource This element must be supported. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.name This element must be supported. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. 1..1 code in (query parameters are always input)
Library.parameter.type This element must be supported. 1..1 code What type of value
Library.content.Slices for extension Content/Rules for all slices
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible
Library.content.data This element must be supported. 1..1 base64Binary SQL query (base64-encoded)

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')
NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
Library.id This element is included in summaries. 0..1 id Logical id of this artifact
Library.meta This element is included in summaries. 0..1 Meta Metadata about the resource
Library.implicitRules This element is a modifier element. This element is included in summaries. 0..1 uri A set of rules under which this content was created
Library.language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
Library.text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
Library.contained 0..* Resource Contained, inline Resources
Library.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
Library.url This element is included in summaries. C 0..1 uri Canonical identifier for this library, represented as a URI (globally unique)
Constraints: cnl-1
Library.identifier This element is included in summaries. 0..* Identifier Additional identifier for the library
Library.version This element is included in summaries. 0..1 string Business version of the library
Library.versionAlgorithm[x] This element is included in summaries. 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
Library.versionAlgorithm[x].versionAlgorithmString string
Library.versionAlgorithm[x].versionAlgorithmCoding Coding
Library.name This element is included in summaries. C 0..1 string Name for this library (computer friendly)
Library.title This element is included in summaries. 0..1 string Name for this library (human friendly)
Library.subtitle 0..1 string Subordinate title of the library
Library.status This element is a modifier element. This element is included in summaries. 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
Library.experimental This element is included in summaries. 0..1 boolean For testing only - never for real usage
Library.type This element is included in summaries. 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Binding: LibraryType (extensible): The type of knowledge artifact this library contains.
Required Pattern: At least the following
Library.type.id 0..1 string Unique id for inter-element referencing
Library.type.extension 0..* Extension Additional content defined by implementations
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.id 0..1 string Unique id for inter-element referencing
Library.type.coding.extension 0..* Extension Additional content defined by implementations
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.version 0..1 string Version of the system - if relevant
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.type.coding.display 0..1 string Representation defined by the system
Library.type.coding.userSelected 0..1 boolean If this coding was chosen directly by the user
Library.type.text 0..1 string Plain text representation of the concept
Library.subject[x] 0..1 Type of individual the library content is focused on
Binding: ParticipantResourceTypes (extensible): The possible types of subjects for a library (E.g. Patient, Practitioner, Organization, Location, etc.).
Library.subject[x].subjectCodeableConcept CodeableConcept
Library.subject[x].subjectReference Reference(Group)
Library.date This element is included in summaries. 0..1 dateTime Date last changed
Library.publisher This element is included in summaries. 0..1 string Name of the publisher/steward (organization or individual)
Library.contact This element is included in summaries. 0..* ContactDetail Contact details for the publisher
Library.description This element is included in summaries. 0..1 markdown Natural language description of the library
Library.useContext This element is included in summaries. 0..* UsageContext The context that the content is intended to support
Library.jurisdiction This element is included in summaries. 0..* CodeableConcept Jurisdiction of the authority that maintains the library (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
Library.purpose 0..1 markdown Why this library is defined
Library.usage 0..1 markdown Describes the clinical usage of the library
Library.copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
Library.copyrightLabel 0..1 string Copyright holder and year(s)
Library.approvalDate 0..1 date When the library was approved by publisher
Library.lastReviewDate 0..1 date When the library was last reviewed by the publisher
Library.effectivePeriod This element is included in summaries. 0..1 Period When the library is expected to be used
Library.topic 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: DefinitionTopic (example): High-level categorization of the definition, used for searching, sorting, and filtering.
Library.author 0..* ContactDetail Who authored the content
Library.editor 0..* ContactDetail Who edited the content
Library.reviewer 0..* ContactDetail Who reviewed the content
Library.endorser 0..* ContactDetail Who endorsed the content
Library.relatedArtifact This element must be supported. C 0..* RelatedArtifact Additional documentation, citations, etc
Constraints: lib-2
Library.relatedArtifact.id 0..1 string Unique id for inter-element referencing
Library.relatedArtifact.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.relatedArtifact.type This element must be supported. This element is included in summaries. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. This element is included in summaries. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.display This element is included in summaries. 0..1 string Brief description of the related artifact
Library.relatedArtifact.citation This element is included in summaries. 0..1 markdown Bibliographic citation for the artifact
Library.relatedArtifact.url This element is included in summaries. 0..1 url A url for the artifact that can be followed to access the actual content
Library.relatedArtifact.document This element is included in summaries. 0..1 Attachment What document is being referenced
Library.relatedArtifact.resource This element must be supported. This element is included in summaries. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.relatedArtifact.resourceReference This element is included in summaries. 0..1 Reference(Resource) What artifact, if not a conformance resource
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.id 0..1 string Unique id for inter-element referencing
Library.parameter.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.parameter.name This element must be supported. This element is included in summaries. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. This element is included in summaries. 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
Library.parameter.min This element is included in summaries. 0..1 integer Minimum cardinality
Library.parameter.max This element is included in summaries. 0..1 string Maximum cardinality (a number of *)
Library.parameter.documentation This element is included in summaries. 0..1 string A brief description of the parameter
Library.parameter.type This element must be supported. This element is included in summaries. 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
Library.parameter.profile This element is included in summaries. 0..1 canonical(StructureDefinition) What profile the value is expected to be
Library.dataRequirement 0..* DataRequirement What data is referenced by this library
Library.content This element must be supported. This element is included in summaries. 1..* Attachment Contents of the library, either embedded or referenced
Library.content.id 0..1 string Unique id for inter-element referencing
Library.content.Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. This element is included in summaries. C 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible

Example General: text/plain; charset=UTF-8, image/png
Library.content.language This element is included in summaries. 0..1 code Human language of the content (BCP-47)
Binding: AllLanguages (required): IETF language tag for a human language.
Additional BindingsPurpose
CommonLanguages Starter

Example General: en-AU
Library.content.data This element must be supported. C 1..1 base64Binary SQL query (base64-encoded)
Library.content.url This element is included in summaries. 0..1 url Uri where the data can be found
Example General: http://www.acme.com/logo-small.png
Library.content.size This element is included in summaries. 0..1 integer64 Number of bytes of content (if url provided)
Library.content.hash This element is included in summaries. 0..1 base64Binary Hash of the data (sha-1, base64ed)
Library.content.title This element is included in summaries. 0..1 string Label to display in place of the data
Example General: Official Corporate Logo
Library.content.creation This element is included in summaries. 0..1 dateTime Date attachment was first created
Library.content.height 0..1 positiveInt Height of the image in pixels (photo/video)
Library.content.width 0..1 positiveInt Width of the image in pixels (photo/video)
Library.content.frames 0..1 positiveInt Number of frames if > 1 (photo)
Library.content.duration 0..1 decimal Length in seconds (audio / video)
Library.content.pages 0..1 positiveInt Number of printed pages

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Library.language Base required All Languages 📍6.0.0-snapshot1 FHIR Std.
Library.versionAlgorithm[x] Base extensible Version Algorithm 📍6.0.0-snapshot1 FHIR Std.
Library.status Base required PublicationStatus 📍6.0.0-snapshot1 FHIR Std.
Library.type Base extensible LibraryType 📦1.0.1 THO v7.4
Library.subject[x] Base extensible Participant Resource Types 📍6.0.0-snapshot1 FHIR Std.
Library.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.4
Library.topic Base example Definition Topic 📍6.0.0-snapshot1 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍6.0.0-snapshot1 FHIR Std.
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.
Library.content.language Base required All Languages 📍6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning Library Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning Library.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
lib-2 warning Library.relatedArtifact Dependencies and components of a Library should reference a resource type in ('depends-on' | 'composed-of' | 'part-of') implies ((resource.exists() xor resourceReference.exists()))
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')

This structure is derived from Library

Summary

Mandatory: 3 elements(3 nested mandatory elements)
Must-Support: 12 elements

Structures

This structure refers to these other structures:

Extensions

This structure refers to these extensions:

Maturity: 2

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
Library.implicitRules This element is a modifier element. This element is included in summaries. 0..1 uri A set of rules under which this content was created
Library.contained 0..* Resource Contained, inline Resources
Library.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
Library.status This element is a modifier element. This element is included in summaries. 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
Library.type This element is included in summaries. 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Binding: LibraryType (extensible): The type of knowledge artifact this library contains.
Required Pattern: At least the following
Library.type.id 0..1 string Unique id for inter-element referencing
Library.type.extension 0..* Extension Additional content defined by implementations
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.id 0..1 string Unique id for inter-element referencing
Library.type.coding.extension 0..* Extension Additional content defined by implementations
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.version 0..1 string Version of the system - if relevant
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.type.coding.display 0..1 string Representation defined by the system
Library.type.coding.userSelected 0..1 boolean If this coding was chosen directly by the user
Library.type.text 0..1 string Plain text representation of the concept
Library.relatedArtifact This element must be supported. C 0..* RelatedArtifact Additional documentation, citations, etc
Constraints: lib-2
Library.relatedArtifact.type This element must be supported. This element is included in summaries. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. This element is included in summaries. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.resource This element must be supported. This element is included in summaries. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.name This element must be supported. This element is included in summaries. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. This element is included in summaries. 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
Library.parameter.type This element must be supported. This element is included in summaries. 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
Library.content This element must be supported. This element is included in summaries. 1..* Attachment Contents of the library, either embedded or referenced
Library.content.Slices for extension Content/Rules for all slices
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. This element is included in summaries. C 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible

Example General: text/plain; charset=UTF-8, image/png
Library.content.data This element must be supported. C 1..1 base64Binary SQL query (base64-encoded)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Library.status Base required PublicationStatus 📍6.0.0-snapshot1 FHIR Std.
Library.type Base extensible LibraryType 📦1.0.1 THO v7.4
Library.relatedArtifact.​type Base required RelatedArtifactType 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍6.0.0-snapshot1 FHIR Std.
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning Library Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
lib-2 warning Library.relatedArtifact Dependencies and components of a Library should reference a resource type in ('depends-on' | 'composed-of' | 'part-of') implies ((resource.exists() xor resourceReference.exists()))
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')

Differential View

This structure is derived from Library

NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: sql-must-be-sql-expressions
Library.type 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Required Pattern: At least the following
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.relatedArtifact This element must be supported. 0..* RelatedArtifact Additional documentation, citations, etc
Library.relatedArtifact.type This element must be supported. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.resource This element must be supported. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.name This element must be supported. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. 1..1 code in (query parameters are always input)
Library.parameter.type This element must be supported. 1..1 code What type of value
Library.content This element must be supported. 1..* Attachment Contents of the library, either embedded or referenced
Library.content.Slices for extension Content/Rules for all slices
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible
Library.content.data This element must be supported. 1..1 base64Binary SQL query (base64-encoded)

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')

Snapshot ViewView

NameFlagsCard.TypeDescription & Constraints    Filter: doco
Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
Library.id This element is included in summaries. 0..1 id Logical id of this artifact
Library.meta This element is included in summaries. 0..1 Meta Metadata about the resource
Library.implicitRules This element is a modifier element. This element is included in summaries. 0..1 uri A set of rules under which this content was created
Library.language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
Library.text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
Library.contained 0..* Resource Contained, inline Resources
Library.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
Library.url This element is included in summaries. C 0..1 uri Canonical identifier for this library, represented as a URI (globally unique)
Constraints: cnl-1
Library.identifier This element is included in summaries. 0..* Identifier Additional identifier for the library
Library.version This element is included in summaries. 0..1 string Business version of the library
Library.versionAlgorithm[x] This element is included in summaries. 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
Library.versionAlgorithm[x].versionAlgorithmString string
Library.versionAlgorithm[x].versionAlgorithmCoding Coding
Library.name This element is included in summaries. C 0..1 string Name for this library (computer friendly)
Library.title This element is included in summaries. 0..1 string Name for this library (human friendly)
Library.subtitle 0..1 string Subordinate title of the library
Library.status This element is a modifier element. This element is included in summaries. 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
Library.experimental This element is included in summaries. 0..1 boolean For testing only - never for real usage
Library.type This element is included in summaries. 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition | etc.
Binding: LibraryType (extensible): The type of knowledge artifact this library contains.
Required Pattern: At least the following
Library.type.id 0..1 string Unique id for inter-element referencing
Library.type.extension 0..* Extension Additional content defined by implementations
Library.type.coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
Library.type.coding.id 0..1 string Unique id for inter-element referencing
Library.type.coding.extension 0..* Extension Additional content defined by implementations
Library.type.coding.system 1..1 uri Identity of the terminology system
Fixed Value: http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes
Library.type.coding.version 0..1 string Version of the system - if relevant
Library.type.coding.code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
Library.type.coding.display 0..1 string Representation defined by the system
Library.type.coding.userSelected 0..1 boolean If this coding was chosen directly by the user
Library.type.text 0..1 string Plain text representation of the concept
Library.subject[x] 0..1 Type of individual the library content is focused on
Binding: ParticipantResourceTypes (extensible): The possible types of subjects for a library (E.g. Patient, Practitioner, Organization, Location, etc.).
Library.subject[x].subjectCodeableConcept CodeableConcept
Library.subject[x].subjectReference Reference(Group)
Library.date This element is included in summaries. 0..1 dateTime Date last changed
Library.publisher This element is included in summaries. 0..1 string Name of the publisher/steward (organization or individual)
Library.contact This element is included in summaries. 0..* ContactDetail Contact details for the publisher
Library.description This element is included in summaries. 0..1 markdown Natural language description of the library
Library.useContext This element is included in summaries. 0..* UsageContext The context that the content is intended to support
Library.jurisdiction This element is included in summaries. 0..* CodeableConcept Jurisdiction of the authority that maintains the library (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
Library.purpose 0..1 markdown Why this library is defined
Library.usage 0..1 markdown Describes the clinical usage of the library
Library.copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
Library.copyrightLabel 0..1 string Copyright holder and year(s)
Library.approvalDate 0..1 date When the library was approved by publisher
Library.lastReviewDate 0..1 date When the library was last reviewed by the publisher
Library.effectivePeriod This element is included in summaries. 0..1 Period When the library is expected to be used
Library.topic 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: DefinitionTopic (example): High-level categorization of the definition, used for searching, sorting, and filtering.
Library.author 0..* ContactDetail Who authored the content
Library.editor 0..* ContactDetail Who edited the content
Library.reviewer 0..* ContactDetail Who reviewed the content
Library.endorser 0..* ContactDetail Who endorsed the content
Library.relatedArtifact This element must be supported. C 0..* RelatedArtifact Additional documentation, citations, etc
Constraints: lib-2
Library.relatedArtifact.id 0..1 string Unique id for inter-element referencing
Library.relatedArtifact.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.relatedArtifact.type This element must be supported. This element is included in summaries. 1..1 code depends-on for ViewDefinition, SQLView, ValueSet or ConceptMap references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
Required Pattern: depends-on
Library.relatedArtifact.label This element must be supported. This element is included in summaries. C 1..1 string Table name used in SQL query
Constraints: sql-name
Library.relatedArtifact.display This element is included in summaries. 0..1 string Brief description of the related artifact
Library.relatedArtifact.citation This element is included in summaries. 0..1 markdown Bibliographic citation for the artifact
Library.relatedArtifact.url This element is included in summaries. 0..1 url A url for the artifact that can be followed to access the actual content
Library.relatedArtifact.document This element is included in summaries. 0..1 Attachment What document is being referenced
Library.relatedArtifact.resource This element must be supported. This element is included in summaries. 1..1 canonical(View Definition | SQL View Library | ValueSet | ConceptMap) Canonical URL of a ViewDefinition, SQLView, ValueSet or ConceptMap
Library.relatedArtifact.resourceReference This element is included in summaries. 0..1 Reference(Resource) What artifact, if not a conformance resource
Library.parameter This element must be supported. 0..* ParameterDefinition Parameters defined by the library
Library.parameter.id 0..1 string Unique id for inter-element referencing
Library.parameter.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.parameter.name This element must be supported. This element is included in summaries. 1..1 code Name used to access the parameter value
Library.parameter.use This element must be supported. This element is included in summaries. 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
Library.parameter.min This element is included in summaries. 0..1 integer Minimum cardinality
Library.parameter.max This element is included in summaries. 0..1 string Maximum cardinality (a number of *)
Library.parameter.documentation This element is included in summaries. 0..1 string A brief description of the parameter
Library.parameter.type This element must be supported. This element is included in summaries. 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
Library.parameter.profile This element is included in summaries. 0..1 canonical(StructureDefinition) What profile the value is expected to be
Library.dataRequirement 0..* DataRequirement What data is referenced by this library
Library.content This element must be supported. This element is included in summaries. 1..* Attachment Contents of the library, either embedded or referenced
Library.content.id 0..1 string Unique id for inter-element referencing
Library.content.Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
Library.content.Slices for extension.extension:sqlText This element must be supported. 0..1 string Plain-text SQL for readability
URL: http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text
Library.content.contentType This element must be supported. This element is included in summaries. C 1..1 code application/sql or application/sql;dialect=...
Binding: MimeTypes (required)
Additional BindingsPurpose
All SQL Content Type Codes Extensible

Example General: text/plain; charset=UTF-8, image/png
Library.content.language This element is included in summaries. 0..1 code Human language of the content (BCP-47)
Binding: AllLanguages (required): IETF language tag for a human language.
Additional BindingsPurpose
CommonLanguages Starter

Example General: en-AU
Library.content.data This element must be supported. C 1..1 base64Binary SQL query (base64-encoded)
Library.content.url This element is included in summaries. 0..1 url Uri where the data can be found
Example General: http://www.acme.com/logo-small.png
Library.content.size This element is included in summaries. 0..1 integer64 Number of bytes of content (if url provided)
Library.content.hash This element is included in summaries. 0..1 base64Binary Hash of the data (sha-1, base64ed)
Library.content.title This element is included in summaries. 0..1 string Label to display in place of the data
Example General: Official Corporate Logo
Library.content.creation This element is included in summaries. 0..1 dateTime Date attachment was first created
Library.content.height 0..1 positiveInt Height of the image in pixels (photo/video)
Library.content.width 0..1 positiveInt Width of the image in pixels (photo/video)
Library.content.frames 0..1 positiveInt Number of frames if > 1 (photo)
Library.content.duration 0..1 decimal Length in seconds (audio / video)
Library.content.pages 0..1 positiveInt Number of printed pages

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Library.language Base required All Languages 📍6.0.0-snapshot1 FHIR Std.
Library.versionAlgorithm[x] Base extensible Version Algorithm 📍6.0.0-snapshot1 FHIR Std.
Library.status Base required PublicationStatus 📍6.0.0-snapshot1 FHIR Std.
Library.type Base extensible LibraryType 📦1.0.1 THO v7.4
Library.subject[x] Base extensible Participant Resource Types 📍6.0.0-snapshot1 FHIR Std.
Library.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.4
Library.topic Base example Definition Topic 📍6.0.0-snapshot1 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍6.0.0-snapshot1 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍6.0.0-snapshot1 FHIR Std.
Library.content.contentType Base required Mime Types 📦6.0.0-snapshot1 FHIR Std.
Library.content.language Base required All Languages 📍6.0.0-snapshot1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning Library Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning Library.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
lib-2 warning Library.relatedArtifact Dependencies and components of a Library should reference a resource type in ('depends-on' | 'composed-of' | 'part-of') implies ((resource.exists() xor resourceReference.exists()))
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.all(contentType.startsWith('application/sql'))
sql-name error Library.relatedArtifact.label Name is limited to letters, numbers, or underscores and cannot start with an underscore -- i.e. with a regular expression of: ^[A-Za-z][A-Za-z0-9_]*$ This makes it usable as table names in a wide variety of databases. empty() or matches('^[A-Za-z][A-Za-z0-9_]*$')

This structure is derived from Library

Summary

Mandatory: 3 elements(3 nested mandatory elements)
Must-Support: 12 elements

Structures

This structure refers to these other structures:

Extensions

This structure refers to these extensions:

Maturity: 2

 

Other representations of profile: CSV, Excel, Schematron

Notes:

Quick Start

A minimal SQLQuery Library:

{
  "resourceType": "Library",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery"
    ]
  },
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/uv/sql-on-fhir/CodeSystem/LibraryTypesCodes",
        "code": "sql-query"
      }
    ]
  },
  "name": "PatientBloodPressure",
  "status": "active",
  "relatedArtifact": [
    {
      "type": "depends-on",
      "resource": "https://example.org/ViewDefinition/patient_view",
      "label": "patient"
    },
    {
      "type": "depends-on",
      "resource": "https://example.org/ViewDefinition/bp_view",
      "label": "bp"
    }
  ],
  "parameter": [
    { "name": "patient_id", "type": "string", "use": "in" },
    { "name": "from_date", "type": "date", "use": "in" }
  ],
  "content": [
    {
      "contentType": "application/sql",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/sql-text",
          "valueString": "SELECT patient.id, bp.systolic FROM ..."
        }
      ],
      "data": "U0VMRUNUIHBhdGllbnQu..."
    }
  ]
}

Decoded SQL (matches both the sql-text extension and the base64 data):

SELECT patient.id, bp.systolic
FROM patient
JOIN bp ON patient.id = bp.patient_id
WHERE patient.id = :patient_id
  AND bp.effective_date >= :from_date

Query Composition

An SQLQuery may reference a reusable SQLView as well as ViewDefinitions, letting queries build on one another much like SQL views. A ViewDefinition projects FHIR resources into tables; an SQLView wraps a query over those tables and exposes it under a canonical URL; an SQLQuery composes both as its table sources.

These references form a directed graph of ViewDefinitions, SQLViews, and SQLQueries, in which each referenced result acts as a virtual table for the referencing query. A ValueSet or ConceptMap dependency joins the same graph as a leaf, exposed as a relation of its member codes or of its mappings (see Terminology in SQL). Authors SHOULD keep this graph acyclic. Whether circular dependencies are detected, any limit on dependency depth, and whether intermediate results are materialized or inlined (for example as CTEs or database views) are implementation decisions and are not mandated by this specification.

The Active Patient Addresses example shows an SQLQuery that references the Active Patients SQLView.

How these dependencies are resolved when a query is invoked, including how a client may supply one inline that the server cannot itself resolve, is specified in Supporting artifacts.

Parameter Types

Each Library.parameter declares a type that callers SHALL honour when supplying values. When parameters are passed at invocation time via a Parameters resource (for example to $sql-run or $sql-export), each entry is bound by name to the matching Library.parameter, and the appropriate value[x] element SHALL be used for the declared type:

Library.parameter.type Parameters.parameter value
string valueString
integer valueInteger
date valueDate
dateTime valueDateTime
boolean valueBoolean
decimal valueDecimal

SQL Annotations

SQL files MAY include annotations to generate SQLQuery Libraries automatically. Library elements are authoritative.

Syntax: @key: value in SQL comments.

/*
@name: PatientBloodPressure
@title: Patient Blood Pressure Report
@version: 1.0.0
@status: active
*/

-- @param: patient_id string Patient identifier
-- @param: from_date date Start date
-- @relatedDependency: https://example.org/ViewDefinition/patient_view as patient
-- @relatedDependency: https://example.org/ViewDefinition/bp_view as bp

SELECT patient.id, bp.systolic
FROM patient JOIN bp ON patient.id = bp.patient_id
WHERE patient.id = :patient_id AND bp.effective_date >= :from_date

Annotation reference:

Annotation FHIR Mapping Format
@name Library.name @name: identifier
@title Library.title @title: Human Title
@description Library.description @description: text
@version Library.version @version: semver
@status Library.status @status: draft\|active\|retired
@author Library.author.name @author: Name (repeatable)
@publisher Library.publisher @publisher: Org
@param Library.parameter @param: name type [description] (repeatable)
@relatedDependency relatedArtifact @relatedDependency: URL [as label] (repeatable)

Tooling

Builders SHALL:

  1. Parse annotations from block (/* */) and line (--) comments
  2. Populate the sql-text extension with the SQL text (plain text)
  3. Generate content.data with base64-encoded SQL
  4. Set content.contentType to application/sql
  5. Set type to LibraryTypesCodes#sql-query
  6. Set parameter.use to in for all parameters
  7. Set relatedArtifact.type to depends-on for all dependencies

Builders SHOULD:

  1. Infer name from filename if @name not provided
  2. Default status to draft if not specified
  3. Validate parameter types against allowed FHIR types
  4. Validate labels as SQL identifiers (^[a-zA-Z_][a-zA-Z0-9_]*$)
  5. Warn on unrecognized annotations