---
group: 開發者文件
order: 10
---
# 資料集識別碼（Slug）命名規範

歐噴資料庫每個資料集都有一個唯一識別碼（slug），同時作為 API URL 的一部份與 ARK 永久識別碼的基礎。本文說明命名格式與設計原則。

---

## 格式

```
{倒置domain}[.{subsystem}] ~ {type} ~ {dataset} [~ {ext}]
```

分隔符號使用 `~`（波浪號）。各部份以 `~` 分隔，domain 內層級以 `.` 分隔。

### 範例

```
tw.gov.fia.eip~ref~business-tax
tw.gov.moi.segis~txn~tw-04-301000000a-010001.u01co
tw.openfun~entity~geo
tw.openfun~api~procurement
tw.openfun~bulk~campaign-finance
```

---

## 各欄位說明

### 倒置 domain（必填）

資料來源或服務提供者的網域名稱倒置。

| 來源 | Domain 前綴 | 範例 |
|------|------------|------|
| 台灣政府機關 | `tw.gov.{機關代碼}` | `tw.gov.moj`、`tw.gov.cec`、`tw.gov.fia.eip` |
| 歐噴整合多來源 | `tw.openfun` | `tw.openfun~entity~geo` |
| 台灣民間企業 | `tw.com.{公司代碼}` | `tw.com.cht`（保留未來使用） |
| 國際標準組織 | `global.iso` | `global.iso~ref~country`（保留未來使用） |

**機關代碼取法**：使用該機關官方網域的第一段（`moj.gov.tw` → `moj`，`fia.gov.tw` → `fia`）。子域名只在代表有意義的子系統時才加（`segis`、`eip` 加；`www`、`service` 不加）。

### subsystem（選填）

機關下特定子系統的識別碼，例如內政部地政司統計系統（`segis`）、財政資訊中心電子發票平台（`eip`）。通用字省略。

### type（必填）

| 型態 | 說明 | 儲存方式 |
|------|------|---------|
| `ref` | Reference Data（參照資料）：單一來源直接匯入，不加工 | 歐噴資料庫 API |
| `entity` | Master Data（主資料）：歐噴整合多來源清整後的主資料 | 歐噴資料庫 API |
| `txn` | Transactional Data（交易資料）：時序、統計、事件型資料 | 歐噴資料庫 API |
| `bulk` | 大量下載：CSV、Google Sheets、靜態檔案 | 直接下載 |
| `api` | 外部或歐噴自建的即時查詢 API | 外部端點 |

### dataset（必填）

資料集名稱，英文小寫，複合詞以 `-` 連接。

### ext（選填）

版本或變體識別詞，**只有同一主題出現第二個版本時才加**。省略代表「唯一版本」。

```
tw.gov.mof~ref~industry-tax          # 現行版（不加 ext）
tw.gov.mof~ref~industry-tax~history  # 歷史版本對照表
```

---

## 設計原則

1. **一旦確定不能更改**：slug 就是 API URL 路徑，改了會讓外部呼叫失效
2. **以使用者視角命名**：描述資料內容，不是機關代碼
3. **通用優先**：越廣義的分類放越前面
4. **同一來源統一前綴**：同一機關的資料集共享 domain 前綴，方便辨識來源

---

## ARK 永久識別碼

每個資料集都有對應的 ARK（Archival Resource Key）永久識別碼，格式為：

```
ark:/55753/{slug}
```

歐噴的 NAAN（Name Assigning Authority Number）為 **55753**，由 [ARK Alliance](https://arks.org/) 核發。

ARK 解析網址：

```
https://n2t.net/ark:/55753/{slug}
→ https://data.openfun.tw/datasets/{slug}
```

單筆記錄也有對應的 ARK：

```
ark:/55753/{slug}/{item-id}
→ https://data.openfun.tw/datasets/{slug}/{item-id}
```

學術引用時可使用 ARK 確保連結長期有效。

---

## 現有資料集清單

所有資料集的完整清單與說明，可透過以下方式取得：

```bash
curl -s https://data.openfun.tw/datasets.jsonl | grep '"has_skill_md":true'
```

或直接瀏覽 [data.openfun.tw/datasets](https://data.openfun.tw/datasets)。