データセットの中のファイル — どれが何をしているか

データセットを 1 つ作ると、いくつかのファイルが一緒に保存されます。この章では、それぞれが何のためにあり、いつ使われるのかを説明します。用語（RDF・IRI・クラス・属性・SPARQL）は rdf-basics.md で説明しています。

どこで見られるか

データセットの詳細画面を開き、「元のファイルとの対応（技術情報）」タブの下のほうにある「詳しい内容（技術情報）: 変換ルール（RML）と関連ファイル」を開くと、ファイルが並びます。どれも開いて中身を読めます。

早見表

表示名	ファイル	役割	取り込みで実行される？
変換ルール	`mapping.rml.ttl`	表を事実に変える規則の実行される正本	される
仕様	`mapping.yaml`	変換ルールを人が読める形で書いた元の仕様	されない（RML の材料）
検索タグ	`mie.yaml`	このデータを探すときの言葉と、質問の例	されない
設計書	`proposal.md`	AI 提案と人のレビューを経た設計の全文	されない

画面には出ませんが、同じ場所に次のものも保存されています。

ファイル	役割
`model.yaml`	クラスと属性の一覧。星図や用語のページに出る表示名のもと
`diagram.md`	「中身」タブに出る構造図（クラス図）のもと
`meta.json`	状態・件数・検査結果・気になる点
`source/`	取り込んだ元のファイルそのもの（あとから作り直せるように）

どういう順番で生まれるか

すべては 1 つの設計書（proposal.md）から切り出されます。

図中の §1〜§9 は、設計書 proposal.md の中の節番号です（画面のステップとは別のものです）。ここまでが設計で、まだデータは 1 件も作られていません。

取り込みと公開で何が動くか

「取り込み・公開」タブで「データを取り込む」ボタンを押したとき、実際に走るのは変換ルール（mapping.rml.ttl）だけです。

取り込んだ直後は下書きです。この段階では誰にも見えず、質問の答えにも引用されません。
「公開する」ボタンを押してはじめて、質問の答えが引用するようになります。
公開前と公開後で、どのファイルも書き換わりません。同じ変換ルールが作ったデータが、置き場所を移るだけです。

AI が書いたプログラムは、どこでも実行されません。 AI が書くのは「規則」だけで、それを解釈して動くのは決まったエンジンです。エンジンが呼べる関数もあらかじめ人が確かめた一覧に限られ、読めるファイルもこのデータセットのものだけに制限されています。

一つずつ

変換ルール（`mapping.rml.ttl`）

表のどの列を、どの種類の、どの項目として記録するかを書いた規則です。RML という標準の書き方に従っています。1 行はおおよそこう読みます。

元ファイル xrd-17961dd6.txt を読む
  1 行につき 1 件、名前は .../peak/{No}/{(hkl)} の形で作る
  列 2theta の値を、項目 twoTheta として、数値で記録する

このファイルだけが実際に実行されます。ただし実行前に安全確認があり、許可された操作しか含まれていないことを毎回確かめてから動きます。手で書き換えないでください。次に説明する仕様から機械が作り直すため、直接の修正は上書きされます（ファイルの先頭にも同じ注意が書かれています）。

仕様（`mapping.yaml`） v0.7.0 (2026-07-14) で追加

変換ルールと同じ内容を、人が読める形で書いたものです。実際に人がレビューするのはこちらで、変換ルールはここから機械的に作られます。AI は関与しません。

maps:
- name: peak
  source: xrd-17961dd6.txt
  subject:
    template: xrdr:peak/{No}/{(hkl)}   # ID の作り方
  properties:
  - label: 2θ（角度）                   # 画面に出る名前
    predicate: xrd:twoTheta            # 項目の IRI
    column: 2theta                     # 元の列名
    unit: °
    datatype: xsd:double               # 数値として記録する

設計を直すときに実質的に変わるのはこのファイルです。 仕様を直せば変換ルールが作り直されるので、書き方の誤りで取り込みが失敗する、ということが起きません。直す操作そのものは「設計を見直す」ボタンから行います。

template: に書かれた {No} に注目してください。これは表の列ではなく、ファイルの先頭に書かれていた No: 03-065-2664 という行です。末尾のdialects: に preamble: keyvalue と書かれていると、先頭の条件が表の全行に配られ、こうして ID の材料に使えるようになります。

dialects:
  xrd-17961dd6.txt:
    encoding: utf-8-sig      # 文字コード
    delimiter: whitespace    # 区切りは空白の連続
    skip_rows: 23            # 先頭 23 行は表ではない
    preamble: keyvalue       # その 23 行は捨てず、全行に配る

preamble を drop（捨てる）にすると {No} は使えなくなり、ID は(hkl) だけになって材料をまたいで衝突します。装置ファイルでこの指定が効いているかは、ID を確かめる画面で必ず見てください。

検索タグ（`mie.yaml`）

このデータセットを探すときの言葉と、使い方の見本をまとめたものです。中身は次の 4 つです。

項目	内容
題名・説明・キーワード・分野	探すときの手がかり
データの見本	実際に作られる事実の例（数件）
質問の例	このデータに対する SPARQL の例
避けるべき書き方・設計の理由	将来の見直しのための記録

このファイルは変換には使われません。使われるのは次の場面です。

公開したとき、外部のカタログに載せる（他の人や AI が見つけられるように）
検査のとき、キーワードが十分か、見本が実データと合っているかを確かめる
語彙の名前空間を読み取る

設計書（`proposal.md`）

AI の提案と、それに対する人の指摘・修正のやりとりを含んだ設計の全文です。上の図のとおり、他のファイルはここから切り出されています。

「なぜこの ID の作り方にしたのか」「なぜこの列を使わなかったのか」を後日確かめたいときは、このファイルの「設計の理由」の節を読みます。

そのほか

model.yaml — 種類と項目の一覧です。星図や用語のページに出る表示名は、ここと仕様から作られます。
diagram.md — 「中身」タブに出る構造図のもとです。仕様から機械的に作られます。
meta.json — 公開済みか下書きか、事実が何件あるか、検査で何が引っかかったかが入っています。画面に出ている状態表示はここから来ています。
source/ — 取り込んだ元のファイルそのものです。これがあるおかげで、設計を見直したあと、元ファイルを置き直さなくても作り直せます。

直したいときにどれを触るか

やりたいこと	触るもの	操作
項目の名前・単位・数値かどうかを直す	仕様	「設計を見直す」ボタン
ID の作り方を変える	仕様	「設計を見直す」ボタン
使っていない列を足す	仕様	「設計を見直す」ボタン
探すときの言葉を足す	検索タグ	「設計を見直す」ボタン
変換ルールを直接直す	—	しません（仕様から作り直されます）

項目の名前・単位だけを直したときは、保存するとデータを作り直さずに書き換わります（公開済みの ID を開いたページの項目名は、見直しの「ためす」の画面で「項目名の公開を更新する」ボタンを押すと変わります。datasets.md）。それ以外は、直したあとに取り込みからやり直します。公開済みのデータは、新しい下書きができるまで置き換わらないので、その間も質問には答えられます。

過去の版 v0.7.0 (2026-07-14) で追加

設計を見直すたび、その時点のファイル一式が履歴として残ります。「いつ・何が変わったのか」は、詳細画面の技術情報から差分として確認できます。