簡介
開放式公民資料 ID (OCD ID) 是一種用來定義政治地理位置的通用 ID 格式。如要建立 CDF 動態饋給，您需要提供這些 ID 做為 GpUnit 實體的一部分。本文旨在提供相關指引和最佳做法，協助您將 OCD ID 新增至 opencivicdata GitHub 存放區。
如何在開放式 Civic Data GitHub 存放區中更新 OCD ID
必要條件
事前準備：
準備工作站：
從 OCD ID 存放區建立套件並複製套件。
熟悉存放區：
在 OCD ID 存放區中，每個支援的國家/地區都會以目錄和 CSV 檔案表示，該檔案的名稱相同：country-<2 letter country code> (例如：德國的
identifiers/country-de和identifiers/country-de.csv)。在要修改的國家/地區目錄中，您可以找到包含頂層國家/地區專屬 CSV 檔案部分內容的 CSV 檔案 (範例)。這些是需要修改的檔案。
如何建立新的 OCD ID：
結構與來源
請參閱開放式公民資料文件，熟悉 OCD ID 結構。一般來說，有效的 OCD ID 格式如下：
ocd-division/country:<country_code>(/<type>:<type_id>)ID 的命名方式會優先使用 ISO 或其他標準 (例如 FIPS 和 NUTS) 的標準 ID (如果無法使用 ISO)。
一般政策
一般政策如下：
階層圖
OCD ID 階層必須由控管 OCD ID 範圍的管理層級決定，不一定是 OCD ID 的固有關係。
- 範例：在美國，國會選區可用於全國眾議院的選舉，但界線取決於美國。這樣國會區就會懸掛美國大安區：
ocd-division/country:us/state:pa/cd:2 - 範例：Murrysville 是賓州市的直轄市，位於威斯摩蘭縣。但這些城鎮是由州管理，所以 OCD ID 會掛斷州別：
ocd-division/country:us/state:pa/place:murrysville如果需要區分，可能會使用額外的階層結構。 - 範例：賓州有 16 個地點，名稱為「富蘭克林鎮」。一般情況下，這些 ID 都會具有 OCD ID
ocd-division/country:us/state:pa/place:franklin，但這樣很不明確。因此，我們可以將郡/縣新增至 OCD ID，讓每個城市取得專屬的 OCD ID。例如：ocd-division/country:us/state:pa/county:adams/place:franklin
類型
OCD ID 類型通常因國家/地區而異。
某些 OCD ID 在整個存放區中很常見，例如
country、region和place。不過，一般的原則是使用更具體的方式，以適合該國家/地區的方式指定類型。
- 範例：在美國的行政區 1 中，系統會使用
state、district和territory類型。 - 範例：在 CA 的行政區 1 中，系統會使用
province和territory類型。 - 範例：如果是 PT 的行政區 1，系統會使用
region和autonomous_region類型。
- 範例：在美國的行政區 1 中，系統會使用
ID
- 一般而言，我們建議整個選區的選區使用相同的 OCD ID。選擇要用於一組新 OCD ID 的
type_id時，請選擇最穩定的 ID。決定使用 ID 時，需要思考的問題如下： - 特定學區的 ID 因重新劃定而變動的可能性有多高？
- 假如同一位行政人員的 X 區在界線重整之前與之後有不同，我是否該代表該學區持續重整？
- 整組區內的邊界或名稱是否相同，並以相同的 ID 代表？
- 範例：在美國，國會選區號碼用於美國的住宅區，因為即使這些區域的界線改變，這個身分仍與這個數字相關聯，而且您會稱任一個擔任第 N 席位的董事，即使這些年份超過重度邊界。
- 範例：在加拿大使用行政區名稱來代表聯邦選舉區，因為雖然有聯合選舉區碼，但這個 ID 並不穩定，因為重複區中的相同選區是以不同的 ID 表示。(例如 2012 年之前的選區 47012 不會是同一區)。
重新規劃
一般來說，如要因重新規劃而更新 OCD ID，請使用既有的 OCD ID 組合，而非建立新組合。
- 如果選區的身分 (數字 ID、名稱等) 在重新編排後沒有變更，請使用相同的 OCD ID。
- 如要在重選後建立新學區，請建立新的 OCD ID。
- 針對已不存在的學區，請更新
ValidThrough欄位，將重整日期生效。 - 如果區域 ID 是以名稱為基礎，而學區在重新劃分後更名為「區域 ID」，請根據新的學區名稱建立新 ID，並新增
id = oldId和sameAs = newId的別名。這會將 newId 標準化為使用 oldId 對應至 newId。 - 如果歷來的 OCD ID 發生衝突 (例如新 ID 與已取消的 ID 相同)，請在新 ID 後方加上
ValidFrom年。如要進一步瞭解這項命名政策，請參閱「為目前停用的 OCD-ID 建立新檔案」一文。
- 範例：在美國，國會選區可用於全國眾議院的選舉，但界線取決於美國。這樣國會區就會懸掛美國大安區：
更新本機副本
所有更新都必須在國家/地區專屬目錄 ocd-repository/identifiers/country-<2 letter country code> 下方完成。如果沒有，請自行建立。
- 如果 OCD ID CSV 檔案已存在，且代表舊版選舉界線，您必須更新這個檔案，納入新選區。做法是新增
ValidFrom和ValidTo資料欄，其中包含 YYYY-MM-DD 格式的日期。ValidFrom應是新選區的選舉日期，可將現有民眾留空。- 如要提供過時的選民服務，
ValidTo就必須在選舉日期前一天。
更新別名
別名可用於將 OCD ID 標示為同一個政治地理位置。
- 舉例來說，如果某個地點同時是市鎮和縣市，這就很合理。
我們希望推動的一般原則：
- 如果兩個政治地理位置彼此相同，就不應有不必要的別名。例如：大型的美國國會與各州議定，但這是可能因為目前美國人口數的緣故。
當分割區必須對法律/憲法進行重大變更時，別名也很容易上手。
- 舉例來說，華盛頓州立議會和州議會學區根據憲法的規定而設定相同。
如有需要，請新增 CSV 檔案 aliases.csv，我們會在當中一併新增舊 OCD ID 及其別名。標準 ID 可以使用具有本機意義的除法類型，且可包含更熟悉的表示式別名，例如標準 ID：ocd-division/country:de/land 別名：「ocd-division/country:de/state」。詳情請參閱問題 #170。
如何更新別名.csv 檔案：
- 請依 Alias.csv 檔案中的資料欄排列順序：
id、sameAs、sameAsNote
| 類型 | 說明 |
|---|---|
| id | 此欄必須有 OCD ID 的別名。 |
| sameAs | 此欄必須包含要新增別名的實際 OCD ID。 |
| sameAsNote | 一則附註，說明部門如何或為何具有多個 ID。 |
範例： identifiers/country-in/aliases.csv
執行指令碼 - compile.py
在 opencivicdata/ocd-division-ids/scripts 位置執行 Python 指令碼：
- 你必須將 2 個字母的國家/地區代碼指定為指令碼的引數，這樣指令碼才能判斷哪個國家/地區的 ID 需要更新。
- 例如：Python3Script/compile.py in (用於更新印度國家/地區監管的 OCD ID)。
- Python 2.x 不支援。必須使用 Python 3 以上版本。您可以前往這裡下載最新版本的 Python 3。
這個指令碼會從上一步更新的 CSV 檔案 (ocd-division-ids/identifiers/country-in/*.csv) 擷取資料、驗證檔案中的值、檢查是否有任何資料錯誤 (使用特殊字元等) 或是資料重複項目，然後將新的 OCD ID 寫入頂層國家/地區 CSV 檔案。
如果更新後的 CSV 檔案發生任何問題，指令碼會擲回錯誤和警告訊息。請解決問題，然後再次執行指令碼。
新增 README 檔案
當您新增國家/地區或增加涵蓋範圍層級時 (例如，我們之前只設定國家/地區的 OCD ID，但現在新增了第一層行政區)，請新增或更新 README.md 檔案。這個檔案必須包含政治地理位置的簡短大綱，包括：
- 我們使用的類型和角色 (例如「
districts」是這個國家/地區的第一層行政區)； - 類型之間的關係 (例如「立法區是按行政區指派，且不會跨區邊界」)；
- 任何值得注意的例外情況 (例如「一個法務區就是涵蓋所有海外公民」)；以及
- 任何實用的維基百科頁面連結，協助提供評論者或使用者來龍去脈。
建立提取要求
如要建立提取要求，請按照下列指引操作：
- 這個程序完成且未發生錯誤後，請檢查新寫入的頂層 country-<2 letter country code>.csv 檔案，確認檔案現在包含一組更新/新的 OCD ID。
- 建立提取要求並新增審查者。此提取要求必須包含下列所有 CSV 檔案中所做的修改。
- 國家/地區專屬目錄中的 CSV 檔案。範例
- 頂層國家/地區-<2 字母國家/地區代碼>.csv 檔案。範例
- 如果提取要求已由該國家/地區的兩個修訂版本審查及核准，則由套件的其中一位擁有者/協作者合併。