299 sdpi ri for r14

[ToddCooper]

📑 Description

TF-1A Requirements Interoperability incremental update for SDPi release 1.4. Primary focus will be updates to the TF-1A section, both adding more detail to the Requirements Interoperability model + cleaning up content that is now dated (e.g., SysML 2.0 and MBSE ... both of which are valid but two years down the road, clearly not in the immediate future!).

☑ Mandatory Tasks

The following aspects have been respected by the pull request assignee and at least one reviewer:

• Changelog update (necessity checked and entry added or not added respectively)
  • [ ] Pull Request Assignee
  • [ ] Reviewer

[ToddCooper]

@d-gregorczyk & @JavierEspina & @mfaughn :
For this release 1.4 incremental update to the requirements interoperability section of TF-1A, my thoughts are to:

1. Remove the too aspirational appendix content (esp. MBSE and SysML ... these may be a simple note but not sections)
2. Add detail to the metadata for each of the requirement types, with the current blocks providing a baseline
3. Add a requirements labeling / numbering section that will then help developers & users understand how each block should be crafted and the metadata assigned.
4. Craft an initial approach for linking requirements - @d-gregorczyk ... ideas? In AsciiDoc it is as simple as including <> anchor links, since we have those for every requirement; for JSON ... ? there are a few approaches like JSON-LD, JSON Reference, XLink, HAL ... (all from this blog entry)

We'll discuss tomorrow on our SDPi Friday call.

[mfaughn]

1. Craft an initial approach for linking requirements - @d-gregorczykhttps://github.com/d-gregorczyk ... ideas? In AsciiDoc it is as simple as including <> anchor links, since we have those for every requirement… I think the short answer is, “Yes”…as long as you keep maintaining everything in a single .adoc file. If you have any aspirations of ever breaking this up into multiple pages (i.e., linking requirements acorss multiple AsciiDoc files) then make sure you understand the difference b/w how you do an internal cross reference and a document to document cross reference, especially what is documented herehttps://docs.asciidoctor.org/asciidoc/latest/macros/xref/. I don’t think the <> syntax works for interdocument cross references. If you go ahead and break things into several .adoc files and then use the xref macro to link them then you can choose to create everything as a single page using include statements or create multi-page output and it should still work

---

Michael Faughn, Computer Scientist Systems Interoperability Group Software and Systems Division Information Technology Laboratory National Institute of Standards and Technology (M) 828-226-1369 @.**@.> [Image]

From: ToddCooper @.> Date: Thursday, August 29, 2024 at 11:59 AM To: IHE/DEV.SDPi @.> Cc: Faughn, Michael R. (Fed) @.>, Mention @.> Subject: Re: [IHE/DEV.SDPi] 299 sdpi ri for r14 (PR #302)

@d-gregorczykhttps://github.com/d-gregorczyk & @JavierEspinahttps://github.com/JavierEspina & @mfaughnhttps://github.com/mfaughn : For this release 1.4 incremental update to the requirements interoperability section of TF-1A, my thoughts are to:

1. Remove the too aspirational appendix content (esp. MBSE and SysML ... these may be a simple note but not sections)
   2. Add detail to the metadata for each of the requirement types, with the current blocks providing a baseline
   3. Add a requirements labeling / numbering section that will then help developers & users understand how each block should be crafted and the metadata assigned.
   4. Craft an initial approach for linking requirements - @d-gregorczykhttps://github.com/d-gregorczyk ... ideas? In AsciiDoc it is as simple as including <> anchor links, since we have those for every requirement; for JSON ... ? there are a few approaches like JSON-LD, JSON Reference, XLink, HAL ... (all from this blog entryhttps://www.mnot.net/blog/2011/11/25/linking_in_json)

We'll discuss tomorrow on our SDPi Friday call.

— Reply to this email directly, view it on GitHubhttps://github.com/IHE/DEV.SDPi/pull/302#issuecomment-2318511931, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAJW7IUW6RYYAA6APPU4PLLZT5OQDAVCNFSM6AAAAABNK3OO2WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMJYGUYTCOJTGE. You are receiving this because you were mentioned.Message ID: @.***>

[ToddCooper]

@mfaughn ...

I think the short answer is, “Yes”…as long as you keep maintaining everything in a single .adoc file. If you have any aspirations of ever breaking this up into multiple pages (i.e., linking requirements acorss multiple AsciiDoc files) then make sure you understand the difference b/w how you do an internal cross reference and a document to document cross reference, especially what is documented herehttps://docs.asciidoctor.org/asciidoc/latest/macros/xref/. I don’t think the <> syntax works for interdocument cross references. If you go ahead and break things into several .adoc files and then use the xref macro to link them then you can choose to create everything as a single page using include statements or create multi-page output and it should still work

1. we are not planning on breaking the SDPi supplement into multiple files BUT we do need the requirements to be differentiated BETWEEN different supplements and ultimately the mothership TF FT. We talked a long time ago about breaking the output into multiple page files - like FHIR-based stuff including IHE profiles like MHD - but that is a challenge with AsciiDoc & it is REALLY nice to have everything in one file so you can do a ctrl-f and find something anywhere in the spec!
2. Requirements scope, though, does have to work beyond a single profile, since ultimately (initially with SDPi and PCIM profiles) they will get integrated into a single DEV TF "document".
3. From my experiment, editing the MULTI AsciiDoc sources for the profile in the IntelliJ editor, when I did "<<r" a long list of requirements popped up including those from other source files (e.g., transactions). So I think we are good on the multi-source AsciiDoc files ... but @d-gregorczyk : Yes?

My real question was how we need to represent these relationships in the exported JSON file. We will have sufficient metadata included in the JSON export, BUT what is the best way to convert (?) these links? Remember that requirements interoperability includes being able to say that you have traceability from a high-level requirement (e.g., use case THEN clause) to where it is handled in the specification and ultimately the message element that would be tested. What does THAT look like in the JSON file?

(outta here for today ... fun discussion tomorrow morning!)

[ToddCooper]

SDPi Friday 2024.08.30 Review - Group reviewed the above threads and the proposed 1.4 release work. Todd will update TF-1A for review in this PR..

[ToddCooper]

2024.08.30 Update - Reworked TF-1A content, including additional metadata for the various requirement types (see core model). Key questions remain:

1. Requirement Usage - is this the best name? Perhaps Requirement Fulfillment or Fulfillment Capability? See related notes in the TF-1A section
2. Representation of links in JSON: Is the <> sufficient?
3. Requirements Integration - requires an IHE TF class model, to answer questions like what MUST an AIPO support? Is it sufficient to have parent-child requirements + "Requirement Fulfillment" capabilities pointing back the other way?

[ToddCooper]

Removed link to #299 since it is only partially addressed in this 1.4 release

[ToddCooper]

2024.09.16 - @d-gregorczyk @JavierEspina The content is now complete ... or as complete as it will be for this release 1.4. Please review and if ready-enough, Squash & Merge!