sorane は Open Knowledge Format (OKF) v0.1 を実装します。各ページの frontmatter に profile: sorane-okf/<version> を書き、JSON Schema で検証します。
サポートする concept 型#
| type | 用途 | catalog.jsonld |
|---|---|---|
article | ブログ記事・ドキュメント | hasPart（BlogPosting / TechArticle） |
index | サイトトップ | （カタログに含めない） |
dataset | オープンデータのランディング | dataset（Dataset + distribution） |
reference | コード一覧・仕様参照 | hasPart（TechArticle） |
glossary | 分野別用語集（1 ファイル複数語） | hasPart（DefinedTermSet） |
faq | Q&A ページ | hasPart（FAQPage） |
すべての型で type と title が必須です。
dataset では次も必須です: description, resource, license, publisher, distributions（各要素に title, format, accessURL）。
任意の theme は DCAT-AP の EU コード（GOVE, ECON, HEAL など）を推奨します。コード形式で未知の値は sorane validate が warning を出します。自由なタグ文字列も許容されます。
content/datasets/ のようにサブディレクトリにページが 2 件以上あり、作者の index.md が無い場合、ビルドは OKF 形式のディレクトリ一覧（{dir}/index.html と okf/bundle.tar.gz 内の {dir}/index.md）を自動生成します。サイトトップの content/index.md（type: index）とは別物です。
プロファイル文字列#
frontmatter の profile で、検証の厳しさと使える type を選びます。
profile | 使える type | 未知の type | AI 開示フィールド |
|---|---|---|---|
sorane-okf/0.1 | article, index | error | 任意（形状は緩い） |
sorane-okf/0.2 | article, index | error | 厳密検証（AI 開示） |
sorane-okf/0.3 | 上表の 7 型 | warning（ビルドは article 扱い） | 厳密検証 |
新規サイトは用途に応じて sorane-okf/0.3（拡張型・オープンデータ）または sorane-okf/0.2（記事のみ + AI 開示）を選ぶのが一般的です。既存サイトは migrate --bump-profile で上げられます。
sorane.yaml の okf.default_profile でサイト全体の既定プロファイルを指定できます（各ページの profile: は省略可能）。okf.unknown_type で 0.3 の未知 type を warn（既定）か error に切り替えられます。詳細は 設定 を参照してください。
npx @sorane/cli migrate --cwd . --bump-profile 0.3
記事の例#
---
type: article
title: Hello OKF
timestamp: 2025-01-01T00:00:00Z
tags: [sorane]
profile: sorane-okf/0.3
---
本文（Markdown）
データセットの例#
---
type: dataset
title: Transit Stops
description: Bus stop coordinates.
resource: https://example.dev/datasets/transit-stops
license: CC-BY-4.0
profile: sorane-okf/0.3
publisher:
name: Example Org
url: https://example.dev
distributions:
- title: Stops CSV
format: csv
accessURL: static/stops.csv
---
本文（データの説明・更新履歴など）
実例: examples/open-data/（README に全ページ一覧と index / search の手順）
用語集・FAQ の例#
glossary と faq は本文で ## 見出しごとに用語・質問を書きます。アンカー {#id} を付けるとページ内リンクと JSON-LD の term id に使えます。
## 分散 {#variance}
標本の二乗偏差の平均。
glossary は frontmatter の terms: リストでも定義できます（本文の ## がある場合は本文を優先）。
単一用語ページ（glossary-term）#
1 語 1 ファイルで transclusion や深いリンク向けです。term_id と親用語集 inDefinedTermSet（または glossary）を推奨します。2 件以上あると glossary/terms/index.html にタグ一覧風の索引が自動生成されます。
---
type: glossary-term
title: Distribution
term_id: distribution
inDefinedTermSet: glossary.html
profile: sorane-okf/0.3
---
A downloadable representation of a dataset.
出力 HTML のパスは permalink の {{slug}} 規則に従います（content/glossary/terms/distribution.md → distribution.html）。
参照（reference）の例#
コード一覧や CSV 列定義向けです。resource に元データや仕様書の URI を書き、本文は GFM 表が一般的です。
---
type: reference
title: Stops CSV Fields
description: Column definitions for stops.csv
resource: https://example.dev/static/stops.csv
profile: sorane-okf/0.3
---
| Column | Type | Description |
|--------|------|-------------|
| stop_id | string | Unique stop id |
検索インデックスは doc_type（frontmatter の type）で絞り込めます。dataset には license: / theme: / format: タグが付与され、sorane search --tag format:csv のように検索できます。
ビルド出力#
| パス | 内容 |
|---|---|
*.html | 人間向けページ |
*.md | OKF ネイティブ代替ソース |
catalog.jsonld | schema.org カタログ（dataset[] と hasPart[] を分離） |
catalog-dcat.jsonld | DCAT-AP JSON-LD（type: dataset のみ、opt-in） |
| （運用） | Open Data Portal 連携 — CKAN / data.europa.eu |
llms.txt | LLM 向けサイトガイド |
okf/bundle.tar.gz | {type}/{slug}.md のバンドル |
JSON Schema#
| プロファイル | スキーマ |
|---|---|
sorane-okf/0.1 | sorane-okf-0.1.schema.json |
sorane-okf/0.2 | sorane-okf-0.2.schema.json |
sorane-okf/0.3 | sorane-okf-0.3.schema.json |
$id は本番 URL ssg.sorane.dev を指します。