JSONPath / provenance / handoff guide
JSONPathの抽出結果を、位置・null・欠損に分けて渡す
pathは元の位置、nullは存在する値、missingは存在しない状態です。複数結果をまとめず、source provenanceがない場合は不明のままにします。
pathと配列位置を残す
$.users[2].nameのようなpathは、配列indexを含む元の位置です。抽出後の値だけを共有せず、同じ値が別位置にもある可能性を残します。line/columnはsource toolが返した場合だけ記録します。
path: $.users[2].name
value: "Aki"
array_index: 2
provenance: path only; source line unknown| 境界 | 確認すること |
|---|---|
| path/index | rootからのpathと配列indexを保持し、抽出順だけを元位置と呼ばない。 |
| null | keyが存在しvalueがnullなら、present-nullとして記録する。 |
| missing | key自体がなければmissingで、nullへ置き換えない。 |
| multiple results | 複数matchは個別のpath/value結果として保持する。 |
provenanceを捏造しない
JSONPath結果だけから元ファイルの行番号や列番号は分かりません。sourceが返さない位置はunknownと書き、推測で埋めません。
既存のJSONPath toolは端末内の抽出に使えます。このガイドは受渡しreportの項目を固定するもので、入力JSONを外部へ送信しません。
レビューケース
| case | 判定 | 確認 |
|---|---|---|
array-index | path-with-index | 配列位置をpathに含める。 |
explicit-null | present-null | null値とkey欠損を分ける。 |
missing-property | missing | 存在しないkeyをnullにしない。 |
multiple-results | separate-results | 複数結果のpathとvalueを個別に保存する。 |
source-provenance-absent | provenance-unknown | 行番号などを推測しない。 |
unsupported-upload | reject | uploadや曖昧な位置情報は差し戻す。 |
入力を送信しない
本番JSON、token、個人情報をこのガイドへ貼り付けないでください。無害なfixtureを使い、必要なprovenanceはsource toolの出力だけから共有します。