DRAFT SMART Guidelines L3 SOP, published by TBD. This is not an authorized publication; it is the continuous build for version 0.2.1). This version is based on the current content of https://github.com/DigitalSQR/smart-ig-starter-kit and changes regularly. See the Directory of published versions

Authoring Artifacts

L3 Authoring corresponds to authoring computable artifacts and possibly narrative content. This is similar or complementary to L2 authoring.

L2 artifacts

L3 authors should find and use the L2 artifacts.
L2 artifacts can be represented as narrative or other representations such as FHIR resources. For reference, these are the locations for such artifacts and narrative:

Content Type	L2 Representation	L2 Location
Health Interventions	Narrative	input/pagecontent
Generic Personas	Narrative	input/pagecontent/personas.md
User Scenarios	Narrative	input/pagecontent
Processes	Narrative	input/pagecontent
Data Elements	Narrative	input/pagecontent
	Spreadsheet	TBD
Decision Tables	Narrative	input/pagecontent
	Spreadsheet	TBD
Scheduling Logic	Narrative	input/pagecontent
	Spreadsheet	N/A
Indicators	Narrative	input/pagecontent
Functional Requirements	Narrative	input/pagecontent
Non-functional Requirements	Narrative	input/pagecontent

L3 Artifacts

The table below shows the content types that are to be created as part of the L3 authoring process.

Content Type	L3 Representation	L3 Location	Procedure
Health Interventions	n/a	n/a	n/a
Generic Personas	ActorDefinition	input/actors	Actors
User Scenarios	ExampleScenario	input/scenarios	Scenarios
	TestPlan	input/testing	Testing
	TestScript??	input/testing	Testing
	Example instances	input/testing input/examples	Examples
Processes	FHIR PlanDefinition	input/plandefinitions	Plan Definitions
	FHIR ActivityDefinition	input/processes input/activitydefinitions	Activity definitions
Elements	Logical Data Model	input/models	Logical Models
	FHIR Questionnaire	input/questionnaires	Questionnaires
	FHIR StructureMaps	input/maps	Structure Maps
	FHIR ValueSet	input/valuesets	ValueSets
	FHIR CodeSystem	input/codesystems	CodeSystems
	FHIR Profile	input/profiles	Profiles
	ConceptMap	input/maps	Concept Maps
	CQL Concepts	input/cql	CQL
	CQL Data Elements	input/cql
Decision Tables	FHIR PlanDefinition	input/plandefinitions	Decision Tables
	FHIR Library	input/libraries	Concept Maps
	CQL	input/cql	CQL
Scheduling Logic	FHIR PlanDefinition	input/plandefinitions	Scheduling Logic
Indicators and Measures	FHIR Measure	input/measures	Indicators
	CQL IndicatorLogic	input/cql	CQL
Functional Requirements	FHIR Requirements	input/requirements	Requirements
Non-functional Requirements	FHIR Requirements	input/requirements	Requirements

File locations

Narrative

For narrative, all files are in input/pagecontent and can be written in xhtml or markdown. See the guidance on authoring narrative.

Artifacts

The canonical folder structure for all artifacts is:

Native FHIR (JSON / XML)

For json or xml content, the file name SHALL be in the form

• ResourceType-resourceid.xml/json (preferred)
• ResourceType/resourceid.xml/json
• resourceid.xml/json

FSH Content

For fsh content, the file name SHALL be in the form

• ResourceType/resourceid.fsh

The input folders for the resources are:

• input/scenarios
• input/actors
• input/measures
• input/requirements
• input/processes
• input/plandefinitions
• input/activitydefinition
• input/testing
• input/examples
• input/codesystems
• input/valuesets
• input/models
• input/questionnaires
• input/profiles
• input/maps
• input/cql
• input/libraries

TO DO: Decision Tables and Scheduling Logic? Should these represent the 16 types of objects?

For FSH, the folders are the same but in the fsh folder, e.g. input/fsh/scenarios, input/fsh/actors etc.

Naming convention

Resource IDs

• ValueSets should be prefixed or suffixed by VS (not enforced)
• Codesystems do not need to to be prefixed or suffixed. The tooling shall handle the resources per type and ID, so there’s no conflict
• Resource Ids should start with capital letter and may contain hyphens - NOT underscore:
  • Resourceid is valid
  • Resource-id is also valid, although not preferred

File Names

• Resource file names must match the resource id. For profiles, this means the profile id.
• Tools are case sensitive - file names shall not have overlapping names differing only in case
• Sushi / FSH Aliases should be stored in fsh/Aliases.fsh

Versioning

see also versioning

Governance

TO DO: Adding artifacts, what goes into common-clinical, etc.