This page is part of the FHIR Shorthand (v3.0.0-ballot: Release 3 Ballot 1) based on FHIR R4. The current version which supercedes this version is 2.0.0. For a full list of available versions, see the Directory of published versions

FHIR Shorthand

Official URL: http://hl7.org/fhir/uv/shorthand/ImplementationGuide/hl7.fhir.uv.shorthand				Version: 3.0.0-ballot
Draft as of 2023-07-30				Computable Name: FHIRShorthand

NOTE: Information on this page is informative content.

Background

FHIR Shorthand (FSH) is a domain-specific language for defining FHIR artifacts involved in creation of FHIR Implementation Guides (IG). The goal of FSH is to allow Implementation Guide (IG) creators to more directly express their intent with fewer concerns about underlying FHIR mechanics, and efficiently produce high-quality FHIR IGs.

Conceived in September 2019 with the first version of the specification released in March 2020, FSH has been rapidly adopted by the FHIR community. The FSH Finder tool reports well over 400 IG-development projects using FSH. The #shorthand channel on chat.fhir.org has over 500 subscribers and participation is very active. FSH and related tools have been tested at three HL7 Connectathons. Several significant tools for processing FSH have been developed, including SUSHI, a reference implementation and de facto standard compiler for transforming FSH into FHIR artifacts. The site npm-stat shows that the fsh-sushi npm package has had over 190,000 downloads as of July 2023. GoFSH, a tool for transforming FHIR artifacts to FSH, enables lossless round-tripping from FHIR JSON to FSH and back. FSH and SUSHI have been integrated with the HL7 FHIR Implementation Guide Publishing tool, allowing seamless processing from FSH to a complete IG.

FSH was approved as a Standard for Trial Use (STU 1) in May 2020 and a Mixed Normative - Trial Use Standard (R2) in February 2022 . In the ensuing period, additional activity around FSH has driven improvements, new features, and maturation of FSH and related tools. The majority of language features of FSH are now normative, but certain newer language features are proposed as Trial Use. Trial use features are clearly marked in the language specification with the TU symbol.

Designation as a normative standard does not mean that the FSH language will cease to evolve, only that any future changes must be compatible with the normative portions of the specification.

Motivations for FHIR Shorthand

FSH was created in response to the need in the FHIR community for scalable, fast, user-friendly tools for IG creation and maintenance. IG authors often struggle to implement profiling projects with efficiency, consistency, and quality. Project teams iterate over the formal definitions and examples many times during the IG development process. As such, an agile approach to refactoring and revision is invaluable.

Before exploring the FSH approach, consider the alternative methods for IG development:

1. Hand-editing FHIR conformance artifacts such as StructureDefinition and ValueSet resources gives authors full control over every aspect of the resulting FHIR profiles and definitions, but is unwieldy and prone to errors, and suitable only for FHIR experts.
2. The Excel spreadsheet method has existed since before FHIR 1.0 and has been used to produce sophisticated IGs such as US Core. A downside is that version management is difficult; either the files are saved in binary form (.xslx) or as XML files, with the content mixed with formatting directives. According to HL7 Confluence, the spreadsheet method “is expected to be a near term solution with more sophisticated (and user-friendly) tooling currently under development,” implying eventual deprecation of this approach.
3. Simplifier/Forge and Trifolia-on-FHIR provide graphical, form-based interfaces that help guide users through common profiling tasks. The upside is that the tools provide guidance to authors, while the potential downside is the need to navigate through many screens, and difficulty making cross-cutting changes. Trifolia is fully browser-based, with no software to install locally. Both are commercially-supported products.

While recognizing there is no single “best” approach to IG development, experience across many domains has shown that complex software projects are typically approached with textual languages. As a language designed for the job of profiling and IG creation, FSH is concise, understandable, and aligned to user intentions. Users may find that the FSH language representation is a good way to understand a set of profiles or logical models. Because it is text-based, FSH brings a degree of editing agility not typically found in graphical tools (cutting and pasting, search and replace, spell checking, etc.) FSH is ideal for distributed development under source code control, providing meaningful version-to-version differentials, support for merging and conflict resolution, and nimble refactoring. These features allow FSH to scale in ways that other approaches cannot. Any text editor can be used to create or modify FSH, but advanced text editor plugins may also be used to further aid authoring.

About this IG

The FSH IG includes the following information:

1. This page, providing introductory material (informative content).
2. FHIR Shorthand Overview – Introduction to FSH language and SUSHI (a reference implementation and de facto standard FSH compiler) (informative content).
3. FHIR Shorthand Language Reference – The syntax and usage of the FHIR Shorthand language (formal content).
4. Quick Reference Card – A cheat sheet for FSH syntax and examples (informative content).
5. Change Log – A history of changes to the FHIR Shorthand specification (informative content).

The following material, useful for learning and applying FHIR Shorthand but not part of the language specification, is found on FSHSchool.org:

1. SUSHI User Guide – SUSHI (“SUSHI Unshortens ShortHand Inputs”) is a reference implementation and de facto standard interpreter/compiler for FHIR Shorthand. SUSHI produces Health Level Seven (HL7®) Fast Healthcare Interoperability Resources (FHIR®) profiles, extensions, and other artifacts needed to create FHIR Implementation Guides (IG).
2. GoFSH User Guide – GoFSH is a tool that turns FHIR artifacts into FSH. Using GoFSH, existing FHIR artifacts or complete Implementation Guides can be transformed into FSH, automatically.
3. FSH Visual Studio Code Extension Overview – The FSH Visual Studio Code extension provides syntax highlighting, code snippets, path completion, and other features that improve FSH authoring efficiency.
4. FHIR Shorthand Tutorials – A step-by-step hands-on introduction to producing an Implementation Guide (IG) with FHIR Shorthand and SUSHI.
5. FHIR Shorthand Seminar – A comprehensive overview of FHIR IG authoring basics for people who are interested in being able to independently create FHIR IGs.
6. FSH Online – A coding playground for FSH, an online environment that allows you to write FSH and convert it to FHIR artifacts, convert FHIR artifacts to FSH, access examples, and share FSH code with others.
7. FSH Finder – A list of public GitHub repositories that contain FSH code, refreshed daily.

Note that the Language Reference is the formal specification, and if there is any conflict between that and any other written or programmatic materials, the former is considered the source of truth.

Version Number

The sequence of releases of this specification is expressed in terms of three integers, x.y.z. An increment in z indicates minor, backward-compatible updates. An increment in y indicates new or modified language features, and potentially, non-backward-compatible changes. By HL7 convention, the major version number x typically does not increment until the release of a new balloted version. Implementations SHOULD indicate what version or versions of the FSH specification they implement.

Issue Reporting and Contributions

• FSH language issues and suggestions can be made in the HL7 Jira. When filing FSH language or IG issues, use project=”FHIR” AND Specification = “Shorthand (FHIR) [FHIR-shorthand]”.

• SUSHI bugs, issues, and suggestions can be made here.

• GoFSH bugs, issues, and suggestions can be made here.

• If your FSH project is not listed in FSH Finder, log an issue here or submit a pull request on the list of organizations in settings.yml.

• FSH examples for inclusion in FSH Online can be contributed here.

Authors and Contributors

Role	Name	Organization	Contact
Author	Mark A. Kramer	MITRE Corporation	mkramer@mitre.org
Author	Chris Moesel	MITRE Corporation	cmoesel@mitre.org
Contributor	Julia K. Afeltra	MITRE Corporation	jafeltra@mitre.org
Contributor	Julian A. Carter	MITRE Corporation	jacarter@mitre.org
Contributor	Samantha Citron	MITRE Corporation	scitron@mitre.org
Contributor	Nick Freiter	MITRE Corporation	nfreiter@mitre.org
Contributor	Joe Paquette	athenahealth	jpaquette@athenahealth.com
Contributor	Mint N. Thompson	MITRE Corporation	mathompson@mitre.org
FHIR Infrastructure Co-chair	Rick Geimer	Lantana Consulting Group	rick.geimer@lantanagroup.com
FHIR Infrastructure Co-chair	Josh Mandel	SMART Health IT	jmandel@gmail.com
FHIR Infrastructure Co-chair	Lloyd McKenzie	HL7 Canada/Gevity	lloyd@lmckenzie.com
FHIR Infrastructure Co-chair	Yunwei Wang	MITRE Corporation	yunweiw@mitre.org

The authors gratefully acknowledge the many contributions from numerous users and facilitators who helped shape, mature, debug, and advance the FSH specification. The authors want to thank all those who participate on the shorthand channel via chat.fhir.org. While every discussion helps build the FSH knowledge base and strengthen the community of FSH, we especially appreciate those who provide answers and participate in design discussions. We therefore recognize:

Reece Adamson, Kurt Allen, Carl Anderson, Keith Boone, Giorgio Cangioli, Gino Canessa, Etienne Cantineau, Juan Manuel Caputo, Sam Citron, Sheila Connelly, Carmela Couderc, Stuart Cox, Nathan Davis, Bart Decuypere, Paul Denning, Noemi Deppenwiese, Mark Discenza, Jean Duteau, Oliver Egger, Brett Esler, Richard Esmond, Richard Ettema, Michael Faughn, Benjamin Flessner, Scott Fradkin, Sarah Gaunt, Nick George, Hugh Glover, Andy Gregorowicz, Grahame Grieve, Alex Goel, Nick Goupinets, John Grimes, Eric Haas, Torben Hagensen, Bill Harty, Rob Hausam, David Hay, Bret Heale, Simone Heckmann, Martin Höcker, Mark Iantorno, Brian Kaney, Daniel Karlsson, Richard Kavanagh, John Keyes, Max Körlinge, Ewout Kramer, Saul Kravitz, Halina Labikova, Patrick Langford, Michael Lawley, Carl Leitner, Hank Lenzi, Rutt Lindström, Geoff Low, Stephen MacVicar, Dylan Mahalingam, Rute Martins Baptista, Josh Mandel, Max Masnick, Lloyd McKenzie, Stuart McGrigor, Bob Milius, John Moehrke, Ryan Moehrke, Jabeen Mohammed, Sean Muir, Dipanjan Mukherjee, Muthu Muthuraj, Christian Nau, Craig Newman, Catherine Hosage Norman, Diana Ovelgoenne, Joe Paquette, Tom Parker-Shemilt, Janaka Peiris, Vadim Peretokin, Vassil Peytchev, Brian Postlethwaite, Caroline Potteiger, Mareike Przysucha, David Pyke, Andre Quina, Joshua Reynolds, Rob Reynolds, Bryn Rhodes, Andy Richardson, Peter Robinson, Kirstine Rosenbeck Gøeg, Thomas Tveit Rosenlund, Shovan Roy, Julian Sass, Michael Sauer, Mark Scrimshire, Larry Shields, John Silva, Elliot Silver, Igor Sirkovich, Bill Sorensen, Corey Spears, Richard Stanley, Lee Surprenant, Jose Costa Teixeira, May Terry, Arvid Thunholm, Eric Torstenson, Richard Townley-O’Neill, Conor Vahland, Pétur Valdimarsson, Bas van den Heuvel, Matthijs van der Wielen Bence Vass, Barbro Vessman, Jens Villadsen, Ward Weistra, Patrick Werner, Rien Wertheim, David Winters, Alexander Zautke, and Michaela Ziegler.

The authors apologize if they have omitted any contributor from this list.

Continue to Overview ->