fhir / ig-guidance Goto Github PK

Discussed on Security and Privacy Considerations, but likely applicable to other sections (e.g. Terminology).

• How to get assistance on that topic
  • Zulip channel?
  • Co-chair distribution list?
  • etc

Links to topic specific written guidance

• https://confluence.hl7.org/display/SEC/Cookbook+for+Security+Considerations
• https://confluence.hl7.org/display/SEC/HL7+Privacy+and+Security+Considerations

The current approach with numbers for each color leads to a messy diagram, and makes adding new variables in an organized manner difficult since they would be added at the end of the list, not with the other variables for the visual element.

Rather than the unordered list of color variables currently presented, consider tables:

We probably need 3 tables:

• content (sample above)
  • columns: text, background, border, link and hover
  • rows: IG title, breadcrumb, publication box, body, table of contents, stu note (and stu headline), dragon, footer nave footer container
• side stripe colors
• menu
  • columns: text, background
  • rows: menu, hover, active, dropdown, dropdown hover

Also separator text color (and any other "1 offs")

Number the rows in the tables. Replace the diagram with one that shows only the areas. That is, replace current numbers 1 and 22 with the number for the new "IG title" area; replace current number 17 and 18 with the new number for the TOC area.

The page source, or at least the included diagram (perhaps diagrams) should show all defined styles, which should be listed in the tables.

Since the variables will be listed in the table, reduce the existing "CSS color definitions" section to only an example of overriding a couple of colors.

I was not able to create a pull request, so here is my recommendation to be added to the best practice narrative

Security and Privacy Considerations

• Section is focused on speaking to the Security and Privacy experts
  • The purpose of the section is to explain what attacks have been considered and what countermeasures can be applied to defend against them
  • Privacy Principles -- related to a subject of data; transparency, purpose limitation, data minimization, accuracy, storage limitations, and security -- There are regional specializations.
  • Security Principles -- security is risk management against risks to Confidentiality, Integrity, and Availability
• Keep points succinct to the special considerations of your IG
  • Reference FHIR core security and privacy for background http://build.fhir.org/secpriv-module.html
  • Reference FHIR core security and privacy checklist http://build.fhir.org/security.html
  • Leverage the security and privacy categorization defined in FHIR core where appropriate
  • Leverage the security and privacy implementation guides such as SMART-on-FHIR
• Include specific conformance requirements of your IG that are related to Security or Privacy in this section, and what attacks that requirement is addressing
• Include residual risks that are not addressed as they would need to be addressed in system design, system deployment, or policy

Someone recently reached out to me and noted that this IG says very little about developing with FSH, even though FSH is now a very popular approach to development of template-based IGs. I am wondering if it might make sense to note that this approach supports FSH (along w/ a link or two to the spec and/or FSH School) as well as to call out [ig-root]/sushi-config.yaml and [ig-root]/input/fsh in the section that documents the contents of an IG project. What do you think?

Apparently plantUml supports themes (https://plantuml.com/theme). Add an example showing use of themes, and potentially how to point to a local defined theme.

We want to give implementers an idea of the range of possibilities.

I recommend we always recommend the include for plantuml are inside div

https://chat.fhir.org/#narrow/stream/179166-implementers/topic/PlantUML.20to.20SVG.20requires.20adjustment

In section 7.0.2, there is a link to the HL7 wiki. This should be replaced by a link to an appropriate page in confluence, after ensuring that all content on the Wiki page is covered in Confluence.

To create the package.json, you might find it easiest to copy the one from the HL7 official template. See here more about the contents of package.json.

if you write a constraint on an element that follows this pattern:

(name | name | name).count = 1

(or <= 1)
where all the names in the union are children of the element on which this invariant sits, then the IG publisher will understand that the named elements are a mutually exclusive group. That means that:

• They will be rendered as a mutually exclusive group in the table presentation form
• if you make one required in a profile, the others will automatically be set to max = 0 (that must be true, so it saves you from having to be explicit about it)
• the rendering as a group will collapse out if one of the elements is required

I added this to reduce the comprehension impedence for CCDA guide readers

I often have difficulty figuring out what an IG is for. Explicit description of the functionality, either with use cases or references to DAMs or other requirements assets, will help people not involved in the IG creation understand what it's for and how it fits in the landscape.

as per https://plantuml.com/en/graphviz-dot
and/or document workaround