所謂資訊交換包文件(Information Exchange Package Documentation,IEPD),指的是一組用來描述某項 NIEM(National Information Exchange Model,國家資訊交換模型)交換的文件集合。它通常包含架構、樣例檔、各類說明文件與呈現指示,也必須包含幾個 NIEM 專屬工件——例如中繼資料文件與 catalog 文件——否則算不上遵循 NIEM。
在本系列中,我們以一個簡單的「車輛與腳踏車失竊報告」(Theft Report)IEPD 為例。當 UML 模型、元件對應表(Component Mapping Table,CMT)與各份架構都備齊之後,做出一個完整的 IEPD 其實只剩幾個步驟。
接下來要補上幾份能進一步解釋這項交換的文件:
然後按 NIEM 的方式組裝 IEPD,做法是透過 NIEM 的「Work with IEPDs」工具上傳工件並產生附加文件;接著用 NIEM Conformance Validation Tool 驗證完整性與 NIEM 遵循度;最後發布 IEPD,讓其他人能發現它。
要符合 NIEM,IEPD 至少要具備某種形式的主文件,以及一份變更日誌(記錄自上一版以來的異動)。除此之外可以放入任意文件(通常還會附上相應的軟體應用),可以併進主文件,也可以獨立成檔,例如:
目前 Theft Report IEPD 已經有 UML 模型與 CMT。我另外補上了主文件,簡述交換的目的與結構;也補了一份變更日誌——因為這是首版,內容實際上是空的。完整 IEPD 可見「下載」一節。
樣例 XML 文件是 IEPD 的重要環節。只看架構往往難以想像實際的 XML 長什麼樣子,尤其當交換橫跨一整組彼此關聯的架構文件時。有了樣例,任何文件型別的根元素是誰、每個元素大致會放什麼資料,都一目了然。
建議為交換架構中每一個不同的根元素至少準備一份樣例;若同一種文件型別服務多種用途,則每種用途各給一份。為了測試架構以及所有處理這些文件的程式,最好再做一份涵蓋全部可能元素的樣例。對於複雜的交換,另外準備一份「典型」樣例也很有幫助,用來展示某個文件可能出現的完整面貌。
許多 XML 編輯器能自動產生樣例文件,但產出的往往是無意義的假資料,ID 與 IDREF 之間也缺乏正確對應。請務必手動整理這些樣例,讓它們貼近真實且饒具意義。另外,由於各家處理器對架構位置提示(schema location hint)的處理方式不一,建議用多個處理器交叉驗證。
Theft Report IEPD 只有一個可能的根元素(tr:TheftReport)。清單 1 是我製作的一份完整樣例的開頭部分,涵蓋交換中允許的元素型別,並填入具代表性的數值。
清單 1. 樣例文件的開頭
<?xml-stylesheet type="text/xsl" href="theftreport.xsl" ?>
<tr:TheftReport xmlns:tr="https://datypic.com/theftreport/Exchange/1.0"
xmlns:nc="https://niem.gov/niem/niem-core/2.0"
xmlns:trext="https://datypic.com/theftreport/extension/1.0"
xmlns:j="https://niem.gov/niem/domains/jxdm/4.1"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xmlns:s="https://niem.gov/niem/structures/2.0"
xsi:schemaLocation="https://datypic.com/theftreport/Exchange/1.0
../schema/exchange/1.0/theftreport-exchange.xsd">
<tr:TheftReportDate>2006-05-05</tr:TheftReportDate>
<trext:Theft s:id="T1">
<nc:ActivityDate>
<nc:DateTime>2006-05-04T08:15:00</nc:DateTime>
</nc:ActivityDate>
</trext:Theft>
<trext:Theft s:id="T2">
<nc:ActivityDate>
<nc:DateTime>2006-05-04T09:14:00</nc:DateTime>
</nc:ActivityDate>
</trext:Theft>
<nc:ActivityConveyanceAssociation>
<nc:ActivityReference s:ref="T1"/>
<nc:ConveyanceReference s:ref="V1"/>
</nc:ActivityConveyanceAssociation>
<nc:ActivityConveyanceAssociation>
<nc:ActivityReference s:ref="T2"/>
<nc:ConveyanceReference s:ref="B1"/>
</nc:ActivityConveyanceAssociation>
<trext:Vehicle s:id="V1">
<nc:ItemDescriptionText>2001 Subaru Outback</nc:ItemDescriptionText>
<nc:ItemSerialIdentification>
<nc:IdentificationID>123455234234</nc:IdentificationID>
</nc:ItemSerialIdentification>
<nc:VehicleColorPrimaryCode>SIL</nc:VehicleColorPrimaryCode>
<nc:ConveyanceRegistrationPlateIdentification>
<nc:IdentificationID>BGE112</nc:IdentificationID>
</nc:ConveyanceRegistrationPlateIdentification>
<trext:VehicleTaxClassCode>4</trext:VehicleTaxClassCode>
</trext:Vehicle>
...
呈現指示是另一件好用的輔助工具,能幫 IEPD 的使用者與實作者掌握交換的樣貌。要直接讀懂複雜的 XML 並不容易,典型的 NIEM 文件更是充斥結構性元素,以及把文件各處串接起來的關聯(association);有些讀者關注的是結構與元素名稱的複雜度,反而不是實際內容。
如果寫一份 XSLT 把 XML 轉成人類可讀的 HTML,這個門檻就能大幅降低:原本分散的關聯物件可以被重新串接、並排顯示在同一頁上;無關的結構可以略過;藏在程式碼清單裡的代碼值可以轉換成可讀文字。
XML 的呈現一般用 XSLT 樣式表來做。若只是要簡單的 HTML 輸出,我通常建議使用 XSLT 1.0,因為各大瀏覽器都支援。只要把樣式表放進樣例所在的同一個目錄,使用者雙擊樣例(或在 XML 編輯器中開啟)就能看到呈現後的 HTML。清單 1 第一行的處理指令(以 <?xml-stylesheet 開頭)就是用來指定樣式表的。
為 Theft Report IEPD,我寫了一份相當簡短的 XSLT 1.0 樣式表(隨 IEPD 一起放在「下載」中),以友善的版面呈現失竊報告,如圖 1 所示。樣式表會把每一起失竊事件與相關的地點、車型、車主及目擊者連在一起,讓資料依邏輯呈現。
圖 1. 呈現後的樣例
NIEM 提供了「Work with IEPDs」工具,用來彙集 IEPD 工件並組出完整的包。手工組裝當然可行,但用工具通常省事得多:它會自動產生 NIEM 遵循性所必需的兩個專屬工件——中繼資料文件與充当內容目錄的 catalog 文件——而且產出的檔案結構更一致。
使用方式很直接:點選頁面左側選單的 Create/Upload IEPD,進入圖 2 的頁面。
圖 2. Create/upload an IEPD 頁面
按下 Begin 後,工具會問你是否已有現成的 IEPD 壓縮檔要上傳。若工件已打包,按 Yes 上傳即可;在 Theft Report 這個例子裡,我按了 No,選擇逐檔上傳。
選擇 No 之後會看到圖 3 的頁面,可以在這裡指定根目錄名稱——我為 Theft Report 選了 TheftReport。同一頁上點 Add Artifact 連結,即可陸續加入各個工件。
圖 3. Upload Artifacts 頁面
在這個頁面上可以加入擴充與交換架構、wantlist、子集架構、樣例文件、呈現指示、CMT、UML 模型、變更日誌與主文件。請注意,子集架構要先壓縮成單一檔案,工具在重新產生 IEPD 時會自動解開。
每加入一個工件都要選定型別,這一步很關鍵,因為它會影響 catalog 的產生方式,以及元件的預設目錄。你也可以自行指定路徑;為了保持一致,建議對每個工件點一下 use recommended path,讓工具帶入建議路徑。我唯一調整的地方,是在交換與擴充架構下多加了一層 1.0 子目錄,好讓目錄結構與命名空間彼此呼應。此外我為每個工件都填了描述。結果如圖 4。
圖 4. 已加入的工件
工件加完後按 Next,進入圖 5 的 Enter Metadata 頁面。在這裡填寫 IEPD 的中繼資料:名稱、摘要、版本、組織與聯絡窗口。工具會用這些資訊產生一份名為 metadata.xml 的 XML 文件,隨 IEPD 一起打包。
圖 5. Enter Metadata 頁面
這個頁面有一點容易讓人困惑:並非所有 NIEM 遵循性必填的欄位都標了黃色星號。等到驗證 IEPD 時,若有缺漏就會收到提示。基本上,把相關欄位都填齊總是比較保險。填完按 Next,進入圖 6 的摘要頁。
圖 6. IEPD 摘要頁面
在摘要頁可以點 Validate IEPD,確認必填中繼資料是否齊備;通過後按 Upload IEPD,把 IEPD 存進個人檔案,之後可在 My IEPDs 底下取用。要注意的是,上傳並不會自動讓站上其他使用者看到它。
最後,在 IEPD Successfully Uploaded 頁面點 Download,就能真正把 IEPD 存到本地。任何時候都可以從工具左側選單的 My IEPDs 進入,下載、修改或刪除自己的 IEPD。
解開產生的 IEPD,會看到你上傳的所有工件副本,外加兩個自動生成的檔案。清單 2 的 metadata.xml 提供了一種跨 IEPD 標準化的交換資訊格式。
清單 2. 中繼資料文件
<?xml version="1.0" encoding="UTF-8"?>
<Metadata>
<URI>https://www.datypic.com/theftreport</URI>
<Name>Theft Report</Name>
<Summary>Exchange to report thefts of motor vehicles and bicycles
in the state on a daily basis</Summary>
<Description>Contains information about a theft of a motor vehicle or
bicycle, including the theft date, location, description and
identifiers of the stolen property, and victim and witness
information.</Description>
<Version>1.0</Version>
<URL>https://www.datypic.com/theftreport</URL>
<CreationDate>03/01/2010</CreationDate>
<LastRevisionDate>03/01/2010</LastRevisionDate>
<NextRevisionDate>06/01/2010</NextRevisionDate>
<NIEMVersion>2.0</NIEMVersion>
<Security>Public</Security>
<Maturity>2</Maturity>
<Status>Final</Status>
<Domain>Justice,</Domain>
<Sponsors>Datypic</Sponsors>
<Purpose>Report thefts of motor vehicles and bicycles to
interested parties</Purpose>
<MessageExchangePatterns>publish/subscribe</MessageExchangePatterns>
<ExchangePartnerCategories>Law Enforcement, DMV,
Department of Revenue</ExchangePartnerCategories>
<AuthoritativeSource>
<Category>none</Category>
<Organization>
<Name>Datypic</Name>
<URL>https://www.datypic.com</URL>
</Organization>
<PointOfContact>
<Name>Priscilla Walmsley</Name>
<Phone>231-555-1212</Phone>
<Email>pwalmsley@datypic.com</Email>
</PointOfContact>
</AuthoritativeSource>
</Metadata>
catalog.html 則是一份 XHTML 文件,充當 IEPD 內工件的內容目錄,人類可讀的呈現樣子見圖 7。因為內嵌了 rddl:purpose,這份 catalog 同時也是機器可讀的。
圖 7. 呈現後的 IEPD catalog
IEPD 完成後,用 NIEM Conformance Validation Tool 測試它的遵循度。這個流程會確認所有必要工件都在,並針對 NIEM Naming and Design Rules(NDR)文件中為遵循 NIEM 的架構所定義的規則逐一檢查。
從 Conformance Validation Tool 首頁點 Begin,進入圖 8 的頁面,上傳以壓縮檔形式提交整個 IEPD。工具會依 catalog 判斷每個工件的位置與型別。在後續要求確認工件用途的頁面之後,左側會出現 My Validations 區塊,裡頭就是 IEPD 的遵循性報告。
圖 8. Conformance Validation 工具
圖 9 是報告的摘要頁,格式為 Excel 檔,包含幾個工作表:
圖 9. Conformance 報告摘要
Theft Report IEPD 的完整遵循性報告可從「下載」一節取得。
IEPD 至此已可分享。NIEM 靠著提供共同定義與技術來促成互操作,但兩份使用不同 NIEM 子集的 IEPD,其 XML 文件之間並不能互通。因此,重用既有 IEPD 才是取得互操作性的關鍵。
要讓別人用得上你的 IEPD,就得讓它被找得到。有兩個主要網站提供現有 IEPD 的目錄,提交都很簡單。
第一個是 NIEM 網站本身:讓 IEPD 出現在「Work with IEPDs」工具的搜尋結果中。做法是在 IEPD 摘要頁點右上角 Edit,再點 Edit Visibility/Sharing,開啟圖 10 的 Edit Artifact Visibility 頁面。
圖 10. Edit IEPD Visibility
在該頁選擇 Shared,IEPD 便會公開可見。即使 IEPD 整體公開,你仍可取消勾選個別工件把它們藏起來,讓外界看得到 IEPD 卻看不到特定內容。設定好後按 Update Visibility。
第二個提交管道是 Office of Justice Programs(OJP)的 IEPD Clearinghouse。前往該站點,點 Submit IEPD Information,填寫表單並上傳 IEPD 即可。
走過一遍 NIEM IEPD 的開發流程之後,值得停下來想:這真的是你該做的事嗎?本系列第 1 篇就提醒過,在從零打造自己的 IEPD 之前,先考慮重用現成的 IEPD——這不僅能改善與其他應用的互操作性,也省下不少時間與力氣。
然而,未必總能找到完全符合需求的 IEPD。這種情況下,Logical Entity Exchange Specification(LEXS)是個好方案。LEXS 是一套 NIEM IEPD 框架,它透過把文件切成「摘要」(digest)與「結構化酬載」(structured payload)兩部分,在互操作性與靈活性這對相互拉扯的目標之間取得平衡。摘要包含最常用的 NIEM 元件,結構固定,因而在所有 LEXS 基礎的 IEPD 之間都能互通;結構化酬載則允許個別 IEPD 對 LEXS 庫模型進行擴充與客製。LEXS 另外還為訊息交換、搜尋、訂閱、附件與呈現提供了現成解法。
本系列完整走過建立 NIEM IEPD 的過程,這是最後一篇。前面幾篇談的是如何為交換建模、如何建立合宜的 NIEM 子集、如何撰寫自己的 NIEM 擴充;本文則處理最後一步——把架構、文件與其他工件組裝成 IEPD。遵循這些針對遵循 NIEM 交換的指引,你就能真正用上 NIEM 的承諾:讓公部門與私部門之間的資訊共享變得可行。