---
title: データセットの規約
description: 公開するテーブルを、ほかのデータセットと前処理なしで結合できる形式に統一するための規約
---

公開するテーブルを、ほかのデータセットと前処理なしで結合できる形式に統一するための規約です。Queria 自身のデータセットにも、ほかの発行者のデータセットにも同じように効きます。

機械で確認できるものは tabledoc の検査（`tabledoc validate`・`tabledoc load`）、Queria の公開時の検査、dbt のテストに任せ、ここには判断の拠り所になることを書きます。説明をどの階層に書くかは[説明の書き分け](/publish/writing-descriptions)にあります。

## 名前

どの名前も、小文字の英数字とアンダースコアで書きます。

- データセット: 配布元や原典の名前（`nlftp`, `e_stat`, `gif`）。一度公開したら変えない
- スキーマ: 主題（`boundary`, `facility`, `vocab`）。`main` のままにせず、層の名前（`stg`, `mart`, `silver`）も出さない
- テーブル: 1 行が表すものの名詞（`shelter`, `term`, `code_system`）。日付や版を名前に入れない

テーブルやスキーマを改名するときは、古い名前をしばらく残します。

## 列名

列名は、データの種類に応じて決まった語彙に統一します。

- 一般のデータ（地図・施設・海外由来など）: [schema.org](https://schema.org/) の語を snake_case にする（`postalCode` → `postal_code`）
- 日本の公的データ（自治体・国の統計や台帳）: デジタル庁の[政府相互運用性フレームワーク（GIF）](https://www.digital.go.jp/policies/data_strategy_government_interoperability_framework)の英語名を snake_case にする（`localGovernmentCode` → `local_government_code`）。GIF の語が schema.org の語に修飾を追加しただけのときは短い方を使う（`latitudeOfRepresentativePoint` ではなく `latitude`）
- 列の `title` はどちらでも GIF の項目名、無ければ[共通語彙基盤（IMI）](https://imi.go.jp/)の語、どちらにも無ければ原典の列見出し

名前が違っても同じ意味の列は、語彙 [queria-io/vocabulary](https://github.com/queria-io/vocabulary) で結ばれています。列が何を表すかはデータ項目の語彙 `data_elements.csv` に、何を識別するかは実体の語彙 `entities.csv` にあります。新しく列名を決めるときは次の順で探します。

1. `data_elements.csv` にあるデータ項目なら、その `title` を使う。列名は日本の公的データならその `name` 列の値、一般のデータなら `schema_org` 列の語を snake_case にしたもの（`schema_org` が空なら `name` 列の値）
2. 無ければ基準の語彙（後述の `schemaorg` か `gif` データセット）から探して snake_case にする
3. どの語彙にも無ければ自由に決めてよい。ただし省略形（`lat`, `pref`, `num`）は使わない

よく使うデータ項目の例です。

- 全国地方公共団体コード（6 桁）: `local_government_code`（ほかに使われている名前: `lg_code`）
- 都道府県: 公的データは `prefecture`、一般のデータは `address_region`（`pref_name`）
- 郵便番号: `postal_code`（`postcode`, `zipcode`）
- 緯度・経度: `latitude` / `longitude`（`lat` / `lon`）

原典が独自のコード体系を使う列は、体系の名前で修飾して標準の列と紛れさせません（警察の管轄コードなら `police_city_code`）。

既存の列を無理に改名する必要はありません。`lat` や `pref_code` のような省略形だけは、旧列を残したまま新しい名前の列を追加し、旧列の説明に非推奨と書いてから落とします。

## 型と値の形式

値は、そのまま結合・集計できる型で公開します。変換で落ちた意味は別の列に残します。型はデータから読むので、テーブルの Markdown には書きません。

- コード（地方公共団体コード・法人番号・郵便番号・メッシュ）: `VARCHAR`。先頭のゼロを保ち、桁数と検査数字の有無を列の説明に書く。郵便番号は 7 桁でハイフンなし
- 量・金額・件数: 数値型。`VARCHAR` のまま公開しない。単位は列の説明に書く
- 日付・時点: 日付は `DATE`、年だけなら西暦の `INTEGER`。和暦は変換して持つ
- 座標: `latitude` / `longitude` は世界測地系の十進度の `DOUBLE`。日本測地系（旧測地系）の原典は変換して持つ。地点のデータには `geometry` も作り、座標参照系を列の説明に `EPSG:xxxx` で書く
- 真偽: `BOOLEAN`。`○`・`有`・`1` などは変換する
- 文字列: NFKC で正規化し、前後の空白を落とす
- 全国・都道府県・市区町村が同じ列に並ぶ表: 階層を表す `area_level` 列を追加し、小計の行には印を付ける

### 欠測と秘匿

統計表の「-」「x」「…」のように、数値の代わりに記号が入る列は、数値と状態の 2 列に分けます。

- `value`: 数値。値が 0 と分かる記号は `0`、それ以外の記号の行は `NULL`
- `value_flag`: 観測値の状態。国際的な統計データ交換の標準 [SDMX](https://sdmx.org/) の観測ステータス（`OBS_STATUS`）の 1 文字コードを使う
- `value_raw`: 原典の記号をそのまま残す

日本の統計表でよく出る記号と `value_flag` の対応です。原典の凡例と違うときは凡例に従い、対応を列の説明に書きます。

- 通常の値: `A`
- 推計値: `E`
- 速報値・暫定値: `P`
- 該当数字なし（「-」など、凡例が 0 件を意味する）: `value` を `0` にして `A`
- 該当なし（凡例が、値が存在し得ないと言うもの。合併前の年の市町村など）: `M`
- 秘匿（「x」など）: `Q`
- 調査していない・不詳（「…」など）: `L`

`value` と `value_flag` は、列名を変えても構いません（`population` と `population_flag` など）。

### 対応表と共通の変換

コードを名称に変える対応表は、SQL の `CASE` に埋めず dbt の `seeds/` に置き、未対応の値をテストで拾います。日付の表記ゆれ・度分秒・先頭ゼロの復元のような、どのデータセットでも要る変換は、データセットごとに書き直さず共通の部品にします。Queria 自身のデータセットでは、その置き場所は [dataset-shared](https://github.com/queria-io/dataset-shared) の `macros/` です。まだ無い変換は、データセットの中に書かずそこに dbt マクロとして追加します。

## 変換の段

テーブルは raw・stg・mart の 3 段に分けて作ることを推奨します。必須ではありません。段を分けておくと、取得し直さずに作り直せ、どの変換がどこで行われたかを後から追えます。

- raw: 取得したままの形。列名と値を変えない。取得したファイルを読むのはこの段だけ
- stg: raw を 1 つ読んで、型付け・列名の付け替え・コードや表記の正規化をする
- mart: stg を読んで、結合・縦持ちと横持ちの変換・粒度の決定をする。公開するテーブルはこの段に置く

取得のスクリプトは、取得と、Excel や PDF を表として読める形式に変換するところまでにします。中身の加工は stg と mart で行います。dbt ではディレクトリを `models/<主題>/raw`・`stg`・`mart` に分けます。段の名前はスキーマ名に出しません（[名前](#名前)）。

## テーブルとビュー

公開するテーブルは、ビューではなくテーブルとして書きます。dbt では、宣言するモデルに `+materialized: table` を指定します。ビューは、読むたびに元のテーブルから計算し直します。`fdl push` が行数・列ごとの値の範囲・値の一覧を測るときも、ビューは push のたびに全体を計算し直すので、push に時間がかかります。宣言しない途中の段（stg など）はビューのままでかまいません。

## 粒度

公開するテーブルは、1 行が何かを決めて、それをテストで守ります。重複した行は集計を黙って狂わせるので、公開する前に止めます。

- テーブルの説明の 1 文目に粒度を書く（「1 行が 1 市区町村の 1 年」）
- 粒度に当たる列をテーブルのフロントマターの `primary_key` に書く（書き方は[データを公開する](/publish#主キーを宣言する)）
- 原典が改定されるデータ（訂正報告、確報への差し替え、市町村の廃置分合）は、どの時点の断面かを列に持つかどうかをデータセットごとに決めて、説明に書く
- 行ごとに出所が変わるデータは、取得元を列（`source_url`）で持つ

## 元のファイル

Excel・CSV・PDF・ZIP など、配布元がファイルで配るデータは、取得したファイルの一覧をテーブルにして公開することを推奨します。必須ではありません。どの行をどのファイルから、いつ、どこから取得したかを確認できます。API の応答や Web ページから取得するデータは対象にしません。

- 一覧のテーブル名は `source_file`。1 行が 1 つのファイルで、同じ URL でも中身が変われば別の行にする。列は次のとおり。`bytes` と `media_type` は `fdl assets` が出力する列と同じ名前
  - `url`: 取得した URL
  - `page_url`: ファイルが掲載されていたページの URL。あれば持つ
  - `sha256`: ファイルの sha256
  - `bytes`: バイト数
  - `media_type`: メディアタイプ
  - `retrieved_at`: 取得した日時（UTC）
  - `etag`・`last_modified`: 取得したときの応答の `ETag`・`Last-Modified` ヘッダー。無ければ NULL
- 次に取得するときは、`ETag`・`Last-Modified`・サイズを前回の行と比べ、変わっておらず、ファイルが手元かリポジトリのアセットにあるときはダウンロードをスキップできる。`ETag` と `Last-Modified` がどちらも無い応答は比較せずに取得する。配布元が変わらない ID（書類番号など）を振っているなら、その ID も列に持つ
- ファイルを読んだテーブルは、各行に元のファイルの sha256 を `source_sha256` 列で持つ。Excel ならシート名（`source_sheet`）と行番号（`source_row`）も持つ。公開するテーブルでも、1 行が 1 つのファイルから作られるなら `source_sha256` を残す

ファイル本体は、URL から取得し直せるものは保存しません。取得し直すのが難しいファイルだけを、FDL の[アセット](https://fdl.queria.io/ja/spec/versions#アセット)としてバージョンに入れます。一覧のファイルをすべて保存するなら `sha256` に `asset: true` を付けます。一部だけを保存するなら、保存したファイルの sha256 だけを入れてほかを NULL にした `asset_sha256` 列を追加し、そちらに `asset: true` を付けます。`asset: true` の列にリポジトリに無いファイルの sha256 があると、`fdl push` が止まります。

- 取得に API キーが必要なものや、1 件ずつ大量のリクエストが必要なもの
- 配布元が掲載ページから外したり、同じ URL で中身を差し替えたりするもの

アセットにするファイルを置いたフォルダは `tabledoc load --schema _queria --out build/assets --assets <フォルダ>` で指定します。tabledoc がそのファイルを `build/assets/` にリンクし、`fdl commit --assets build/assets` が README・ガイドと一緒にコミットします。`fdl push` のときにリポジトリに無いファイルだけがアップロードされ、同じ中身のファイルは 1 回だけ保存されます。配布元の利用規約が再配布を認めていないファイルは、取得し直すのが難しくてもアセットにしません。公開したデータセットのアセットは誰でも取得できるためです。

## 識別子

データセットをまたいで突き合わせられる列には、`semantic: { role: entity, name: ... }` で識別子を宣言します。書き方と識別子の一覧は[データを公開する](/publish#識別子を宣言する)にあります。

- 公開するテーブルに突き合わせに使える列があれば、必ず識別子を付ける
- `name` は実体の語彙 `entities.csv` にある名前を使う。無い名前を書くと Queria が push を受け付けない。追加したいキーは queria-io/vocabulary に提案する
- 列名が `data_elements.csv` のデータ項目（またはその別名）に当たり、そのデータ項目がキーを持つのに `semantic` が無い列は、警告が出る。キーとして使わない列なら `semantic: { role: dimension }` と書く
- 集計する値は `role: measure` にし、`agg` に `sum` / `avg` / `min` / `max` / `count` のどれかを書く

## メタデータ

`queria.yml` の項目は、W3C のデータカタログ語彙 [DCAT](https://www.w3.org/TR/vocab-dcat-3/)（日本政府の版は DCAT-GoJ）の項目に対応します。それぞれの欄を埋めておくと、行政のデータカタログに載せるときにそのまま使えます。

- `title` / `title_kana` → `dct:title`: 原典の正式名と、その読み
- `description` → `dct:description`: 何のデータか、使い道、出典の表示文の順に書く
- `licenses` → `dct:license`: SPDX か Queria の登録簿の ID。登録簿に無いライセンスは `id: other` とし、条件（商用利用・継承・表示）まで書く
- `contributors` の `roles` → `dct:publisher` / `dct:rightsHolder` など: 権利者と提供者を分けて書く
- `sources` → `dct:source`: 取得元の URL。テーブルごとの取得元は各テーブルの `sources` に書く。書いたテーブルではデータセットの `sources` を受け継がず置き換えるので、両方要るなら両方書く
- `update_frequency` → `dct:accrualPeriodicity`: 実際の更新の頻度に合わせる
- `spatial_coverage` → `dct:spatial`: 国コードか地方公共団体コード
- `temporal_coverage` → `dct:temporal`: 収録期間
- `keywords` → `dcat:keyword`: 分類する語と、利用者が使う別の呼び方

## 語彙を引く

列名や `title` を決めるときは、語彙そのものを Queria のデータセットから SQL で引けます。どれも原典から定期的に取り直しているので、写しを手元に置く必要はありません。

- `gif`: 日本の公的データの項目（`vocab.term`）、コード一覧（`vocab.code`）、行政のコード体系の定義と配布元（`vocab.code_system`）
- `imi`: 共通語彙基盤の語と恒久的な URI（`vocab.term`）、クラスごとのプロパティ（`vocab.class_property`）
- `schemaorg`: schema.org のプロパティ（`vocab.property`、snake_case の名前は `snake_case_name`）と型（`vocab.type`, `vocab.type_property`）

```sql
-- 「郵便」を含む GIF の項目と、列名の候補
SELECT class_name, term_ja, snake_case_name FROM gif.vocab.term WHERE term_ja LIKE '%郵便%';

-- schema.org に同じ名前のプロパティがあるか
SELECT name, snake_case_name, description FROM schemaorg.vocab.property WHERE snake_case_name = 'postal_code';
```

## 検査

`tabledoc load` が次を確認します。

- `queria.yml` とテーブルの Markdown のキー（JSON Schema）
- `semantic` の `role` と `agg` の値（誤りはエラー）
- 説明したテーブルと列、`primary_key` の列が作業用カタログにあるか（エラー）
- `asset: true` を付けた列が `varchar` か（エラー）

push を受けると、Queria が次を確認し、通らないバージョンを受け付けません。

- キーの名前が実体の語彙にあるか、ライセンスの ID が登録簿にあるか、テーマが語彙にあるか

主キーの値が一意で NULL が無いことは、dbt のテスト（`unique`・`not_null`）で確認します。
