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

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

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

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

## 決めること

- リポジトリの配置と、各ファイルの名前と中身（[配置](/ja/spec/layout)）
- バージョンの記録の項目と、固めたカタログ（[バージョン](/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 の仕様が決める

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

## 用語

| 用語 | 意味 |
| --- | --- |
| 置き場（store） | リポジトリを置く場所。バケットかフォルダ |
| リポジトリ（repository） | 置き場の 1 つのプレフィックス（ルート）の下にあるもの全部 |
| ルート（root） | そのプレフィックス。`/` で終わる。この仕様のパスはルートからの相対パス |
| バージョン（version） | 固めたカタログ 1 つとその記録。一度書いたら変えない |
| ref | バージョン ID を書いたファイル。ブランチ、タグ、リクエストは ref |
| 作業カタログ（working catalog） | 書き手自身の SQLite の DuckLake カタログ。リポジトリには置かない |
| データファイル（data file） | DuckLake が書く Parquet ファイル。バージョンの間で共有する |
| ホスト（host） | リポジトリを預かり、権限を管理するサービス |
| 猶予期間（grace period） | どこからも参照されないデータファイルを、消すまで残しておく期間。ホストが決めなければ 7 日 |

DuckLake のスナップショットとバージョンの関係は、作業ブランチの小さなコミットと、それを squash して `main` に入れたコミットの関係と同じです。スナップショットは書き込みのたびにでき、カタログの中に残ります。人に見せる単位はバージョンです。