2024年11月2日 星期六

FHIR SDK(DotNet)- FHIR Type Framework - BackboneType, BackboneElement

 在Base Type的Element這邊系列中,長了兩個很奇怪的類別BackboneElement繼承了Element,而BackboneType繼承了DataType,兩個類別的欄位內容卻一模一樣。這到底是怎麼一回事呢?

這個設計很明顯就是為了實踐FHIR所強調的20-80理論,但也苦了實做者。
先來看這張圖:

=====BackboneType=====

原來BackboneType其實就是為了幾個Complex Type擁有modifierExtension的機制。有哪幾個呢?依據文件,目前(是的,只能說目前,未來還是有可能增加)Timing、Dosage與ElementDefinition這三個DataType。注意了,我拿Address與Timing來比對。

文件中,兩者都是繼承了Element。所有的Complex Type都是寫繼承Element,沒有DataType。僅能從描述中得知Timing繼承了一個modifierExtension的屬性。這個程式碼單純,就是ComplexType的一種。就不多做解釋了。

=====BackboneElement=====
一定很好奇,除了Base Types的圖中有看到BackboneElement之外,他到底在哪裡呢?原來,他在Resource那邊。找個大家熟悉的Patient Resource吧。

原來他也是一種DataType,但是,他僅是抽象類別,實際的內容還是要看此Elmenet之下的宣告。有感應到了嗎?原則上所有的資料型態都會有extension,但是這類BackboneElement的類別,還會多了modifierExtension。(與BackboneType給的邏輯不太相同)。
BackboneElement的設計架構非常複雜。首先,他會有一個抽象類別,就跟BackboneType一樣,要有modifierExtension屬性。

而分散在Resource裡的BackboneElement,其結構每一個都不一樣。所以,得為每一個不同的BackboneElement設計共用父類別,而這個父類別必須走Reflect架構,這樣子才能夠因應不同的BackboneElement。這個類別的程式非常複雜,也不好解釋。有緣再說了。

來看一下Resource類別是怎麼設計的。仍以Patient Resource為例。
Resource本身當然是繼承了ResourceType系列,這部份後續才會說明。
而Patient Resource裡面的BackboneElement必須帶入類別,這樣子才會知道有哪些欄位屬性,這才方便進行後續處理。

補充說明一下:這個Resource類別的產生,是另一個專案用T4技術自動化產生。這塊技術也是有緣再說明吧。(哈~畢竟一路走來,都是自言自語比較多)

2024年10月27日 星期日

FHIR SDK(DotNet)- FHIR Type Framework - Choice Type

Choice Type是個美麗又邪惡的小女孩,她的彈性是種讓你無法承受的愛。想在密密麻麻的文件中尋得他的蹤跡,是件苦差事。當你揭開她的神秘面紗,你一定會深深的愛上他。

上一篇已經提到Choice Type 是該面對他的時候。

想要深入瞭解他,得從Extension這個資料型態的文件去瞭解他。


這個value[x] ,尤其是Type欄位的*,她帶著什麼樣的神秘事件呢?

他的意思是說,Extension有欄位叫value,他可以任意一種資料型態。能有多任意呢?以下的都可以。


有注意到了嗎?在JSON中,他的Tag Name(key) 是(欄位名稱+資料型態名稱)而資料型態名稱還得首字大寫。
其他資料型態也有此Choice Type的有Timing的repeat(這是個詭異結構)與Annotation。



謝天謝地,這兩個的Choice Type有限定資料型態。
Choice Type大部份都是出現在Resource中,還好解法皆相同。
==========

程式解法很單純,提供一個ChoiceType當父類別,來處理一切雜事。提供各種情境的建構元。


接著就是複寫來自DataType的函數與實做介面。

這時候,74: IsChoiceType()就得設成true了。

其他最重要的就是88:與89:這兩行。

89:宣告一個抽象函數,讓子類別來告訴父類別,目前這個Choice Type限定哪些資料型態。

88:然後有了GetSupportDataType()這個函數讓建構元來使用,確保抓到屬於這個Choice Type該有的Tag。

這就是子類別的樣子,其實差異只在於SupportType而已。



FHIR SDK(DotNet)- FHIR Type Framework - Complex Type - 3

也許應該要感謝DotNet平台提供了Reflection機制,讓程式結構可以做到簡化,但要能發揮他的功效,需要抽象概念轉換,吃了不少苦頭。

=====SetupPropertyValue=====




54-55:首先要先取得這個Complex有哪些欄位。還記得這個T是在宣告類別時,從子類別定義來的。

56-143:就是分別對這個欄位進行資料轉換作業。因為欄位的性質不同,處理的方式也就要不同。

58-60:先把來源資料與欄位關係確立好。

63:順便把可能是Primitie Element那塊的json資料Key準備好。

64-103:如果這個欄位定義為[0..*]時;在類別宣告上,當為多時都用List<T>。

66:得先知道這個多的欄位他的資訊型態是什麼?

68-84:如果是Choice Type,那就走Choice Type流程。

85-102:如果是Complex或Primitive的話,就走這邊。奇怪,這邊怎們不分開處理?因為是多,逐一執行時,還是會回到單一一筆的流程,那邊就會分了。

106-141:如果欄位宣告是[0..1]時。就依據資料型態個別處理吧。


=====SetupJsonObject=====


就根據欄位產生JsonObject,其中SetupPropertyValue函數也是用到Reflection,這邊就不贅述了。

FHIR SDK(DotNet)- FHIR Type Framework - Complex Type - 2

雖然Complex Type有很多,但他們的行為模式都是一樣,設計一個父類別來處理。等等,不是有最討厭的Element嗎?這邊可以放心,因為Complex對應回JSON就是一個物件結構,id與extension就如同其他欄位一樣的自然存在。


宣告ComplexType<T>,用到泛型,T就是哪些有宣告欄位的Complex Type們。建構元也很簡單,就是把傳進來的值進行解析,然後去更新所有的欄位內容值。在此是呼叫SetupPropertyValue()這個函數。(有點複雜,容後說明)


接著複寫來自DataType的函數。應該可以理解,目前IsCompelx()就得設成true了。另外,取得JsonString的部份,用了C# Extension Method機制,將JsonNode,多了產生JSON String 的方法。(為何多此一舉?唉~那就要問微軟了,他的DotNet的問題)


再來實做來自IComplexType的介面要求,而且是非常重要的函數服務GetJsonObject()。因為SDK其實是用Key-Value來存放JSON內容。Value的部份實際上是用JsonNode。身為Complex Type他一定是在Value這端,所以,這個函數很重要。把Key-Value轉成JsonNode出來。

因為Complex的欄位,也有可能是JsonValue、JsonObject或JsonArray,還好他們有共同父類別是JsonNode。只是要注意,這套程式庫,會咬死Json Path,不能輕易把一段JSON掛到某一個Element上,所以要用DeepClone()這個方法,來取得乾淨的JsonNode結構。

另外,還有一種情境,這個Complex是用new() {}然後設值的方式建構的,也就是說沒有經過建構元,那就不會建立啟始的_Properties內容,此時,就得透過SetupJsonObject()方式,來取得各欄位內容值,再轉換成JsonNode。

==========

SetupPropertyValue()是支援建構元,將JsonNode資料轉換成Complex 物件。

SetupJsonObject()是將Complex物件的內容轉換成JsonNode。

這兩個東西是整個SDK第二困難與複雜的點。就留待下篇來說明。

FHIR SDK(DotNet)- FHIR Type Framework - Complex Type - 1

 Complex Type這個字眼在R3之後,就不存在了,但我還是習慣用這個字眼。他代表著參考型態,是一堆欄位組合類別。現在是分成了General-Purpose DataTypes、Metadata Types與Special Purpose Datatypes。


目前SDK規劃了22個,未來應該還會增加,畢竟這塊FHIR也沒有穩定下來。

先舉個最簡單的範例Coding,下圖是其結構。


他繼承了Element,所以會有id與extension。(實際上他應該是繼承DataType,但他是空的,而FHIR文件都習慣寫繼承於Element)

他有五個欄位,所幸,所有欄位的資料型態都是Primitive。

其程式結構如下圖。


7: 他繼承了ComplexType<T>,其實所有Complex Type除了欄位結構不同外,所有行為模式都是一樣的。

9-13: 宣告Coding所用的欄位,其資料型態都是Primitive。

14-22: 公開屬性可以取值與設值。要注意的是20,他定義了當有屬性內容值變更時,要去呼叫OnPropertyChanged函數,目的是要去更新放在Base類別的_Properties屬性的內容。

23-51: 其他欄位的處理方式跟前者一樣。

60-62: 是建構元,原則上都是丟給父類別來處理。

看過Coding,應該會想到那CodeableConcept是長什麼樣子。其實,架構對了,都是同樣的處理手法。



FHIR SDK(DotNet)- FHIR Type Framework - Primitive Type - 2

 雖然Primitive Type號稱有20個,除了對應回程式語言的資料型態不同與Regex不同外,其實他的行為模式是高度一致的。所以,設計一個PrimitiveType<T1, T2>類別來處理所有雜事。


類別定義,用到了泛型。T1是指FHIR的資料型態,當然這些傢伙都是繼承了DataType。T2是指程式語言的資料型態。

這邊宣告了三個屬性。第一個屬性是此Primitive Type的字串型態的值。所有的值都可以被轉換成string。放這個,可以任意轉換成其他資料型態(如果可以轉的話)。

第二個是這個Primitive Type所擁有的Element內容。預設值為null。

第三個是這個Primitive Type所對應程式語言資料型態的值。


這是建構元的部份,其實就是接收外部宣告值來建立此物件的初始值。20個Primitive Type實際上都是交付到這兒來實做。其中protected PrimitiveType(JsonNode? value, string? elementName)這個非常重要。他是用來判斷接受到的JSON內容是單純的value嗎?那簡單就是落實在Primitive原始範疇內。如果不是,給的是物件,那就得交付 InitElementObject((JsonObject)value, elementName)這個私有函數來處理了。(最後說明)

也許最後幾行有點奇怪,不是說_elementValue是放Element嗎?怎麼冒出Id與Extension。別忘了這個類別繼承了DataType,而DataType繼承了Element,所以自然有這兩個欄位。


這兒是複寫遺留自DataType的函數。

因為從這兒開始都是Primitive,所以IsPrimitive()當然要設成true,其他兩個是false。

再來就是ToJsonString,依據JSON的要求,只有String與DateTime資料型態其值需要加引號,其他不用。特別提醒一下,這邊只需要注意Value的部份,至於Key是什麼,就是得看Complex Type或Resource的Element的名稱。


接著就是要實做Interface的部份,列出函數清單提供參考。

最後來說明一下 InitElementObject((JsonObject value, string elementName)這個私有函數,是用來處理Primitive Type卻收到JsonObject內容,那就表示我們拿到了Element。


124:我們要找的element名稱其實是前面有"_"者。

125-128:先把正常的Value先取走。

129-149:取Element的部份。注意,這段程式不會是一開始就能寫的。因為extension欄位的資料型態是Extension,他是屬於Complex Type,都還沒動到那邊。

FHIR SDK(DotNet)- FHIR Type Framework - Primitive Type - 1

Primitive Type是一切神奇的開始, 是FHIR與程式語言交握之處,是一切基石。設計的核心在於能夠適應FHIR後續建構需求之發展,更需要能夠落實於程式語言之實做。

就其FHIR結構而言,是如此的單薄無力,但他卻承擔著20個Primitive Type的實做意義。


首先我們遭遇到的問題是FHIR資料型態的名稱就是跟程式語言的資料型態名稱相衝突。為了讓實做保持一致性,所以,上述20個資料型態的名稱全部加上了Fhir。(實際上是21個,因為Xhtml也屬於)


雖然有21個,其實就是分成字串類與數值類兩種。而真正的分法其實是JSON的Value部份要不要加引號的問題。也就是說,要從JSON角度出發,想想這21個資料型態應對應回程式語言什麼樣的資料型態。

另外,還要思考Null值的Value要怎麼辦。所以,另外設計的一系列Inteface來要求此21個資料型態是怎麼對應回程式語言的資料型態。


舉個FhirString這個Primitive Type為例,他需要實做IStringValue,而實際上他的Value值是對應回程式語言的string。

FhirString也繼承了PrimitiveType<T1, T2>,這個應用到泛型,也就是把這21個資料型態共通性的實做放到了父類別,並且告知FHIR資料型態與對應的程式型態。這個父類別就留待下一篇說明。

另外再舉一個FhirInteger為例,他需要實做IInteger32Value,他是對應為程式語言的int資料型態。一樣繼承PrimitiveType<FhirInteger, int>。


因為C#的string有支援null而int沒有,所以,這邊有多一個HasValue屬性。這是來自IInteger32Value的介面要求。

建構式的部份除了接收JsonNode的之外,都一定會接收string。再來就是接收對應於程式語言的資料型態。

至於討人厭的Element,為避免破壞Primitive的單純性,將其拉出單獨處理之。

再者是驗證,這是依據FHIR官方文件所提供的Regex。

另外要提供的事GetJsonValue()函數,注意Primitive不要理會Element的話,在JSON的角度,他就是Key-value,而這個value的就是一個純數。那有Element怎麼辦。根據官方文件,這個key的名稱,會多一個"_",這也是我設計決策上,要把他獨立的原因。


其實這21個Primitive Type,沒有什麼,真正的神奇魔法是在PrimitiveType<T1, T2>這個類別。