SQL on FHIR
2.1.0-pre - release International flag

SQL on FHIR - Local Development build (v2.1.0-pre) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Resource Profile: SQL Query Library

Official URL: https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery Version: 2.1.0-pre
Draft as of 2026-02-24 Computable Name: SQLQuery

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. 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; execution environments resolve these to physical tables.

Resource Content

ViewDefinition Dependencies

Use relatedArtifact with type = "depends-on" to list required ViewDefinitions. Use label to define the table name in SQL.

"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" }
]

Table Aliases

Each dependency requires a label that defines the table name used in SQL. Labels must 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 MUST 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 MUST 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": "https://sql-on-fhir.org/ig/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.

Conformance

Terminology: contentType SHALL come from All SQL Content Type Codes.

Constraints:

  • Library type SHALL be LibraryTypesCodes#sql-query
  • 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
  • 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 of Profiles, Differentials, Snapshots and how the different presentations work.

This structure is derived from Library

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: sql-must-be-sql-expressions
... type 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Required Pattern: At least the following
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... type S 1..1 code depends-on for ViewDefinition references
.... label SC 1..1 string Table name used in SQL query
Constraints: sql-name
.... resource S 1..1 canonical(Resource) Canonical URL of ViewDefinition
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... name S 1..1 code Name used to access the parameter value
.... use S 1..1 code in (query parameters are always input)
.... type S 1..1 code What type of value
.... Slices for extension Content/Rules for all slices
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType S 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
.... data S 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 All SQL Content Type Codes 📦2.1.0-pre This IG

Constraints

Id Grade Path(s) Description Expression
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... contained 0..* Resource Contained, inline Resources
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
... type Σ 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Binding: LibraryType (extensible): The type of knowledge asset this library contains.
Required Pattern: At least the following
.... id 0..1 string Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... id 0..1 string Unique id for inter-element referencing
..... extension 0..* Extension Additional content defined by implementations
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... version 0..1 string Version of the system - if relevant
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
..... display 0..1 string Representation defined by the system
..... userSelected 0..1 boolean If this coding was chosen directly by the user
.... text 0..1 string Plain text representation of the concept
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... type SΣ 1..1 code depends-on for ViewDefinition references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
.... label SΣC 1..1 string Table name used in SQL query
Constraints: sql-name
.... resource SΣ 1..1 canonical(Resource) Canonical URL of ViewDefinition
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... name SΣ 1..1 code Name used to access the parameter value
.... use SΣ 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
.... type SΣ 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
... content SΣ 1..* Attachment Contents of the library, either embedded or referenced
.... Slices for extension Content/Rules for all slices
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType SΣC 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
Example General: text/plain; charset=UTF-8, image/png
.... data SC 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 📍5.0.0 FHIR Std.
Library.type Base extensible Library Type 📍5.0.0 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍5.0.0 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍5.0.0 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍5.0.0 FHIR Std.
Library.content.contentType Base required All SQL Content Type Codes 📦2.1.0-pre This IG

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())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
... id Σ 0..1 id Logical id of this artifact
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... 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
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
... url ΣC 0..1 uri Canonical identifier for this library, represented as a URI (globally unique)
Constraints: cnl-1
... identifier Σ 0..* Identifier Additional identifier for the library
... version Σ 0..1 string Business version of the library
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 0..1 string Name for this library (computer friendly)
... title Σ 0..1 string Name for this library (human friendly)
... subtitle 0..1 string Subordinate title of the library
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing purposes, not real usage
... type Σ 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Binding: LibraryType (extensible): The type of knowledge asset this library contains.
Required Pattern: At least the following
.... id 0..1 string Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... id 0..1 string Unique id for inter-element referencing
..... extension 0..* Extension Additional content defined by implementations
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... version 0..1 string Version of the system - if relevant
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
..... display 0..1 string Representation defined by the system
..... userSelected 0..1 boolean If this coding was chosen directly by the user
.... text 0..1 string Plain text representation of the concept
... 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.).
.... subjectCodeableConcept CodeableConcept
.... subjectReference Reference(Group)
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description Σ 0..1 markdown Natural language description of the library
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Intended jurisdiction for library (if applicable)
Binding: JurisdictionValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this library is defined
... usage 0..1 markdown Describes the clinical usage of the library
... copyright 0..1 markdown Use and/or publishing restrictions
... copyrightLabel 0..1 string Copyright holder and year(s)
... approvalDate 0..1 date When the library was approved by publisher
... lastReviewDate 0..1 date When the library was last reviewed by the publisher
... effectivePeriod Σ 0..1 Period When the library is expected to be used
... topic 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: DefinitionTopic (example): High-level categorization of the definition, used for searching, sorting, and filtering.
... author 0..* ContactDetail Who authored the content
... editor 0..* ContactDetail Who edited the content
... reviewer 0..* ContactDetail Who reviewed the content
... endorser 0..* ContactDetail Who endorsed the content
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... id 0..1 id Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... type SΣ 1..1 code depends-on for ViewDefinition references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
.... classifier Σ 0..* CodeableConcept Additional classifiers
Binding: CitationArtifactClassifier (example): Additional classifiers for the related artifact.
.... label SΣC 1..1 string Table name used in SQL query
Constraints: sql-name
.... display Σ 0..1 string Brief description of the related artifact
.... citation Σ 0..1 markdown Bibliographic citation for the artifact
.... document Σ 0..1 Attachment What document is being referenced
.... resource SΣ 1..1 canonical(Resource) Canonical URL of ViewDefinition
.... resourceReference Σ 0..1 Reference(Resource) What artifact, if not a conformance resource
.... publicationStatus Σ 0..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): Publication status of an artifact being referred to.
.... publicationDate Σ 0..1 date Date of publication of the artifact being referred to
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... id 0..1 id Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... name SΣ 1..1 code Name used to access the parameter value
.... use SΣ 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
.... min Σ 0..1 integer Minimum cardinality
.... max Σ 0..1 string Maximum cardinality (a number of *)
.... documentation Σ 0..1 string A brief description of the parameter
.... type SΣ 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
.... profile Σ 0..1 canonical(StructureDefinition) What profile the value is expected to be
... dataRequirement 0..* DataRequirement What data is referenced by this library
... content SΣ 1..* Attachment Contents of the library, either embedded or referenced
.... id 0..1 id Unique id for inter-element referencing
.... Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType SΣC 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
Example General: text/plain; charset=UTF-8, image/png
.... language Σ 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
.... data SC 1..1 base64Binary SQL query (base64-encoded)
.... url Σ 0..1 url Uri where the data can be found
Example General: http://www.acme.com/logo-small.png
.... size Σ 0..1 integer64 Number of bytes of content (if url provided)
.... hash Σ 0..1 base64Binary Hash of the data (sha-1, base64ed)
.... title Σ 0..1 string Label to display in place of the data
Example General: Official Corporate Logo
.... creation Σ 0..1 dateTime Date attachment was first created
.... height 0..1 positiveInt Height of the image in pixels (photo/video)
.... width 0..1 positiveInt Width of the image in pixels (photo/video)
.... frames 0..1 positiveInt Number of frames if > 1 (photo)
.... duration 0..1 decimal Length in seconds (audio / video)
.... 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 📍5.0.0 FHIR Std.
Library.versionAlgorithm[x] Base extensible Version Algorithm 📍5.0.0 FHIR Std.
Library.status Base required PublicationStatus 📍5.0.0 FHIR Std.
Library.type Base extensible Library Type 📍5.0.0 FHIR Std.
Library.subject[x] Base extensible Participant Resource Types 📍5.0.0 FHIR Std.
Library.jurisdiction Base extensible Jurisdiction ValueSet 📍5.0.0 FHIR Std.
Library.topic Base example Definition Topic 📍5.0.0 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍5.0.0 FHIR Std.
Library.relatedArtifact.​classifier Base example Citation Artifact Classifier 📍5.0.0 FHIR Std.
Library.relatedArtifact.​publicationStatus Base required PublicationStatus 📍5.0.0 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍5.0.0 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍5.0.0 FHIR Std.
Library.content.contentType Base required All SQL Content Type Codes 📦2.1.0-pre This IG
Library.content.language Base required All Languages 📍5.0.0 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())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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

Extensions

This structure refers to these extensions:

Differential View

This structure is derived from Library

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: sql-must-be-sql-expressions
... type 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Required Pattern: At least the following
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... type S 1..1 code depends-on for ViewDefinition references
.... label SC 1..1 string Table name used in SQL query
Constraints: sql-name
.... resource S 1..1 canonical(Resource) Canonical URL of ViewDefinition
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... name S 1..1 code Name used to access the parameter value
.... use S 1..1 code in (query parameters are always input)
.... type S 1..1 code What type of value
.... Slices for extension Content/Rules for all slices
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType S 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
.... data S 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 All SQL Content Type Codes 📦2.1.0-pre This IG

Constraints

Id Grade Path(s) Description Expression
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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_]*$')

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... contained 0..* Resource Contained, inline Resources
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
... type Σ 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Binding: LibraryType (extensible): The type of knowledge asset this library contains.
Required Pattern: At least the following
.... id 0..1 string Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... id 0..1 string Unique id for inter-element referencing
..... extension 0..* Extension Additional content defined by implementations
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... version 0..1 string Version of the system - if relevant
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
..... display 0..1 string Representation defined by the system
..... userSelected 0..1 boolean If this coding was chosen directly by the user
.... text 0..1 string Plain text representation of the concept
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... type SΣ 1..1 code depends-on for ViewDefinition references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
.... label SΣC 1..1 string Table name used in SQL query
Constraints: sql-name
.... resource SΣ 1..1 canonical(Resource) Canonical URL of ViewDefinition
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... name SΣ 1..1 code Name used to access the parameter value
.... use SΣ 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
.... type SΣ 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
... content SΣ 1..* Attachment Contents of the library, either embedded or referenced
.... Slices for extension Content/Rules for all slices
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType SΣC 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
Example General: text/plain; charset=UTF-8, image/png
.... data SC 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 📍5.0.0 FHIR Std.
Library.type Base extensible Library Type 📍5.0.0 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍5.0.0 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍5.0.0 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍5.0.0 FHIR Std.
Library.content.contentType Base required All SQL Content Type Codes 📦2.1.0-pre This IG

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())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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 View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Library C 0..* Library Represents a library of quality improvement components
Interfaces Implemented: MetadataResource
Constraints: cnl-0, sql-must-be-sql-expressions
... id Σ 0..1 id Logical id of this artifact
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... 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
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
... url ΣC 0..1 uri Canonical identifier for this library, represented as a URI (globally unique)
Constraints: cnl-1
... identifier Σ 0..* Identifier Additional identifier for the library
... version Σ 0..1 string Business version of the library
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 0..1 string Name for this library (computer friendly)
... title Σ 0..1 string Name for this library (human friendly)
... subtitle 0..1 string Subordinate title of the library
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing purposes, not real usage
... type Σ 1..1 CodeableConcept logic-library | model-definition | asset-collection | module-definition
Binding: LibraryType (extensible): The type of knowledge asset this library contains.
Required Pattern: At least the following
.... id 0..1 string Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
.... coding 1..* Coding Code defined by a terminology system
Fixed Value: (Complex)
..... id 0..1 string Unique id for inter-element referencing
..... extension 0..* Extension Additional content defined by implementations
..... system 1..1 uri Identity of the terminology system
Fixed Value: https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes
..... version 0..1 string Version of the system - if relevant
..... code 1..1 code Symbol in syntax defined by the system
Fixed Value: sql-query
..... display 0..1 string Representation defined by the system
..... userSelected 0..1 boolean If this coding was chosen directly by the user
.... text 0..1 string Plain text representation of the concept
... 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.).
.... subjectCodeableConcept CodeableConcept
.... subjectReference Reference(Group)
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description Σ 0..1 markdown Natural language description of the library
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Intended jurisdiction for library (if applicable)
Binding: JurisdictionValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this library is defined
... usage 0..1 markdown Describes the clinical usage of the library
... copyright 0..1 markdown Use and/or publishing restrictions
... copyrightLabel 0..1 string Copyright holder and year(s)
... approvalDate 0..1 date When the library was approved by publisher
... lastReviewDate 0..1 date When the library was last reviewed by the publisher
... effectivePeriod Σ 0..1 Period When the library is expected to be used
... topic 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: DefinitionTopic (example): High-level categorization of the definition, used for searching, sorting, and filtering.
... author 0..* ContactDetail Who authored the content
... editor 0..* ContactDetail Who edited the content
... reviewer 0..* ContactDetail Who reviewed the content
... endorser 0..* ContactDetail Who endorsed the content
... relatedArtifact S 0..* RelatedArtifact Additional documentation, citations, etc
.... id 0..1 id Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... type SΣ 1..1 code depends-on for ViewDefinition references
Binding: RelatedArtifactType (required): The type of relationship to the related artifact.
.... classifier Σ 0..* CodeableConcept Additional classifiers
Binding: CitationArtifactClassifier (example): Additional classifiers for the related artifact.
.... label SΣC 1..1 string Table name used in SQL query
Constraints: sql-name
.... display Σ 0..1 string Brief description of the related artifact
.... citation Σ 0..1 markdown Bibliographic citation for the artifact
.... document Σ 0..1 Attachment What document is being referenced
.... resource SΣ 1..1 canonical(Resource) Canonical URL of ViewDefinition
.... resourceReference Σ 0..1 Reference(Resource) What artifact, if not a conformance resource
.... publicationStatus Σ 0..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): Publication status of an artifact being referred to.
.... publicationDate Σ 0..1 date Date of publication of the artifact being referred to
... parameter S 0..* ParameterDefinition Parameters defined by the library
.... id 0..1 id Unique id for inter-element referencing
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... name SΣ 1..1 code Name used to access the parameter value
.... use SΣ 1..1 code in (query parameters are always input)
Binding: OperationParameterUse (required): Whether the parameter is input or output.
.... min Σ 0..1 integer Minimum cardinality
.... max Σ 0..1 string Maximum cardinality (a number of *)
.... documentation Σ 0..1 string A brief description of the parameter
.... type SΣ 1..1 code What type of value
Binding: FHIRTypes (required): List of FHIR types (resources, data types).
.... profile Σ 0..1 canonical(StructureDefinition) What profile the value is expected to be
... dataRequirement 0..* DataRequirement What data is referenced by this library
... content SΣ 1..* Attachment Contents of the library, either embedded or referenced
.... id 0..1 id Unique id for inter-element referencing
.... Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... extension:sqlText S 0..1 string Plain-text SQL for readability
URL: https://sql-on-fhir.org/ig/StructureDefinition/sql-text
.... contentType SΣC 1..1 code application/sql or application/sql;dialect=...
Binding: All SQL Content Type Codes (required)
Example General: text/plain; charset=UTF-8, image/png
.... language Σ 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
.... data SC 1..1 base64Binary SQL query (base64-encoded)
.... url Σ 0..1 url Uri where the data can be found
Example General: http://www.acme.com/logo-small.png
.... size Σ 0..1 integer64 Number of bytes of content (if url provided)
.... hash Σ 0..1 base64Binary Hash of the data (sha-1, base64ed)
.... title Σ 0..1 string Label to display in place of the data
Example General: Official Corporate Logo
.... creation Σ 0..1 dateTime Date attachment was first created
.... height 0..1 positiveInt Height of the image in pixels (photo/video)
.... width 0..1 positiveInt Width of the image in pixels (photo/video)
.... frames 0..1 positiveInt Number of frames if > 1 (photo)
.... duration 0..1 decimal Length in seconds (audio / video)
.... 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 📍5.0.0 FHIR Std.
Library.versionAlgorithm[x] Base extensible Version Algorithm 📍5.0.0 FHIR Std.
Library.status Base required PublicationStatus 📍5.0.0 FHIR Std.
Library.type Base extensible Library Type 📍5.0.0 FHIR Std.
Library.subject[x] Base extensible Participant Resource Types 📍5.0.0 FHIR Std.
Library.jurisdiction Base extensible Jurisdiction ValueSet 📍5.0.0 FHIR Std.
Library.topic Base example Definition Topic 📍5.0.0 FHIR Std.
Library.relatedArtifact.​type Base required RelatedArtifactType 📍5.0.0 FHIR Std.
Library.relatedArtifact.​classifier Base example Citation Artifact Classifier 📍5.0.0 FHIR Std.
Library.relatedArtifact.​publicationStatus Base required PublicationStatus 📍5.0.0 FHIR Std.
Library.parameter.use Base required Operation Parameter Use 📍5.0.0 FHIR Std.
Library.parameter.type Base required All FHIR Types 📍5.0.0 FHIR Std.
Library.content.contentType Base required All SQL Content Type Codes 📦2.1.0-pre This IG
Library.content.language Base required All Languages 📍5.0.0 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())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
sql-must-be-sql-expressions error Library The content of the Library must be SQL expressions. content.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

Extensions

This structure refers to these extensions:

 

Other representations of profile: CSV, Excel, Schematron

Notes:

Quick Start

A minimal SQLQuery Library:

{
  "resourceType": "Library",
  "meta": {
    "profile": ["https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery"]
  },
  "type": {
    "coding": [{
      "system": "https://sql-on-fhir.org/ig/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": "https://sql-on-fhir.org/ig/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

SQL Annotations

SQL files MAY include annotations to generate SQLQuery Libraries automatically. Library elements are authoritative. Based on Brian Kaney’s sql-fhir-library-builder.

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