JSON Resolve pointers

JSON Resolve pointers コマンドは、object 引数内にある全てのJSON ポインターを、options 引数で指定した設定(あれば)に基づいて、解決します。

JSON ポインターは、以下のような場合に特に有用です:

• 情報を分解するために、外部JSON ドキュメントの一部埋め込んだり、あるいはあるJSON ドキュメントの一部を同じJSON ドキュメント内の他の箇所に再使用したりする。
• JSON 内での再起的構造を表現する。
• JSON に保存されたデフォルトのプロパティを含んだテンプレートオブジェクトを定義する。

object 引数には、解決すべきJSON ポインターを含んだオブジェクト型を渡します(JSON ポインターシンタックスについての詳細な情報については、以下のJSON ポインターを定義する の段落を参照してください)。

注: ソースとなるobject 引数は、コマンド実行後更新され、ポインター解決の結果が含まれます(ただし結果がオブジェクト型でない場合を除きます、以下参照)。オリジナルのobject 引数をそのまま残しておきたい場合には、事前にOB Copy コマンドを使用することを検討して下さい。

オプションとして、options 引数にはポインターを解決するときに使用する特定のプロパティを格納したオブジェクト型を渡すことができます。以下のプロパティがサポートされています:

プロパティ	値の型	詳細
rootFolder	文字列	object 引数内の相対ポインターを解決する際に使用するフォルダーへの(標準の4D シンタックスを使用した)絶対パス。デフォルトのフォルダーはデータベースのResources フォルダーとなっています。
merge	ブール	オブジェクトをポインターオブジェクトに一部併合する(true)か、完全に置き換えるか(false)を指定します。デフォルトはfalse です。

コマンドが実行されたあと、結果は以下のようになります:

• ポインター解決の結果がオブジェクト型であった場合、object 引数は更新され、結果のオブジェクト型を格納します。
• ポインター解決の結果がスカラー値(テキスト、数値、等)であった場合、object 引数は変更なしで残され、結果の値は戻り値の"value" プロパティへと返されます。

どのような場合においても、コマンドは以下のプロパティを格納したオブジェクト型を返します:

JSON ポインターとは、JSON ドキュメント全体の中にある特定のフィールドあるいはキー値へとアクセスするのに使用することができる文字列シンタックスを定義する規格です。この規格はRFC 6901 において説明されています。

JSON ポインターは、厳密な話をすると、'/'によって分割される部分から構成される文字列です。JSON ポインターは通常、ポインターが解決されるドキュメントを指定するURI内で見つけることができます。URI内でフラグメント文字"#"を使用することでJSON ポインターを指定しています。習慣に則り、JSON ポインターを格納しているURIは、"$ref"と名付けられたJSON オブジェクトプロパティ内にあります。

{
   "$ref":<path>#<json_pointer>
}

注: 4D は存在しない配列要素への参照としての"-" 文字はサポートしていません。

JSON ポインターは再帰的に解決されます。これはつまりポインターが解決されたドキュメント内にポインターが更に含まれていた場合、それもまた再帰的に解決され、全てのポインターが解決されるまで繰り返されるということです。このコンテキストにおいては、JSON ポインターURI内のファイルパスは、すべて相対パスあるいは絶対パスのどちらも可能です。パスは区切り文字として'/' を使用し、以下の方法で解決されなければなりません:

• 相対パスは'/' から始まってはいけません。相対パスはそのパス文字列が見つかったJSON ドキュメントに対して相対的に解決されます。
• 絶対パスは'/' から始まります。セキュリティ上の理由から、"/RESOURCES" のみが絶対パスとして受け入れられ、カレントデータベースのResources フォルダを指定します。例えば、"/RESOURCES/templates/myfile.json" は、カレントデータベースのResources フォルダ内に配置されている"myfile.json" というファイルを指します。

注:

• 名前の解決には、大文字と小文字は区別されます。
• 4D はネットワーク越しにあるjson ファイルへのパス("http/https"から始まるパス)は解決しません。

この基本的な例題では、どのようにしてオブジェクト型の中でJSON ポインターを設定して置き換えるかを考えます:

以下の($oMyConfig という名前の)JSON オブジェクト内において、請求先住所("billingAddress")を送付先住所("shippingAddress")として再使用したい場合を考えます:

{
    "lastname": "Doe",
    "firstname": "John",
    "billingAddress": { 
        "street": "95 S. Market Street",
        "city": "San Jose",
        "state": "California" 
    },
    "shippingAddress": { "$ref": "#/billingAddress" }
}

以下のコードを実行すると:

... 以下のオブジェクトが返されます:

{
    "success": true,
    "value": {
        "lastname": "Doe",
        "firstname": "John",
        "billingAddress": {
            "street": "95 S. Market Street",
            "city": "San Jose",
            "state": "California" 
        },
        "shippingAddress": {
            "street": "95 S. Market Street",
            "city": "San Jose",
            "state": "California" 
        }
    }
}

この例題では、"merge" オプションの効果を紹介しています。デフォルトのファイルに基づいてユーザーの権限を編集したい場合を考えます。

{
    "rights": { 
        "$ref": "defaultSettings.json#/defaultRights",
        "delete": true,
        "id": 456
    }
}

defaultSettings.json ファイルの中身は以下のようになっています:

{
    "defaultRights":
    {
        "edit": true,
        "add": false,
        "delete": false
    }
}

以下のコードを実行すると:

... 結果の値はdefaultSettings.json ファイルの中身そのものと完全に同じです:

{
    "success": true,
    "value": {
        "rights": {
            "edit": true,
            "add": false,
            "delete": false
        }
    }
}

一方、以下のコードを実行すると:

... 結果の値は、元のオブジェクトを一部変更した値になります:

{
    "success": true,
    "value": {
        "rights": {
            "edit": true,
            "add": false,
            "delete": true,
            "id": 456
        }
    }
}