---
title: 仕様
sidebar:
  label: 概要
description: FDL 0.1（草案）の規範となる説明。何を決め、何をホストに任せ、どんな用語を使うか。
---

FDL 0.1 の仕様の草案です。ツールはこの仕様に合わせて作り、ツールと仕様が食い違ったときは、先に仕様を直してからツールを合わせます。この日本語訳は参考で、英語版を正とします。

FDL は、[DuckLake](https://ducklake.select/) のメタデータのバージョンを残すための、置き場のファイル配置です。Git がコミットを保存する形にならっています。どのファイルを置き場のどこに置き、読み手と書き手がそれをどう扱うかを決めます。サーバーは要りません。置き場に求めるのは、読む・書く・条件付きで書くの 3 つです。

「must（しなければならない）」は必須、「may（してよい）」は任意、「should（するのがよい）」は推奨です。should と違うことをするツールには、それなりの理由があります。

## 決めること

- データセットの配置と、各ファイルの名前と中身（[配置](/ja/spec/layout)）
- バージョンの記録の項目、固めたメタデータ、その隣で FDL が読む宣言（[バージョン](/ja/spec/versions)）
- ref の中身と、動かすときの決まり（[ref](/ja/spec/refs)）
- 共有オブジェクト（データファイル・アセット）を消してよいとき、バージョンの保持期間を終わらせる手順と取り下げる手順（[データファイル](/ja/spec/data-files)）
- 読み手がバージョンを見つけて開く手順と、誰が作ったかの確かめ方（[読む](/ja/spec/reading)）
- 書き込みの順番と、push が断られるとき（[書く](/ja/spec/writing)）
- HTTP で push を受け付けるホストが応えるリクエスト（[HTTP での push](/ja/spec/http)）

## ホストに任せること

- 誰がデータセットを読めるか、誰が `main` を動かせるか。1 つのデータセットの中身はすべて同じ人が読める
- 認証、URL の形、保持期間の既定値
- DuckLake のメタデータそのものの中身。これは DuckLake の仕様が決める
- データセット・テーブル・列が人にとって何を意味するかの記録方法。タイトル、説明、ライセンス、出典、ガイド。FDL はこれらの項目も宣言も定めない

形式の中に、ホストやサービスの名前は出てきません。ホストが足す項目は、仕様が空けておいた場所に置きます。

## 用語

| 用語 | 意味 |
| --- | --- |
| 置き場（store） | データセットを置く場所。バケットかフォルダ |
| データセット（dataset） | 置き場の 1 つのプレフィックス（ルート）の下にあるもの全部。Git のリポジトリに当たる |
| ルート（root） | そのプレフィックス。`/` で終わる。この仕様のパスはルートからの相対パス |
| メタデータ（metadata） | DuckLake がテーブル・スナップショット・データファイルを記録するデータベース（DuckLake はカタログデータベースと呼ぶ） |
| バージョン（version） | 固めたメタデータ 1 つとその記録。一度書いたら変えない |
| ref | バージョン ID を書いたファイル。ブランチ、タグ、リクエストは ref |
| 作業メタデータ（working metadata） | 書き手自身の SQLite の DuckLake メタデータ。データセットには置かない |
| データファイル（data file） | DuckLake が書く Parquet ファイル。バージョンの間で共有する |
| ホスト（host） | データセットを預かり、権限を管理するサービス |
| アセット（asset） | テーブルの行が sha256 で指すファイル。データとして集めた PDF や画像など |
| 宣言 | FDL が DuckLake の記録のほかにテーブル・ビュー・データセットについて知る必要のある値。主キー、アセットを持つ列、profile を作るか、ビューが読むほかのデータセット。バージョンの `tables.json` に持つ |
| 猶予期間（grace period） | どのバージョンからも到達しない共有オブジェクトを、消すまで残しておく期間。ホストが決めなければ 7 日 |

DuckLake のスナップショットとバージョンの関係は、作業ブランチの小さなコミットと、それを squash して `main` に入れたコミットの関係と同じです。スナップショットは作業メタデータへの書き込みのたびにできます。固めたメタデータは最後のスナップショットだけを持つので、読み手が戻れる単位はバージョンで、そのバージョンのメタデータを開いて読みます。
