VRC JSON

Data Dictionaries および Data Lists には、JSONとの相互変換を行う関数が含まれています。Data ListはJSON配列に相当し、JSONオブジェクトは文字列キーを持つData Dictionaryに相当します。

JSONスキーマ自体の詳細については、Json documentation を参照してください。このページの内容はすべて、この特定のJSONスキーマの実装に関連しています。

JSON 関数

Function	Inputs	Outputs	Result
VRCJson.TryDeserializeFromJson	String input	success bool, DataToken result	JSON 文字列の input から DataList または DataDictionary を作成します。成功した場合、true を返し、result トークンには DataDictionary または DataList が格納されます。失敗した場合、false を返し、result トークンには問題の内容を説明するエラーが格納されます。
VRCJson.TrySerializeToJson	DataToken input, JsonExportType	success bool, DataToken result	DataDictionary または DataList を JSON 文字列の output に変換しようとします。成功した場合、true を返し、result トークンには最終的な JSON 文字列が格納されます。失敗した場合、false を返し、result トークンには問題の内容を説明するエラーが格納されます。

Udon Graph では、すべてのクラス名の先頭から "VRC" が削除されているため、これらの関数を探すには "Json" で検索する必要があります。
UdonSharp では、これらのクラスは VRC.SDK3.Data 名前空間に含まれています。

サポートされている型と値

JSONは小さく、シンプルで厳格な仕様です。DataListやDataDictionaryはより幅広い構成をサポートできるため、データコンテナからJSONへ変換する際にいくつかの制限に直面する可能性があります。これらの制限を理解し、JSONを使用する予定がある状況では、それらの構成を使用しないようにしてください。

JSONは Object Reference Data Tokenをサポートしていません。 JSONにシリアライズしようとする際にデータコンテナ内にオブジェクト参照が含まれていると、TrySerializeToJson関数は DataError.TypeUnsupported を返して失敗します。

JSONは文字列キーの辞書のみをサポートしています。 JSONにシリアライズしようとする際にDataDictionaryの中に文字列以外のキーが含まれていると、TrySerializeToJson関数は DataError.TypeUnsupported を返して失敗します。

JSONは NaN や Infinity をサポートしていません。 NaN や Infinity を含む float や double がある場合、TrySerializeToJson関数は DataError.ValueUnsupported を返して失敗します。

JSONはルートとして Dictionary または List 以外をサポートしていません。 子要素を持たない単純な値のDataTokenを使用した場合、TrySerializeToJson関数は DataError.TypeUnsupported を返して失敗します。

JSONは1種類の数値のみをサポートしています。 すべての異なる数値型を区別しません。その結果、JSONからデシリアライズすると、すべての数値は Double 形式で格納されます。int、byte、あるいは float といった他の数値型を含むData TokenもJSONにシリアライズすることは可能ですが、同じJSONをデータコンテナにデシリアライズし直すと、それらは Doubles に変換されていることに気づくでしょう。

JSONからのデシリアライズ

VRCJson.TryDeserializeFromJson は、JSONからデータコンテナへ変換する際に使用すべき関数です。if や branch の条件として使用することで、処理が成功した場合と失敗した場合の挙動をそれぞれ定義することを推奨します。

%%TryDeserializeFromJson%% が true を返した場合、JSON文字列から %%DataList%% または %%DataDictionary%% への変換が成功したことを意味します。その後、結果に対して型チェックを行い、各ケースに応じた処理を行ってください。

この関数が false を返した場合、指定した文字列は有効なJSONではありません。渡された %%DataToken%% は %%DataError%% となり、%%DataToken.ToString%% を実行すると、エラーの内容と何が問題であったかを示す詳細な説明文が得られます。

パフォーマンス上の理由から、%%VRCJSON%% はすべてを即座に解析するわけではありません。代わりに、まずは最上位レベルのJSONのみを解析します。最上位が有効であっても、入れ子構造の深い部分に無効なJSONが含まれている場合、最初の %%TryDeserializeFromJson%% は true を返す可能性があります。その後、無効な箇所から %%TryGetValue%% を使用して値を取得しようとすると、false が返され、%%DataError.UnableToParse%% が発生します。

if (VRCJson.TryDeserializeFromJson(json, out DataToken result))
{
    // Deserialization succeeded! Let's figure out what we've got.
    if (result.TokenType == TokenType.DataDictionary)
    {
        Debug.Log($"Successfully deserialized as a dictionary with {result.DataDictionary.Count} items.");
    }
    else if (result.TokenType == TokenType.DataList)
    {
        Debug.Log($"Successfully deserialized as a list with {result.DataList.Count} items.");
    }
    else 
    {
        // This should not be possible. If TryDeserializeFromJson returns true, this it *must* be either a dictionary or a list.
    }
} else {
    // Deserialization failed. Let's see what the error was.
    Debug.Log($"Failed to Deserialize json {json} - {result.ToString()}");
}

JSONへのシリアル化

データコンテナからJSONへ変換する際は、VRCJson.TrySerializeToJson関数を使用してください。この関数をifまたはbranchの条件として使用することで、処理が成功した場合と失敗した場合の動作をそれぞれ指定することをお勧めします。

VRCJson.TrySerializeToJsonがtrueを返した場合、%%DataList%%または%%DataDictionary%%が正常にJSON文字列へ変換されています。その場合、結果のトークンから安全に文字列を取得できます。

if (VRCJson.TrySerializeToJson(dictionary, JsonExportType.Beautify, out DataToken json))
{
    // Successfully serialized! We can immediately get the string out of the token and do something with it.
    Debug.Log($"Successfully serialized to json: {json.String}");
} 
else 
{
    // Failed to serialize for some reason, running ToString on the result should tell us why.
    Debug.Log(json.ToString());
}

JsonExportType

JSONへシリアル化する際は、希望する%%JsonExportType%%を選択できます。人間が読みやすい形式が必要な場合はBeautifyが適しており、ネットワーク送信などでコンパクトな形式が必要な場合はMinifyが適しています。

Beautify: 各要素を新しい行に展開し、階層ごとに1つタブを追加します。
Minify: すべてを1行にまとめ、空白を最小限に抑えます。

最終更新: 2023年12月8日