updates

DigitalSQR · Sep 18, 2023 · 9c21c22 · 9c21c22
1 parent c05d8f0
commit 9c21c22
Show file tree

Hide file tree

Showing 16 changed files with 179 additions and 59 deletions.
diff --git a/input/images-source/model_requirements.plantuml b/input/images-source/model_requirements.plantuml
@@ -0,0 +1,52 @@
+@startuml
+'skinparam linetype ortho
+skinparam linetype polyline
+hide circle
+hide stereotype
+
+'!pragma layout smetana
+
+skinparam class<<MD>> {
+ BorderColor DarkSlateGray
+ BackgroundColor WhiteSmoke
+ HeaderBackgroundColor #909090
+}
+
+skinparam class<<TM>> {
+ BorderColor #505090
+ BackgroundColor APPLICATION
+ HeaderBackgroundColor #8bd
+}
+
+class "**Requirement**" as R<<TM>> {
+    |_ identifier[SG] 1..*   
+    |_ status 1..1
+    |_ name 1..1
+    |_ title 1..1
+    |_ description 1..1
+    |_ activityId 1..1  
+    |_ category 0..*
+    --
+}
+
+class "**Functional**\n**Requirement**" as FR<<TM>> {
+    |_ process 1..*
+    |_ persona 1..*
+    |_ description 1..1  
+      |_ text 1..1  
+      |_ functionality 1..1  
+      |_ goal 1..1  
+    --
+}
+
+class "**Non-Functional**\n**Requirement**" as NFR<<TM>> {
+    |_ category 1..*
+    |_ description 1..1  
+      |_ text 1..1  
+    --
+}
+
+FR -u-|> R
+NFR -u-|> R
+
+@enduml
diff --git a/input/pagecontent/authoring_artifacts.md b/input/pagecontent/authoring_artifacts.md
@@ -268,7 +268,7 @@ The input folders for the resources are:
 * `input/cql`
 * `input/libraries`
 
-<p class = "todo"> TO DO: Decision Tables and Scheduling Logic? Should these represent the 16 types of objects?</p>
+<p class="todo"> TO DO: Decision Tables and Scheduling Logic? Should these represent the 16 types of objects?</p>
 
 For FSH, the folders are the same but in the `fsh` folder, e.g. `input/fsh/scenarios`, `input/fsh/actors` etc.
 

diff --git a/input/pagecontent/l3_codesystems.md b/input/pagecontent/l3_codesystems.md
@@ -44,7 +44,7 @@ This is the overview of the activities and related artifacts used:
 |  Sushi | |  |
 |  OCL | |  |
 |  tx.fhir.org | |  |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 ### **Informative examples**

diff --git a/input/pagecontent/l3_decisiontables.md b/input/pagecontent/l3_decisiontables.md
@@ -48,7 +48,7 @@ Decision tree auto generation
 | Tool | Usage | Doc |
 | --- | ---| --- |
 |  |  | |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 ### **Informative examples**

diff --git a/input/pagecontent/l3_examples.md b/input/pagecontent/l3_examples.md
@@ -1,32 +1,40 @@
+Examples are essential for L3 authors to validate the specification before it is implementable.
+Each SMART Implementation Guide shall contain sufficient data to validate itself, which includes examples that contain the data that is intended to assert and assess the functioning of the specification in the available tooling.
+
 ### **Inputs:** 
 
-* sometexthere
+* Conformance / Definitional artifacts: 
+* Example Scenarios
 
 ### **Outputs:**
 
-* sometexthere
+* Example instances of resources - Patient, Observation, ... that can be used on the available tools to validate the specification.
 
 ### **Activities:**
 
-* sometexthere
+* For each of the definitional artifacts, the author shall create an example instance, matching the story and data of its predecessors - for example an Immunization or Observation that contain the data that is in the logical model example, which matches the story line selected.
 
 ### **Output Criteria / Definition of Done:**
 
-* sometexthere
+* Examples should be in the main package, or may be in a dedicated package when the number of examples is significant.
+* Each of the definitional artifacts shall have at least one example
+* Examples should be conformant to their specification - i.e. no QA errors
+* Terminology used in the examples, even with example bindings, shall be defined as L3 valuesets and codesystems.
 
 
 ### **Change tracking**
+* All the validating examples should follow the same rules as for normative materials - i.e. track changes for each relevant change
+* Other examples are normally not normative material
 
 ### **Tooling:**
 
 | Tool | Usage | Doc |
-| --- | ---| --- |
-|  |  | |
-{:.table-bordered}  
-
-
-### **Informative examples**
+| --- | ---| ---| 
+| Sushi | Examples can be authored in FSH syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
+| CQF tooling | CQF tooling can generate example instances |  |
+{:.table-bordered.full-width}  
 
 ### **Known issues and dependencies:**
 
-
+* TO DO: Data generation?
+* TO DO: Packaging of example data?
diff --git a/input/pagecontent/l3_indicators.md b/input/pagecontent/l3_indicators.md
@@ -1,27 +1,42 @@
-### **Inputs:** 
+Indicators are a machine-readable expressions that define the indicator and its input variables, population, and stratifiers. Indicators are expressed using FHIR Measure resource.
 
-* sometexthere
+### **Inputs:** 
+* L2 indicator definition
+* Data dictionary
 
 ### **Outputs:**
-
-* sometexthere
+* Measure
+* Example MeasureReport corresponding to the test / example data included
 
 ### **Activities:**
+Measures are defined using CQL. The activities to define such Measures are:
+* Create the Measure resource instance and populate metadata (author, title, description, etc.)
+* Create the group(s), population(s) and stratifier(s)
+  * Add description, and the CQL expression that will be available from a CQL library
 
 * sometexthere
 
+
+
 ### **Output Criteria / Definition of Done:**
+* Indicators shall conform to the [SGMeasure](https://worldhealthorganization.github.io/smart-base/StructureDefinition-SGMeasure.html) profile.
 
-* sometexthere
+* All the input variables shall be in the measure's `terms`.
+* All terms shall part of the Data Dictionary
+
+* At least one example MeasureReport should be provided
+  * The example MeasureReport should indicate in which conditions
+* There should be a package with all that is needed to evaluate the Measure and the `$evaluate-measure` operation, with example data included or available.
 
 ### **Change tracking**
 
+
 ### **Tooling:**
 
 | Tool | Usage | Doc |
 | --- | ---| --- |
-|  |  | |
-{:.table-bordered}  
+| CQF Ruler | A FHIR server to upload the artifacts and test the `$evaluate-measure` | [Testing Measures](l3_measures_testing.html) |
+{:.table-bordered.full-width}  
 
 
 ### **Informative examples**

diff --git a/input/pagecontent/l3_logicalmodels.md b/input/pagecontent/l3_logicalmodels.md
@@ -121,13 +121,24 @@ For bindings, check whether the value set already exists in an upstream package.
 -   If not, create a new value set.
     -   New value sets are registered and follow the valueset governance process that is adjacent to authoring of L3 content.
 
+
+#### Binding elements to value sets
+When adding valuesets, the binding strength should be considered: 
+* If the valueset is expected to be used or adapted in downstream adaptations, the binding should be more permissive (i.e. either example or preferred).
+See [valuesets](l3_valuesets.html) for procedures on obtaining or creating valuesets.
+
+
+
 #### Mapping to other semantic references
 Semantic mapping is done with ConceptMaps, establishing the relationship between the DAK elements and reference terminologies, central dictionary, or other DAKS.
 
 
 
 ### **Criteria / Definition of Done:**
 
+* One logical model per json file / One profile per fsh file, as per naming convention
+  * The constraints or invariants applicable to a logical model may be contained in the same FSH file.
+  * elements that are repeatable across different models (e.g. Patient Demographics) shall be in a separate FSH file.
 * All data elements in the DAK shall be in one logical model
 * All data elements defined in DAK as calculated elements shall be present in a logical model
 * All elements in the DAK have one and only one WHO SMART Code. 
@@ -145,7 +156,7 @@ Semantic mapping is done with ConceptMaps, establishing the relationship between
 | Tool | Usage | Doc |
 | --- | ---| ---| 
 | Sushi | Create LMs with fsh syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 

diff --git a/input/pagecontent/l3_personas.md b/input/pagecontent/l3_personas.md
@@ -66,10 +66,11 @@ Personas will be associated with actions(processes). The tracking of that associ
 
 
 ### **Criteria / Definition of Done**
-* Personas SHALL use the SGPersona ActorDefinition profile
-* Persona source follow the guidelines for file content and names
+* All Personas SHALL use the SGPersona ActorDefinition profile
+* Each Persona source follow the guidelines for file content and names
 * All the personas SHOULD be from the Personas glossary; any exceptions will have to be resolved before final publication
 
+
 ### **Change tracking**
 
 
@@ -78,7 +79,7 @@ Personas will be associated with actions(processes). The tracking of that associ
 | Tool | Usage | Doc |
 | --- | ---| ---| 
 | Sushi | New persona instances can be created in FSH syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 

diff --git a/input/pagecontent/l3_processes.md b/input/pagecontent/l3_processes.md
@@ -55,7 +55,7 @@ TO DO: Do we want to link processes to models?
 | Tool | Usage | Doc |
 | --- | ---| ---| 
 |  | |  |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 ### **Informative examples**
 

diff --git a/input/pagecontent/l3_profiles.md b/input/pagecontent/l3_profiles.md
@@ -9,6 +9,7 @@ Therefore some profiles for FHIR artifacts share commonalities.
 
 ### **Outputs:**
 * Profiles in `input/profiles` or `input/fsh/profiles`
+* Example instances in `input/examples` or `input/fsh/examples`
 
 
 ### **Activities:**
@@ -50,17 +51,23 @@ The recommended priority for the search for existing profiles
 
 ### **Output Criteria / Definition of Done:**
 
+* One profile per json file / One profile per fsh file, as per naming convention
+  * The constraints or invariants applicable to a profile may be contained in the same FSH file.
 * All profiles shall be valid profiles
 * All data elements that need to be exchanged or used in a decision, workflow, or indicator are covered by one or more profiles.
+* Every profile shall have one example instance
 
-
+ 
 ### **Change tracking**
+* Profiles are essential traceability artifacts, and all changes to a profile shall be tracked in change history
+* Breaking changes to a prior published release should follow a dedicated review process
 
 ### **Tooling**
 
 | Tool | Usage | Doc |
 | --- | ---| ---| 
-|  | |  |
+| Sushi | Profiles can be authored in FSH syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
+{:.table-bordered.full-width}  
 
 
 ### **Informative examples**

diff --git a/input/pagecontent/l3_requirements.md b/input/pagecontent/l3_requirements.md
@@ -3,28 +3,49 @@ Requirements - functional or non-functional - are captured as L3 artifacts for t
 * Adaptability to jurisdiction-specific guidelines
 * Traceability - for example to Testing
 
-The L3 author 
+The L3 author is expected to capture the requirements in a [Requirements](https://worldhealthorganization.github.io/smart-base/StructureDefinition-SGRequirements.html) resource.
+
+The requirements capture the following data:
+<figure>
+  {% include model_logicalmodel.svg %}
+</figure>
+
 
 ### **Inputs:** 
 
-* sometexthere
+* Personas, Processes and Requirements from L2
+* Personas and Processes from L3
 
 ### **Outputs:**
 
-* sometexthere
+* Requirements resources for all functional and non-functional requirements
+<li class="todo">TO DO: Minimal testing expectations for all requirements?</p>
 
 ### **Activities:**
-
-* sometexthere
+The L3 author takes the L2 requirements and expresses those as FHIR Requirements.
 
 ### **Output Criteria / Definition of Done:**
+* Each requirement shall be associated with a Persona.
+* Each Functional requirement shall have a link to a business [Process] that it is associated with
+  * Each Functional requirement should have an Activity ID
+
+* Each requirement shall have a unique id, a title, and a Scrum-like description:
+  * *"As a "* ... [Persona]
+  * *"I want"* ... [Functionality/activity]
+  * *"So that"* ... [Functional goal]
 
-* sometexthere
 
 ### **Change tracking**
+* Requirements are essential traceable artifacts. Every time a requirement changes, the change history shall be appended.
 
 ### **Tooling:**
 
+| Tool | Usage | Doc |
+| --- | ---| ---| 
+| Sushi | Requirements can be authored in FSH syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
+{:.table-bordered.full-width}  
+
+
 ### **Informative examples**
 
 ### **Known issues and dependencies:**

diff --git a/input/pagecontent/l3_scenarios.md b/input/pagecontent/l3_scenarios.md
@@ -34,23 +34,23 @@ TO DO: This deserves some data generation feature.
 
 
 ### **Output Criteria / Definition of Done:**
-* No QA issues
 * Each User Scenario in the L2 should be covered by one or more ExampleScenarios
   * At least the "normal" flow shall be covered by an example scenario
-* ExampleScenarios should be validated by the publisher 
+* ExampleScenarios should reference the example instances from the other resources (see [profiles](l3_profiles.html), [decision tables](l3_decisiontables.html), [scheduling logic](l3_schedulinglogic.html), [forms](l3_forms.html), [indicators](l3_indicators.html))
+* ExampleScenarios should be validated by the publisher (i.e. no QA issues)
 * ExampleScenarios should be reviewed by the L2 author
 
 
 ### **Change tracking**
-
+ExampleScenarios are not normative material. Change tracking shall follow the general guidance.
 
 
 ### **Tooling**
 
 | Tool | Usage | Doc |
 | --- | ---| --- |
 | Sushi | New ExampleScenarios can be created in FSH syntax | [HL7 Spec](https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html)<br/>[Sushi Documentation](https://fshschool.org) |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 

diff --git a/input/pagecontent/l3_schedulinglogic.md b/input/pagecontent/l3_schedulinglogic.md
@@ -32,7 +32,7 @@ Other Example :  create reminders to come to vaccine tomorrow
 | Tool | Usage | Doc |
 | --- | ---| --- |
 |  |  | |
-{:.table-bordered}  
+{:.table-bordered.full-width}  
 
 
 ### **Informative examples**