More than 5 years have passed since last update.

@kyoh86in

株式会社WACUL

今更ながらJSON Schema Core draft 4.0を日本語訳してみた

Last updated at 2017-01-27Posted at 2017-01-22

JSON SchemaのRFCを読むのが苦痛すぎるので、日本語訳をしてみる。

当翻訳文書上の注意

著作権は原文書に帰属します。
訳者の注についてはカッコ付き斜体で_（訳注：このように）_表記します。
意図的・偶発的問わずtypoについては本来の語を推定し、その箇所には訳注を入れています。
英語力が低いので、あちこち誤訳がありそうです。編集リクエスト待ってます。

以下訳文

JSON Schema：JSONドキュメント定義のためのメディアタイプ

概要

JSON Schemaは、JSONデータの構造を記述するための application/schema+jsonメディアタイプを定義します。JSON Schemaの記述自体もJSONで形式で行われます。
JSON Schemaは、JSONドキュメントがどのように見えるか、情報をどのように抽出すればよいか、そしてその情報をどのようにやりとりするかを宣言します。他にハイパーメディアコントロールや機械的可読性を持たない、既存のAPIに注釈をつけるのに理想的です。

読者への注意

このドラフトのIssueリストは <https://github.com/json-schema-org/json-schema-spec/issues> にあります。
追加情報については <http://json-schema.org> を参照してください。
フィードバックは前述のIssueリスト、ホームページに記載された連絡先、または著者にメールでお知らせください。

この文書のステータス

このInternet Draftは、BCP78およびBCP79の規定に完全に準拠して提出されています。

インターネットドラフトは、インターネットエンジニアリングタスクフォース（IETF）の作業文書です。他のグループがインターネットドラフトとして作業文書を配布することもできることに注意してください。現在のインターネットドラフトのリストはhttp://datatracker.ietf.org/drafts/current/にあります。

インターネットドラフトは、最大6か月間有効なドラフト文書であり、いつでも他の文書によって更新、置き換え、または廃止される可能性があります。参考資料としてインターネットドラフトを使用したり、「進行中の作業」以外のものを引用することは不適切です。

このインターネットドラフトは2017年4月16日に期限切れになります。

著作権

（訳注：略。原文参照のこと）

1. はじめに

JSON Schemaは、JSONデータの構造を定義するためのJSONメディアタイプです。JSON Schemaは、JSONデータのバリデーション、ドキュメンテーション、ハイパーリンクのナビゲーション、相互作用の制御を定義することを目的としています。

この仕様では、JSON referenceによる外部JSON Schemaへの参照と参照解決 （訳注：dereferencing） 、JSON Schemaで使用される vocabulary の明確化、および schema に対するインスタンスの処理に必要な最小機能の宣言といった、JSON Schema Coreの用語とメカニズムを定義しています。

バリデーション、リンク、アノテーション、ナビゲーション、相互作用に関する宣言のための vocabulary は、他の仕様で記述しています。

2.表記と用語

この文書内の"MUST" "MUST NOT" "REQUIRED" "SHALL" "SHALL NOT" "SHOULD" "SHOULD NOT" "RECOMMENDED" "MAY" "OPTIONAL"といったキーワードは、RFC 2119に沿って解釈しなくてはなりません。

同様に、この文書内の"JSON", "JSON text", "JSON value", "member", "element", "object", "array", "number", "string", "boolean", "true", "false", "null"といったキーワードは、RFC 7159に沿って解釈しなくてはなりません。

3.概要

このドキュメントでは、JSONデータを記述するためのJSON Schemaを識別する新しいメディアタイプ "application / schema + json"を提案しています。JSON Schema自体はJSONで記述されています。当仕様と、関連する仕様でもって、define keywords allowing to describe this data in terms of allowable values, textual descriptions and interpreting relations with other resources. このセクションでは、関連する仕様で定義されている機能の概要を示します。

3.1. バリデーション

JSON Schemaは、JSONドキュメントの構造（必要なプロパティや長さの制限など）を記述します。アプリケーションは、この情報を使用してインスタンスを検証（制約が満たされていることを確認）したり、制約を満たしたユーザー入力をインターフェイスに送信することができます。

バリデーションの動作とキーワードは、別の文書 json-schema-validation で定義しています。

3.2. ハイパーメディアとリンク

JSON Hyper-Schema は、JSONドキュメントのハイパーテキスト構造を定義します。これには、インスタンスから他のリソースへのリンク関係、インスタンスのマルチメディアデータとしての解釈、およびAPIの使用に必要な送信データの定義が含まれます。

JSON Hyper-Schemaの動作やキーワードは、別の文書 json-hyper-schema で定義しています。

4.定義

4.1. JSONドキュメント

JSONドキュメントは、application/jsonメディアタイプで記述された情報リソース（バイト列）です。

JSON Schemaでは、定義されているデータモデルにより、"JSON document", "JSON text", "JSON value" という語には互換性があります。

4.2. インスタンス

JSON Schemaは、データモデルに従ってドキュメントを解釈 （訳注：interperts、おそらく「interprets」のtypo） します。このデータモデルによって解釈 （訳注：interperted、おそらく「interpreted」のtypo） されたJSON valueは、「インスタンス」と呼ばれます。

インスタンスには、6つのプリミティブ型のいずれか、および型に応じて持ちうる値の制限があります。

null: JSON の null 表現
boolean: JSON の true, false 表現による真偽値
object: JSON のオブジェクト表現による、文字列をインスタンスにマッピングする際にプロパティの順序が決められていない集合
array: JSON の配列表現による、インスタンスの順序付きリスト
number: JSON の数値表現による、任意精度の10進数の値
string: JSON の文字列表現による、Unicodeコードポイントの文字列

したがって、空白とフォーマットに関しては JSON Schema 定めるところではありません。

オブジェクトは同じキーを持つ2つのプロパティを持つことができないため、単一のオブジェクト内に同じキー（"文字列"表現による）を持つ2つのプロパティ（"メンバ"表現）を定義しようとした場合の、JSON documentの動作は定義されていません。

4.3. インスタンスの等価性

2つのJSONインスタンスは、同じ型で、データモデルに応じた同じ値を持つ場合に限り、等しいとされます。具体的には、

どちらもnull
どちらも真
どちらも偽
どちらも文字列であり、同じコードポイントの羅列
どちらも数であり、同じ数学的値を有する
どちらも配列であり、各項目の値と順序が等しい
どちらもオブジェクトであり、一方の各プロパティがもう一方の各プロパティとキー・値で完全に一致する

この定義により、配列の長さは同じでなければならず、オブジェクトのメンバー数も同じでなければなりません。一方で、オブジェクトのプロパティの順序については問わず、同じキーで複数のプロパティを定義する方法はなく、単なる書式の違い（インデント、カンマ、末尾のゼロなど）は重要ではありません。

4.4. JSON Schemaドキュメント

JSON Schema document（または単にスキーマ）は、インスタンスを記述するために使用されるJSON documentです。スキーマ自体がインスタンスとして解釈されます。JSON Schemaはオブジェクトでなければなりません。

インスタンスを記述するために使用されるプロパティは、キーワードまたはスキーマキーワードと呼ばれます。プロパティの意味は、スキーマが使用しているvocabulary によって指定されます。

JSON Schemaには、スキーマのキーワードではないプロパティが含まれる場合があります。未知のキーワードを無視すべきです（SHOULD）。

スキーマ自体を定義するスキーマは、メタスキーマ （訳注：meta-schema） と呼ばれます。メタスキーマは、JSON Schemaを検証し、スキーマ内で使用している vocabulary を仕様化するために使用されます。

空のスキーマは、プロパティを持たないJSON Schemaです。

4.5. ルートスキーマとサブスキーマ

ルートスキーマは、対象のJSONドキュメント全体を構成するスキーマです。

一部のキーワードはスキーマ自体を取り、JSON Schemaをネストすることができます。

{
    "title": "root",
    "items": {
        "title": "array item"
    }
}

この例のドキュメントでは、「配列アイテム」というスキーマはサブスキーマであり、「ルート」というスキーマはルートスキーマです。

5. 一般的な考慮事項

5.1. JSON値

インスタンスは、RFC7159に定める任意の有効なJSON値を取ることができます。JSON Schemaは、JSONのあらゆる型を記述することができ、例えばnullを含むJSON値を記述できます。

5.2. 言語独立性

JSON Schemaはプログラミング言語によらず、データモデルで説明されているすべての値をサポートしています。ただし、一部の言語やJSONパーサーでは、JSONで記述できる値のすべての範囲をメモリで表現できない場合があることに注意してください。

5.3. 整数

いくつかのプログラミング言語とパーサは、浮動小数点数に対して整数とは異なる内部表現を使用します。

一貫性のため （訳注：For constistency、おそらくFor consistencyのtypo） 、整数のJSON numberを小数でエンコードするべきではありません（SHOULD NOT）。

5.4. JSON Schemaの拡張

実装においては、JSON Schemaに追加のキーワードを定義することができます。明示的な合意がある場合を除いて、スキーマ作成者はこれらの追加のキーワードがピア実装によるサポートを期待してはいけません。実装は、サポートしていないキーワードについては無視すべきです（SHOULD）。

JSON Schemaへの拡張の作成者は、「allOf」を使用して既存のメタスキーマを拡張して、独自のメタスキーマを作成することをお勧めします。この拡張されたメタスキーマは、ツールでJSON documentを正しく解釈するために、"$schema"キーワードを使って参照されるべきです（SHOULD）。

6. `$schema` キーワード

6.1. 目的

$schema キーワードは、JSON Schemaのバージョン識別子として、またその特定のバージョンを定義するスキーマを記述した JSON Schema リソースの場所として解釈されます。

JSON Schemaドキュメントのルートスキーマは、このプロパティを記述すべきです（SHOULD）。このキーワードの値は、RFC3986に定義される絶対URIであり、正規化されていなければなりません。そしてスキーマ自体は、このURIによって識別されるメタスキーマに対して有効でなければなりません（MUST）。

このプロパティの値は、他のドキュメントや他の人に定義されています。JSON Schemaの実装では、JSON Schemaの現在の草案とそれ以前に公開された草案の妥当性を考慮してサポートを実装するべきです（SHOULD）。

7. `$ref` を使用したスキーマの参照

サブスキーマの中ではどこでも、 $ref プロパティを含むオブジェクトを記述することができます。 $refの値はURI参照です。現在のURIをベースとして解決され、使用するスキーマのURIを提示します。 $ref を含むオブジェクトの、他のすべてのプロパティは無視しなければなりません（MUST）。

URIは具体的なネットワーク上の位置を示すものではなく、識別子です。ネットワーク上のアドレス指定可能なURLであったからといって、スキーマはそのアドレスからダウンロード可能である必要はなく、実装においては、ネットワーク上のアドレス可能なURIに対してネットワークからのダウンロードなどの操作をすべきと捉えてはなりません（SHOULD NOT）。

スキーマを無限ループにしてはならない（MUST NOT）。たとえば、2つのスキーマ "#alice" と "#bob" がお互いに "allOf" プロパティーでもって参照しあっている場合、安易なValidatorではインスタンスを検証しようとして、無限再帰的ループに陥る可能性があります。スキーマは、このような無限の再帰的ネストを使用してはなりません（SHOULD NOT）。使用した場合の振る舞いは未定義です。

8.ベースURIと参照解決（訳注：dereferencing）

8.1. Initial base URI

RFC3986 Section 5.1defines how to determine the default base URI of a document.

Informatively, the initial base URI of a schema is the URI it was found at, or a suitable substitute URI if none is known.

（訳注：このセクションで言っていることが全くわからない。ルートのidキーワードが必要な中で、initial　base URIを定める必要性がよくわからない。訳者が盛大に勘違いしている可能性あり）

8.2. `id` キーワード

idキーワードは、スキーマのURIと、スキーマ内の他のURI参照が解決されるベースURIを定義します。idキーワード自体は、オブジェクト全体のベースURIに対して解決されます。

このキーワードの値は、文字列でなければなりませんし、RFC3986に定められた有効なURIでなければなりません。さらにこの値は正規化されるべきであり（SHOULD NOT）、空のフラグメント "#" または空の文字列 "" であるべきではありません（SHOULD NOT）。

JSON Schema ドキュメントのルートスキーマには、絶対URI（スキームを含むが、フラグメントは含まない）を持つ id キーワードが必要です（SHOULD）。

JSON Schemaドキュメント内のサブスキーマに名前を付けるために、id を使用してドキュメントローカルの識別子を定義することができます。この形式の "id"キーワードは、フラグメントURI参照であることを示す # に続けてアルファベット（[A-Za-z]）、続けて任意の数のアルファベット（[A-Za-z]）、数字（[0-9]）、ハイフン（-）、アンダースコア（-）、コロン（:）、またはピリオド（.）の羅列で記述されなくてはなりません（MUST）。

{
    "id": "http://example.com/root.json",
    "definitions": {
        "A": { "id": "#foo" },
        "B": {
            "id": "other.json",
            "definitions": {
                "X": { "id": "#bar" },
                "Y": { "id": "t/inner.json" }
            }
        },
        "C": {
            "id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
        }
    }
}

上記の例における各スキーマはそれぞれ以下に示すように、ルートスキーマからの相対的なJSON Pointer(RFC6901)と　base　URI を持ち、どちらでも一意に識別できます。

(document root)
- http://example.com/root.json#
#/definitions/A
- http://example.com/root.json#foo
#/definitions/B
- http://example.com/other.json
#/definitions/B/definitions/X
- http://example.com/other.json#bar
#/definitions/B/definitions/Y
- http://example.com/t/inner.json
#/definitions/C
- urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f

8.2.1. 内部参照

スキーマは、JSON Pointer やidで直接指定されたURIなど、与えられたURIによって一意に識別できます。

実装 （訳注：Tools） は、スキーマ自身がidプロパティで提供しているURIを記憶しなくてはなりません（SHOULD）。これは「内部参照」と呼ばれます。

例として、次のスキーマを考えます。

{
    "id": "http://example.net/root.json",
    "items": {
        "type": "array",
        "items": { "$ref": "#item" }
    },
    "definitions": {
        "single": {
            "id": "#item",
            "type": "integer"
        },
    }
}

実装が #/definitions/single スキーマを見つけた時、その時点でのbase URIに対する id のURI参照を解決して http://example.net/root.json#item という形にします。
また、実装が#/items スキーマの中を見ようとすると #item 参照にぶつかりますが、これは http://example.net/root.json#item と解決され、同じドキュメント内の他の場所で定義されたスキーマを指すものとして扱われます。

8.2.2. 外部参照

スキーマはURIで識別されます。前述の通り、URIは必ずしも何かがダウンロードされることを意味するものではありませんが、JSON Schemaの実装は、それらを識別するURIを含め、使用するスキーマをすでに理解しているべきです（SHOULD）。

実装は、任意のURIを任意のスキーマに関連付けることを許すべきで（SHOULD）、かつスキーマのidに自動的に与えられたURIを関連付けられるべきです（SHOULD）。

スキーマは複数のURIを持つ可能性がありますが、URIが複数のスキーマを持つ方法はありません。複数のスキーマが同じURIで存在する場合、バリデータはエラーを発生させるべきです（SHOULD）。

9. ハイパーメディアの使用

JSONの最も利用されるシーンの一つは、自動化されたAPIとロボットのための、HTTPサーバーです。このセクションでは、メディアタイプとWeb linking(RFC5988)をサポートするプロトコルにおいて、よりRESTfulなやり方でJSON documentsの処理を拡充する方法について記述します。

9.1. スキーマへのリンク

特定のスキーマに沿って書かれたインスタンスには、"describedby" link (W3C.REC-ldp-20150226) によってダウンロード可能なJSON Schemaへのリンクを記述することが推奨されています（RECOMMENDED）。
HTTPでは、そのようなリンクをレスポンスに Link header [RFC5988] で付与できます。ヘッダの例は以下のとおりです。

Link: <http://example.com/my-hyper-schema#>; rel="describedby"

9.2. JSONプロファイルの記述

The 'profile' Link Relation ([RFC6906]) で説明されているように、インスタンスはプロファイルを指定することができます。メディアタイプのパラメータとして使用すると、HTTPサーバはプロファイルに基づいてContent-Type Negotiationを実行できます。media-typeパラメタは空白で区切られたURIのリストでなければなりません（MUST）（すなわち、相対参照は無効です）。

プロファイルURIは透過ではないため、自動的に参照解決してはなりません（SHOULD NOT）。実装が提供されたプロファイルのセマンティクスを理解していない場合、その実装は代わりに、プロファイルの処理方法に関する情報を提供する「describedby」リンクに従うことができます。「プロファイル」は必ずしもネットワークの場所を指しているわけではないので、ダウンロード可能なスキーマへのリンクには "describedby"関係が使用されます。ただしシンプルにするために、スキーマの作成者は、可能であればこれらのURIを同じリソースを指すようにする必要があります。

HTTPでは、media-typeパラメーターはContent-Typeヘッダー内に送信されます。

Content-Type: application/json; profile="http://example.com/my-hyper-schema#"

複数のプロファイルは空白区切りで指定します。

Content-Type: application/json; profile="http://example.com/alice http://example.com/bob"

HTTPは、プロファイルをリンクでも送ることができますが、media-type パラメータを完全に置き換えてしまう場合、media-typeセマンティクスとContent-Type Negotiationに影響します。

Link: </alice>;rel="profile", </bob>;rel="profile"

9.3. HTTPでの使用

ネットワーク上のハイパーメディアシステムのために使う場合、スキーマのやりとりにはHTTPがよく選ばれます。無作法なクライアントは、キャッシュ可能な長い時間が設けられているときでも、必要以上にネットワーク越しにスキーマの取得を繰り返し、サーバー管理者に問題を引き起こすことがあります。
HTTPサーバーはJSON Schemaが長期間キャッシュされるヘッダーを設定すべきです（SHOULD）。HTTPクライアントは、キャッシュヘッダーを解釈し、キャッシュが利用可能な期間内に文書を再要求しないようにするべきです（SHOULD）。分散システムは共有キャッシュやキャッシングプロキシを使用するべきです（SHOULD）。

クライアントは、JSON Schema実装またはソフトウェアに固有のUser-Agentヘッダーを設定または追加してください（SHOULD）。シンボルは重要度の高い順に並べられているため、JSONスキーマライブラリの名前/バージョンが最初に記述され、より一般的なHTTPライブラリ名（存在する場合）が記述されます。

例：

User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0

クライアントは、Fromヘッダーを付けてリクエストするべきであり（SHOULD）、サーバーオペレータが誤っている可能性のあるスクリプトの所有者に連絡できるようにする必要があります（SHOULD）。

10. セキュリティに関する考慮事項

スキーマとインスタンスはどちらもJSON値です。ですから、[RFC7159]に定められた、JSON valueにおけるセキュリティ上の考慮はスキーマやインスタンスにおいても適用されます。

インスタンスとスキーマは、たびたび信頼できない第三者によってパブリックインターネットサーバー上に公開されます。バリデータは、スキーマの解析に過度のシステムリソースを消費しないよう、注意する必要があります。バリデーターが無限ループに陥ってはなりません（MUST NOT）。

サーバーは、悪意のある人物が既存のスキーマや非常によく似たIDを持つスキーマをアップロードすることで、既存のスキーマの機能を変えてしまうことがないよう、考慮する必要があります。

個別のJSON Schema vocabulary は、独自のセキュリティの考慮事項も持つことになります。詳細については、それぞれの仕様を参照してください。

11. IANA の考慮事項

JSONスキーマのMIMEメディアタイプは、次のように定義・提案されています。

タイプ名: application
サブタイプ名: schema+json

12. 参考文献

12.1. 標準に関する参考文献

[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC3986]	Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.
[RFC7159]	Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014.
[W3C.REC-ldp-20150226]	Speicher, S., Arwe, J. and A. Malhotra, "Linked Data Platform 1.0", World Wide Web Consortium Recommendation REC-ldp-20150226, February 2015.

12.2. その他の参考文献

[RFC5988]	Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010.
[RFC6901]	Bryan, P., Zyp, K. and M. Nottingham, "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013.
[RFC6906]	Wilde, E., "The 'profile' Link Relation Type", RFC 6906, DOI 10.17487/RFC6906, March 2013.
[RFC7231]	Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014.
[json-schema-validation]	Wright, A. and G. Luff, "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", Internet-Draft draft-wright-json-schema-validation-00, October 2016.
[json-hyper-schema]	Wright, A. and G. Luff, "JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON", Internet-Draft draft-wright-json-schema-hyperschema-00, October 2016.

付録A. 謝辞

（訳注：略。原文参照のこと）

付録B. 変更履歴

（訳注：略。原文参照のこと）

著者

（訳注：略。原文参照のこと）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

今更ながらJSON Schema Core draft 4.0を日本語訳してみた

当翻訳文書上の注意

以下訳文

JSON Schema：JSONドキュメント定義のためのメディアタイプ

概要

読者への注意

この文書のステータス

著作権

目次

1. はじめに

2.表記と用語

3.概要

3.1. バリデーション

3.2. ハイパーメディアとリンク

4.定義

4.1. JSONドキュメント

4.2. インスタンス

4.3. インスタンスの等価性

4.4. JSON Schemaドキュメント

4.5. ルートスキーマとサブスキーマ

5. 一般的な考慮事項

5.1. JSON値

5.2. 言語独立性

5.3. 整数

5.4. JSON Schemaの拡張

6. $schema キーワード

6.1. 目的

7. $ref を使用したスキーマの参照

8.ベースURIと参照解決 （訳注：dereferencing）

8.1. Initial base URI

8.2. id キーワード

(document root)

8.2.1. 内部参照

8.2.2. 外部参照

9. ハイパーメディアの使用

9.1. スキーマへのリンク

9.2. JSONプロファイルの記述

9.3. HTTPでの使用

10. セキュリティに関する考慮事項

11. IANA の考慮事項

12. 参考文献

12.1. 標準に関する参考文献

12.2. その他の参考文献

付録A. 謝辞

付録B. 変更履歴

著者

6. `$schema` キーワード

7. `$ref` を使用したスキーマの参照

8.ベースURIと参照解決（訳注：dereferencing）

8.2. `id` キーワード