JSON シリアル化ルール (ADO.NET Data Services フレームワーク)

ADO.NET Data Services で使用される JSON 形式には、サービスによってアクセス可能なすべてのリソースに適用されるデータをシリアル化するためのプロトコルが含まれています。

すべてのリソースに共通のシリアル化ルール

このトピックでは、ADO.NET Data Services ですべてのリソースに共通のシリアル化ルールを示します。

[!メモ]

JSON 形式との間で変換されるライブラリを使用すると、シリアル化の複雑さを大幅に軽減できます。詳細については、「CodePlex」を参照してください。

null 値

すべての null 値は、JSON のリテラル "null" を使用して表す必要があります。

エンティティ セット

• エンティティ セットは JSON オブジェクトの配列として表す必要があります。セット内にはエンティティ型ごとに 1 つのオブジェクトがあります。

• 空のエンティティ セットは、要素がゼロの空の JSON 配列として表す必要があります。

エンティティ型

• エンティティ型は JSON オブジェクトとしてシリアル化する必要があります。

• この型に関する各プロパティは、オブジェクト内で名前/値のペアとして表す必要があります。名前/値のペアの名前はプロパティ名で、ペアの値はプロパティの値です。オブジェクト内でのプロパティの順序は重要ではありません。

• エンティティ型インスタンスの JSON シリアル化には __metadata という名前のプロパティを含める必要があります。このプロパティはデータではありませんが、特定の型のインスタンスのメタデータを指定するためにこのプロトコルで定義された規則です。__metadata プロパティの値には、uri と type の 2 つのプロパティが含まれます。uri プロパティは、現在のエンティティ型インスタンスを指定する URI である必要があります。具体的には、URI は、空ではない最後のパス セグメントを削除した後の要求側 URI を基準としている必要があります。'Type' プロパティの値は、namespaceName.typeName のように、サーバー上のエンティティ型インスタンスを表す型の名前空間修飾名である必要があります。__metadata プロパティには etag プロパティが含まれる場合があります。エンティティで etag プロパティが定義されている場合は、etag プロパティが存在しなければなりません。

  • JSON オブジェクトによって表されるエンティティ型が継承階層の一部である場合は、Type プロパティを含める必要があります。それ以外の場合は 'Type' プロパティは省略可能です。

  • URI パラメータと type パラメータが必要である場合、省略可能である場合、および不要である場合の詳細については、「一般的な HTTP 要件」を参照してください。

複合型

• 複合型は JSON オブジェクトとしてシリアル化する必要があります。

• 複合型の各プロパティは、JSON オブジェクト内で名前/値のペアとして表す必要があります。名前/値のペアの名前はプロパティ名で、ペアの値はプロパティの値です。オブジェクト内でのプロパティの順序は重要ではありません。

ナビゲーション プロパティとリンク プロパティ

• ナビゲーション プロパティとリンク プロパティのシリアル化は、既定では遅延されます。コンテンツが遅延されると、__deferred 要素の下の uri プロパティには正規の URI は含まれません。プロパティを展開する方法の詳細については、「遅延コンテンツ (JSON)」を参照してください。

• ナビゲーション プロパティとリンク プロパティは関連するエンティティ セットへの関連付けを表すため、ナビゲーション プロパティのシリアル化では、次の例外を除き、エンティティ セットと同じルールに従います。

  • 最上位レベルの XML 要素は、エンティティ セット名ではなくナビゲーション プロパティまたはリンク プロパティの名前と一致する必要があります。

プロパティ

プロパティは、ラッピング マークアップのある形式、またはラッピング マークアップのない修飾されていない形式を使用する 2 とおりの方法でシリアル化できます。

ラッピング マークアップのある JSON 形式へのプロパティのシリアル化を使用するには、次の手順に従います。

• JSON オブジェクト内では、シリアル化は {<propertyname>:<propertyvalue>} のように名前/値のペアとして表されます。

• このドキュメントの表には、エンティティ データ モデル (EDM) によって定義された各プリミティブ型の JSON を使用した書式設定方法を示しています。JSON シリアル化の列では、プロパティ値のシリアル化方法が定義されます。

ラッピング マークアップなしの JSON 形式 (/$value で終わる URI) へのプロパティのシリアル化を使用するには、次の手順に従います。

• この形式では、プロパティの値のみがシリアル化されます。次の表の JSON シリアル化の列では、各プリミティブ型をこの形式でシリアル化する方法を示しています。

• 型の値が null または空の場合、この形式ではプロパティの値のシリアル化はありません。その場合、プロトコルの対話モデルによりそのような値の存在が示される必要があります。

参照

概念

JSON 形式 (ADO.NET Data Services フレームワーク)
遅延コンテンツ (JSON ADO.NET Data Services フレームワーク)
ADO.NET Data Services フレームワーク