用語集

非公式翻訳 (Unofficial translation). これはデータパッケージスタンダードの有志による日本語訳です。正典は英語原典 datapackage.org 。未訳の箇所は英語の原文を参照してください。

著者	Rufus Pollock, Paul Walsh, Adam Kariv, Evgeny Karev, Peter Desmet, Data Package Working Group

データパッケージスタンダードで用いられる用語の用語集。

言語

本書のキーワード MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、OPTIONAL は、RFC 2119 に記述されたとおりに解釈される。

定義

プロファイル

プロファイルとは、次を満たさなければならない (MUST) URL である:

draft-07 バージョンの有効な JSON Schema ディスクリプタ(descriptor)に解決される
バージョン管理され不変であること。すなわち、あるバージョンで公開されたら変更できない

プロファイルは、メタデータのバージョン識別子として、また、ディスクリプタがルートレベルの $schema プロパティとして持つ JSON Schema の所在として、その両方の役割を果たす。ディスクリプタはその JSON Schema に対して妥当でなければならず (MUST)、検証されなければならない (MUST)。

JSON Schema と同様に、$schema プロパティはディスクリプタのルートレベルでのみ効果を持つ。例えば、Table Dialect がファイルとして公開される場合、その検証に影響する $schema プロパティを含めることができる。同じ dialect がデータパッケージのディスクリプタにインライン展開されたオブジェクトである場合、その dialect の $schema プロパティは無視されなければならず (MUST)、ディスクリプタ全体はパッケージが提供するルートレベルの $schema プロパティに対して検証されなければならない (MUST)。

データパッケージスタンダードは、Extensions 仕様のとおり、拡張を作成する仕組みとしてプロファイルを採用している。

ディスクリプタ

データパッケージスタンダードでは、データパッケージやテーブルスキーマといったコア仕様に従って定義されたメタデータを表現するために、ディスクリプタ という概念を用いる。

論理レベルでは、ディスクリプタはデータ構造で表現される。そのデータ構造は、RFC 4627 で定義される JSON の object でなければならない (MUST)。

物理レベルでは、ディスクリプタはファイルで表現される。そのファイルは、RFC 4627 で定義される妥当な JSON の object を含まなければならない (MUST)。

本仕様は、いかなる発見可能性(discoverability)の仕組みも定義しない。ディスクリプタを含むファイルを直接参照するために、任意の URI を使用できる。

カスタムプロパティ

データパッケージ仕様は、使用される標準プロパティの集合を定義しつつ、カスタムプロパティの追加を許している。カスタムプロパティには namespace:property という命名規約を用いることが推奨される (RECOMMENDED)。また、カスタムプロパティの命名には lower camel case 規約を用いることが推奨される (RECOMMENDED)。例: namespace:propertyName。

仕様への準拠は、仕様で定められていない追加のプロパティを使用できないことを意味しない。ディスクリプタは、必須・任意として記述されたプロパティに加えて、任意の数のプロパティを含んでもよい (MAY)。例えば、時系列データを格納していて、そのデータパッケージにデータの時間的範囲を記載したい場合、temporal プロパティを追加できる(cf. Dublin Core):

{
  "dc:temporal": {
    "name": "19th Century",
    "start": "1800-01-01",
    "end": "1899-12-31"
  }
}

この柔軟性により、特定のコミュニティは自分たちが扱うデータに適した形でデータパッケージを拡張できる。一例として、Fiscal Data Package 仕様は、財政データの公開・利用のためにデータパッケージを拡張している。

URL またはパス

URL or Path は、次の追加制約を持つ string である:

URL または POSIX パスのいずれかでなければならない (MUST)
URL は完全修飾でなければならない (MUST)。http、https、ftp、ftps のいずれかのスキームを使用しなければならない (MUST)。(スキームが無い場合は POSIX パスでなければならない (MUST))
POSIX パス(/ を区切りとする unix 形式)はローカルファイルの参照に使用できるが、セキュリティ上の制約として、ディスクリプタの相対的な兄弟またはその子でなければならない (MUST)。絶対パス /、相対親パス ../、ドットで始まる隠しフォルダ .hidden は使用してはならない (MUST NOT)。

完全修飾 URL の例:

{
  "path": "http://ex.datapackages.org/big-csv/my-big.csv"
}

ディスク上の相対パスとしてもオンラインでも動作する相対パスの例:

{
  "path": "my-data-directory/my-csv.csv"
}

/(絶対パス)と ../(相対親パス)は、データパッケージソフトウェアを実装する際のセキュリティ脆弱性を避けるために禁止されている。リソースの path に対するこれらの制限は、リソースパスがデータパッケージのディレクトリとそのサブディレクトリ内のファイルのみを指すことを保証する。これにより、悪意あるユーザーがデータパッケージソフトウェアを悪用して、意図しない機微情報へアクセスすることを防ぐ。例えば、データパッケージのホスティングサービスがパッケージをディスクに保存し、API 経由でアクセスを許可しているとする。悪意あるユーザーが /etc/passwd のようなリソースパスを持つデータパッケージをアップロードする。続いてそのリソースのデータを要求すると、サーバーは何も考えずに /etc/passwd を開き、そのデータを呼び出し元に返してしまう。

表形式データ

表形式データは、行の集合からなる。各行はフィールド(列)の集合を持つ。通常、各行は同じフィールドの集合を持つと期待されるため、テーブル全体に共通するフィールドについて語ることができる。

スプレッドシートや CSV ファイルのテーブルでは、最初の行をヘッダー行と解釈し、フィールドの名前を与えることが多い。一方で、SQL データベースのテーブルなど他の状況では、フィールド名は明示的に指定される。

例として、典型的なスプレッドシートのテーブルを示す:

field     field
  |         |
  |         |
  V         V

 A     |    B    |    C    |    D      <--- Row (Header)
 ------------------------------------
 valA  |   valB  |  valC   |   valD    <--- Row
 ...

JSON では、テーブルは次のようになる:

[
  { "A": value, "B": value, ... },
  { "A": value, "B": value, ... },
  ...
]

データ表現

テキストベースのソースからの表形式データの表現と処理について語るには、データの物理表現と論理表現という概念を導入すると便利である。

データの物理表現とは、ディスク上のテキストとしてのデータの表現を指す。例えば CSV や JSON ファイルである。この表現は、ある程度の型情報を持つ場合(JSON。JSON がサポートする基本型が使える)もあれば、持たない場合(CSV。すべてのデータが文字列形式で表現される)もある。

データの論理表現とは、仕様で定義される基本型・データ構造・関係の観点での、データの「理想的な」表現を指す。仕様とは、データの論理表現に関するものであり、また物理表現を論理表現へ変換する方法に関するものでもある、と言える。

本書では、曖昧さを防ぐ必要がある箇所、特に実装者にとって曖昧さを防ぐ必要がある箇所で、物理表現か論理表現かを明示的に示す。

例えば、constraints はデータの論理表現に対してテストされるべきである (SHOULD) 一方、missingValues のようなプロパティはデータの物理表現に適用される。