HN 日本語サマリー

← 一覧へ戻る
プログラミング

JEP 540: シンプルなJSON API(インキュベーター段階)

JEP 540: Simple JSON API (Now in Incubator) (openjdk.org)

89 pointsby theanonymousone66 コメント

要約

JavaのOpenJDKプロジェクトで、JEP 540としてシンプルなJSON APIがインキュベーター段階で導入されました。この提案は、Java SEプラットフォームにJSON処理のための標準的なAPIを提供することを目指しています。これにより、開発者は外部ライブラリに依存することなく、より簡単にJSONデータを操作できるようになります。

全文翻訳

JEP 540: シンプルなJSON API(インキュベーター版)

概要

外部ライブラリを必要とせずにJSONドキュメントを解析および生成するための、シンプルで標準的なAPIを定義します。これにより、多くのJSON処理タスクを少ないコーディングで達成できるようになります。これはインキュベーターAPIです。

履歴

このJEPは、2014年に書かれたJEP 198「軽量JSON API」に取って代わるものです。その後の状況の変化を踏まえ、ここでは異なるアプローチを採用します。

目標

  • Javaプラットフォームにおいて、RFC 8259に準拠したJSONドキュメントを、低儀礼で処理するための標準的な手段を提供する。

  • APIを小さく、シンプルで、学習しやすいものにする。RFC 8259への厳密な準拠に必要なデータ型と操作のみを提供し、機械間通信を容易にする。複数の解析設定、構文拡張、データバインディング、ストリーミングなどの機能は避ける。

  • 既知の構造を持つJSONドキュメントをナビゲートし、データを抽出するコードがシンプルで読みやすいことを保証する。JSONドキュメントにはスキーマがないため、そのようなコードは事実上のスキーマとして機能し、そのように読み取れるべきである。

  • 未知のJSONドキュメントの簡単なクイック探索を可能にする。私たちはしばしば、仕様を使わずにコードを書き、例となるドキュメントに対して試すという探索的な方法でJSONドキュメントを扱う。APIは、明確なエラーメッセージで迅速に失敗するメソッドを提供し、迅速な探索を可能にするべきである。

  • JSONドキュメント構造が時間とともに進化する可能性があるため、欠落または予期しない値を回復力のある方法で処理できるようにする。

  • JDK自体がJSONドキュメントを解析および生成できるようにする。

非目標

  • 確立された外部JSONライブラリに取って代わるAPIを作成することは目標ではない。

動機

JSONは現代のコンピューティングにおいて至る所に存在します。Javaエコシステムには、Jackson、Gson、Jakarta JSON ProcessingおよびBinding、Fastjson 2など、幅広い確立されたJSONライブラリが存在します。これらのライブラリはJSONドキュメントの解析と生成を可能にするだけでなく、JSON5のような拡張JSON構文や、JavaオブジェクトとJSON間の高レベルなカスタマイズを伴うデータバインディング、イベントベースのストリーミングなどの機能もサポートしています。

しかし、多くの場合、JSONドキュメントから一部のデータを抽出するといった単純なタスクを実行するだけで十分です。PythonやGoでそのようなタスクを実行するコードはシンプルですが、Javaコードも同様にシンプルであるべきです。

例えば、米国国立気象サービスREST APIからの応答に含まれる一連の予報気温の平均を計算するタスクを考えてみましょう。応答は次のようなJSONドキュメントです。

{
  ...
  "properties": {
    ...
    "periods": [
      {
        "number": 1,
        "name": "Today",
        "startTime": "2026-04-22T06:00:00-04:00",
        "endTime": "2026-04-22T18:00:00-04:00",
        "isDaytime": true,
        "temperature": 54,
        "temperatureUnit": "F",
        ...
      },
      {
        "number": 2,
        "name": "Tonight",
        "startTime": "2026-04-22T18:00:00-04:00",
        "endTime": "2026-04-23T06:00:00-04:00",
        "isDaytime": false,
        "temperature": 48,
        "temperatureUnit": "F",
        ...
      },
      {
        "number": 3,
        "name": "Thursday",
        "startTime": "2026-04-23T06:00:00-04:00",
        "endTime": "2026-04-23T18:00:00-04:00",
        "isDaytime": true,
        "temperature": 68,
        "temperatureUnit": "F",
        ...
      },
      ...
    ]
  }
}

予報気温の平均を計算するには、ドキュメントを解析し、予報が含まれる構造内の場所にナビゲートし、温度データを抽出しながら予報の配列を反復処理する必要があります。外部ライブラリをインストールすることなく、また他の言語の方が生産性が高いと疑うことなく、このような単純なタスクを単純なJavaコードで処理できるべきです。

Javaプラットフォームの最近の進化を推進する主要な目標の1つは、単純なタスクをより簡単に、より少ない儀礼で達成できるようにすることです。この目標に役立つ機能には、コレクションの便利なファクトリメソッド、var宣言、ソースファイルからのプログラム実行、およびコンパクトなソースファイルとインスタンスmainメソッドが含まれます。JSONのシンプルなAPIは、この重要な目標にも役立ちます。

JDKでのJSONの使用

Javaプラットフォームに標準のJSON APIがあれば、プラットフォーム内およびJDK自体によるJSONのさらなる利用への道が開かれます。JDKは外部依存関係を持つことができないためです。1つの潜在的なユースケースは設定ファイルです。JDKは、セキュリティプロパティファイルなどのさまざまな設定ファイルにプロパティファイル形式を使用しています。この形式の弱点は、構造化データを表現できないことです。プロパティファイルで配列を表現するには、順次番号付けされたプロパティのような不格好な回避策を使用する必要があります。

security.provider.1=SUN
security.provider.2=SunRsaSign
security.provider.3=SunEC
...

JDKにJSONが組み込まれれば、設定ファイルはJSON配列を使用して、配列を自然に表現できるようになります。

{
  "providers": [ "SUN", "SunRsaSign", "SunEC" ],
  ...
}

説明

jdk.incubator.json APIは、JSON値を表すJsonValueインターフェースを中心に構成されています。

JSON構文には4種類のプリミティブがあります。

  1. ダブルクォートで囲まれたJSON文字列:

    "Hello"
    "My name is 'Bob'"
    "\u006a\u0061\u0076\u0061"
    
  2. 10進数を使用した基数10で表されるJSON数値:

    6  6.0  31.84  2.9E+5
    
  3. JSONブール値リテラル:trueおよびfalse

  4. JSON nullリテラル:null

そして2種類の構造があります。

  1. { }で区切られ、コンマ区切りのメンバーで構成されるJSONオブジェクト。メンバーは名前(キーとも呼ばれる)と値で構成され、コロンで区切られます。

    {
      "address" : "123 Smith Street",
      "value" : 31.84,
      "coordinates" : [ [ 37, 23, 41 ], [ -121, 57, 10 ] ]
    }
    
  2. [ ]で区切られ、コンマ区切りのJSON値で構成されるJSON配列:

    [ 1, 2, 3, { "value": "4" }, [ 5, 6 ] ]
    

したがって、JsonValueインターフェースには、対応する6つのサブインターフェースがあります:JsonString、JsonNumber、JsonBoolean、JsonNull、JsonObject、およびJsonArray。各インターフェースは、対応するJSON構文要素に適した操作を宣言しています:JsonNumberおよびJsonBooleanインスタンスはJavaプリミティブへの変換を提供し、JsonStringインスタンスはJava Stringへの変換を提供し、JsonObjectインスタンスはメンバーを公開し、JsonArrayインスタンスは配列要素を公開します。

JsonValueインターフェースはsealedであり、任意のJsonValueインスタンスが常にこの固定セットのサブタイプのいずれかであることを保証するため、網羅的なswitch式とステートメントはdefault句を必要としません。

JSON APIは、RFC 8259に準拠したJSONドキュメントを簡単に解析できます。Jsonクラスのparseメソッドは、解析されたJSONデータの名前、型、値を示すJsonValueインスタンスのツリーを返します。国立気象サービスの例に戻ると、数行で平均予報気温を計算できます。

String body = ... RESTレスポンスボディ、JSONドキュメントです ... ;
JsonValue json = Json.parse(body);
json.get("properties").get("periods").asList().stream()
    .mapToInt(j -> j.get("temperature").asInt())
    .average()
    .ifPresent(IO::println);

(完全な例は付録に示されています。)

APIはJSONドキュメントの生成も容易にします。例えば、このコード:

IO.println(JsonObject.of(Map.of("providers",
                                JsonArray.of(List.of(JsonString.of("SUN"),
                                                     JsonString.of("SunRsaSign"),
                                                     JsonString.of("SunEC"))))));

は次の出力を生成します。

{"providers":["SUN","SunRsaSign","SunEC"]}
JSONドキュメントの解析とナビゲーション

Jsonクラスは、Stringまたはchar配列に含まれるJSONドキュメントを解析できます。JSONドキュメントは、ネットワークから読み取られたREST APIレスポンスボディ、ディスクから読み取られた設定ファイル、またはアプリケーションによって生成されたその他のテキストペイロードである可能性があります。

JSONドキュメントの解析には、Json.parseメソッドのいずれかへの単一の呼び出しが必要です。

JsonValue root = Json.parse(doc);

解析は厳密です:ドキュメントはRFC 8259に準拠している必要があります。末尾のカンマやコメントなどの構文拡張はサポートされていません。さらに、ドキュメントには重複したメンバー名を持つオブジェクトを含めることはできません。このポリシーは、RFCによって許可されており、最大限の相互運用性と予測可能性を提供し、不正または曖昧なJSONドキュメントの処理に関する懸念を軽減します(重複に関する完全な議論は以下を参照)。

解析が成功すると、JsonValueインスタンスが返されます。解析に失敗すると、チェックされないJsonParseExceptionがスローされます。例外には、エラー、ドキュメントのルートからのパス、およびドキュメント内の場所に関する特定の情報を提供する詳細メッセージが含まれます。例えば、ドキュメントにオブジェクト内の重複したメンバー名が含まれている場合、スローされる例外は次の形式になります。

jdk.incubator.json.JsonParseException: The duplicate member name: "providers" was
already parsed. Path: "{". Location: line 2, position 4.

ほとんどのJSONドキュメントは、ルートにJSONオブジェクトまたはJSON配列を持ちます。例えば、jcmdツールによって生成されたJSON形式のスレッドダンプにはルートオブジェクトが含まれています。

{
  "threadDump": {
    "formatVersion": 2,
    "processId": 45178,
    "time": "2026-04-16T23:13:02.709630Z",
    "runtimeVersion": "27-internal",
    "threadContainers": [
      {
        "container": "<root>",
        "parent": null,
        "owner": null,
        "threads": [
          {
            "tid": 3,
            "time": "2026-04-16T23:13:02.906891Z",
            "name": "main",
            "state": "WAITING",
            ...

ルートオブジェクトには単一のメンバー、ネストされたthreadDumpオブジェクトが含まれており、threadDump自体はプリミティブ値と構造化JSON値の両方を含んでいます。

Json.parse(...)を介してルートJsonValueを取得したら、オブジェクトと配列からアクセスメソッドを介して値を取得できます。これらのメソッドは、要求されたメンバー値または配列要素をJsonValueとして返します。メンバー値にアクセスするためにJsonValueをJsonObjectにダウンキャストしたり、配列要素にアクセスするためにJsonArrayにダウンキャストしたりする必要はありません。

  • get(String)はオブジェクトメンバーの値を取得します。スレッドダンプオブジェクトを取得するには:

    JsonValue threadDump = root.get("threadDump");
    
  • get(int)は配列要素を取得します。ルートスレッドコンテナを取得するには:

    JsonValue firstContainer = threadDump.get("threadContainers").get(0);
    

JsonValueインスタンスが間違った型である場合、または要求されたメンバーまたは要素が存在しない場合、アクセスメソッドはJsonValueExceptionをスローします。

JSON値をJava値に変換する

JsonValueインターフェースの変換メソッドを呼び出すことで、JSON値をJava値に変換できます。変換を成功させるには、JsonValueがJsonValueの適切なサブタイプのインスタンスである必要があります。

サブタイプメソッド結果のJava型
JsonStringasString()java.lang.String
JsonNumberasInt()int
JsonNumberasLong()long
JsonNumberasDouble()double
JsonBooleanasBoolean()boolean
JsonObjectasMap()java.util.Map
JsonArrayasList()java.util.List

例えば、スレッドダンプの「time」メンバーに関連付けられたJava String値を取得できます。

JsonValue threadDumpTime = threadDump.get("time");
String time = threadDumpTime.asString();

スレッドコンテナ配列をJsonValueインスタンスのListに変換し、各インスタンスを処理できます。

threadDump.get("threadContainers").asList().forEach(jv -> ...);

スレッドダンプオブジェクトをMapとしてアクセスして、メンバーの数を取得できます。

int count = threadDump.asMap().size();

JSONドキュメントの奥深くをナビゲートし、アクセスメソッドを連鎖させ、最後にJava値に変換できます。ルートスレッドコンテナの最初​​のスレッドのスレッド識別子値を取得するには:

long tid = threadDump.get("threadContainers").get(0)
                     .get("threads").get(0).get("tid").asLong();

変換メソッドの設計により、特定のJSONデータ型がドキュメントで期待される場合のinstanceofチェックとダウンキャストのほとんどが排除されます。

  • asString()は、JsonStringインスタンスをRFC 8259 JSONエスケープシーケンスを対応する文字に変換したJava Stringに変換します。

  • asInt()は、JsonNumberインスタンスの数値が正確に表現できる場合に、Java intに変換します。

  • asLong()は、JsonNumberインスタンスの数値が正確に表現できる場合に、Java longに変換します。

  • asDouble()は、JsonNumberインスタンスの数値が正確に表現できる場合に、Java doubleに変換します。

  • asBoolean()は、JsonBooleanインスタンスをtrueまたはfalseのJava boolean値に変換します。

  • asMap()は、JsonObjectインスタンスを不変のJava Mapに変換します。JSONオブジェクトにメンバーが含まれていない場合、空のMapが返されます。

  • asList()は、JsonArrayインスタンスを不変のJava Listに変換します。JSON配列に要素が含まれていない場合、空のListが返されます。

JSON null値の変換メソッドはありません。JsonNullインスタンスは、instanceof JsonNullでテストするか、tryValueメソッドを介して処理できます。

JsonValueが変換メソッドに適したサブタイプのインスタンスでない場合、メソッドはJsonValueExceptionをスローします。例えば、JsonStringのインスタンスであるJsonValueに対してasInt()を呼び出すと、常にこの例外がスローされます。文字列値を数値に解析しようとはしません。

数値変換は、数値がターゲットJava数値型で表現できないなどの理由で失敗する可能性があり、これもJsonValueExceptionをスローします。数値の処理と変換に関する詳細については以下を参照してください。

JSONドキュメントの進化の処理

特定のソースからのJSONドキュメントは、時間とともに、以前の構造とコンテンツの期待に違反する形で進化する可能性があります。

  • ドキュメントのJSONオブジェクトとJSON配列に存在しないメンバー名または配列インデックスを期待してアクセスメソッドを呼び出す可能性があります。

  • 異なる型の値に対して、特定のJSONデータ型に適用可能な変換メソッドを呼び出す可能性があります。

間違った型でアクセスまたは変換メソッドを呼び出すと、JsonValueExceptionがスローされます。この例外はチェックされないため、スクリプトや小さなプログラムの読み書きが容易になります。

スレッドダンプの例を続けると、ルートJSON値は単一のメンバーthreadDumpを持つJSONオブジェクトであることを思い出してください。このコード:

JsonValue name = root.get("threadName");

は、JSONオブジェクトに"threadName"という名前のメンバーが含まれていないことを説明するメッセージとともにJsonValueExceptionをスローします。一方、このコード:

List<JsonValue> threadDumpList = threadDump.asList();

は、threadDumpメンバーがJSON配列ではなくJSONオブジェクトであることを説明するメッセージとともにJsonValueExceptionをスローします。

例外メッセージは、JSONドキュメントのルートから予期しないJSON値へのパス、およびJSONドキュメント内の位置を説明します。これは、アクセスメソッドのチェーンがドキュメントの奥深くをナビゲートする場合に役立ちます。例えば、以前のスレッド識別子を抽出するコードスニペットが、誤ってlongではなくbooleanに変換した場合:

boolean tid = threadDump.get("threadContainers").get(0)
                        .get("threads").get(0).get("tid").asBoolean();

すると、asBoolean()によってスローされる例外は次の形式になります。

jdk.incubator.json.JsonValueException: JsonNumber is not a JsonBoolean. Path:
 "{threadDump{threadContainers[0{threads[0{tid". Location: line 13, position 19.
オプションメンバーの処理

JSONオブジェクトに指定された名前のメンバーがあるかどうかわからない場合は、tryGetアクセスメソッドを使用できます。これは、メンバーの値を含むOptionalインスタンスを返します。メンバーが存在しない場合は空のOptionalを返します。(対照的に、getメソッドはメンバーが存在することを確認し、存在しない場合は例外をスローします。)tryGetメソッドは、JsonObjectで呼び出されない場合にJsonValueExceptionをスローします。

次のスレッドオブジェクトを検討してください:

{
  "tid": 11,
  "time": "2026-04-16T23:13:02.918321Z",
  "name": "Finalizer",
  "state": "WAITING",
  "waitingOn": "java.lang.Object@c10f5b9",
  "stack": [
    ...

スレッドオブジェクトには複数のオプションメンバーが含まれています。そのうちの1つはwaitingOnメンバーであり、スレッドが待機しているオブジェクトのJSON文字列表現を含んでいます。しかし、スレッドが待機していない場合、スレッドオブジェクトは次のようになります。

{
  "tid": 10,
  "time": "2026-04-16T23:13:02.918177Z",
  "name": "Reference Handler",
  "state": "RUNNABLE",
  "stack": [
    ...

したがって、スレッドダンプからスレッドオブジェクトを処理する際には、waitingOnメンバーが存在しない可能性があることを想定する必要があります。これはtryGetで処理できます。

JsonValue thread = ...
thread.tryGet("waitingOn")
      .ifPresent(result -> ...);

ifPresentに渡されたラムダは、waitingOnメンバーが存在する場合にのみ呼び出されます。

null値の処理

JSON値がJSON nullであるかどうかわからない場合は、tryValueアクセスメソッドを使用できます。このメソッドは、呼び出されたJSON値がJsonNullの場合に空のOptionalを返します。それ以外の場合は、その値を返します。

例えば、スレッドコンテナオブジェクトは通常次のようになります。

{
  "container": "java.util.concurrent.ThreadPoolExecutor@1936a586",
  "parent": "<root>",
  ...

ここでは、parentメンバーの値はJSON文字列、つまり親コンテナの名前です。しかし、<root>という名前のコンテナはすべてのコンテナのルートであり、次のようになります。

{
  "container": "<root>",
  "parent": null,
  ...

ルートコンテナには親がないため、parentメンバーの値はJSON nullです。したがって、スレッドダンプからコンテナオブジェクトを処理する際には、親メンバーがJSON文字列またはJSON nullのいずれかである可能性を想定する必要があります。これはtryValueで処理できます。

JsonValue container = ...
container.get("parent").tryValue()
         .ifPresent(result -> ...);

ifPresentに渡されたラムダは、「parent」メンバーの値がJSON nullでない場合にのみ呼び出されます。

可変な構造とコンテンツの処理

特定のコンテキストにおけるJSONドキュメントの構造とコンテンツは、しばしば均一ですが、時には可変です。異なるソース間で、または特定のソースから時間とともに進化するソース間で、あるいは同じドキュメント内でも変化する可能性があります。

例えば、JDK 26以前のリリースではスレッド識別子はJSON文字列として表されますが、JDK 27以降のリリースではJSON数値として表されます。

例えば、tidがJSON数値であると期待するコード:

long tid = thread.get("tid").asLong();

は、tid値をJSON文字列として出力するJDKバージョンによって生成されたスレッドダンプに遭遇した場合、JsonValueExceptionで失敗します。

どちらの表現でも、数値はJava longに収まるように指定されています。instanceofを使用してJsonNumberまたはJsonStringであるかを確認できますが、switchステートメントで型パターンを使用する方が明確です。

long tid = switch (thread.get("tid")) {
    case JsonNumber jn -> jn.asLong();
    case JsonString js -> Long.parseLong(js.asString());
    default -> throw new JsonValueException("Unexpected type for \"tid\"");
};
JSONドキュメントの生成

JsonValueからJSONドキュメントを文字列形式で生成するには、そのtoStringメソッドを呼び出すだけです。このメソッドは、すべてのメンバー、要素、および値が空白なしで同じ行に出力されるコンパクトな文字列表現を返します。

例えば、このコード:

JsonValue json = Json.parse("""
  {
    "service" : "web_server",
    "id" : 3
  }
  """);
IO.println(json.toString());

は次のように出力します。

{"service":"web_server","id":3}

(toStringメソッドは、asStringメソッドとは異なります。asStringメソッドは、呼び出されたJsonValueがJsonStringでない場合に例外をスローします。)

静的メソッドJson.toDisplayStringは、JSONドキュメントの整形された形式を出力します。メンバーと要素は改行で区切られ、ネストされた構造は指定されたStringでインデントされます。例えば、このコード:

IO.println(Json.toDisplayString(json, "  "));

は、2スペースのインデントで上記の構造を出力します。

{
  "service": "web_server",
  "id": 3
}

toStringメソッドとJson.toDisplayStringメソッドの両方の出力は、Json.parseメソッドで解析可能であり、元のドキュメントと同じJSON値を表すJsonValueを生成します。

JSON数値

RFC 8259で定義されているJSON数値の構文は、任意の精度と範囲の10進値を表すことができます。JSON APIはJSON数値をロスレスで処理できるようにしますが、ほとんどのアプリケーションでは一般的な数値型で十分です。

RFC 8259は、JSONライブラリ間の良好な相互運用性を達成するために、Java double型に対応するIEEE 754 64ビットバイナリ浮動小数点値を使用することを推奨しています。したがって、asDouble()メソッドは、数値JSON値をJava doubleに変換します。JSON値はdoubleが表せる範囲内にある必要があります。範囲外の値の場合、JsonValueExceptionがスローされます。無限大および非数(「NaN」)の値はJSONで表現できないため、決して返されません。ただし、負のゼロはJSONで表現できるため、返される可能性があります。

JSON値がdoubleで表現できるよりも高い精度を持つ場合、値は最も近いdouble値に丸められます。例えば:

double d1 = Json.parse("3.141592653589793238462643383279").asDouble();
// d1 は 3.141592653589793、最も近い double 値

double d2 = Json.parse("1.8E309").asDouble();
// JsonValueException、範囲外をスロー。
// Double.parseDouble("1.8E309") は正の無限大を生成します。

整数値は頻繁に使用されるため、asInt()メソッドは、数値JSON値をJava int値に変換します。JSON値は正確にintとして表現できる必要があります。そうでない場合、例外がスローされます。小数部分を持つが整数値を表す数値は変換されます。例えば:

int i1 = Json.parse("123.0").asInt();       // 成功
int i2 = Json.parse("234.56E2").asInt();    // 成功
int i3 = Json.parse("345.6").asInt();       // 失敗、整数ではない
int i4 = Json.parse("2147483648").asInt();  // 失敗、範囲外

変換メソッドasLong()はasInt()に似ていますが、Java long値を返し、longとして正確に表現できるJSON数値値をサポートする点が異なります。

intまたはdoubleよりも狭いプリミティブ型が必要な場合は、パターン内のプリミティブ型(現在プレビュー機能)を使用して安全な変換を実行できます。例えば、JSON数値がshortとして表現できると期待する場合:

JsonValue json = Json.parse("""
  {
    "id": 12345,
    "price": 10.99
  }
  """);
if (json.get("id").asInt() instanceof short s) {
    // s を使用
} else {
    // 範囲外エラーを報告
}

前述のように、JSON数値は任意の精度と範囲を持つことができます。asDouble()、asInt()、およびasLong()メソッドは、定義により、JSON数値値のサブセットのみを処理します。範囲外の値を拒否し、過度に正確な値を丸めます。情報損失なしにJSON数値データを処理するには、実質的に任意のJSON数値をjava.math.BigDecimalインスタンスに変換できます。

BigDecimal bd = new BigDecimal(jn.toString());

代替案

  • 限定された機能セットではなく、完全な機能セットを提供する。

    多くの既存の外部JSONライブラリは、その中で広範な機能セットを提供しています。Javaプラットフォームにこれらすべての機能を含めることはできません。代わりに、コストに対する価値が最も高い機能のサブセットを選択する必要があります。

    一般的に提供されているデータバインディング機能は除外しました。この機能は多くのアプリケーションにとって間違いなく有用で便利です。しかし、それはAPIフットプリントを大幅に増やし、実装と保守のコストを劇的に増加させるでしょう。多くのユースケースではデータバインディングを必要としないため、この機能は厳密には必要ないと考えています。JacksonおよびJakarta JSONライブラリがデータバインディング機能を個別のモジュールに分割していることは、データバインディングを必要としないユースケースがあることの暗黙の認識です。

    ストリーミングAPIは、特定の狭い専門的なユースケースには明らかに不可欠ですが、単純なデータ抽出タスクでさえかなりのアプリケーション複雑性を引き起こします。したがって、この機能は除外しました。

    データバインディングとストリーミングを除外すると、JSONドキュメントがJSON固有のオブジェクトのツリーに解析され、そこからデータを簡単に抽出できるDOMライクなアプローチが残ります。APIは小さく、それに伴って実装と保守のコストも小さくなります。これは、最も単純なものから中程度の複雑さのものまで、JSONアプリケーションの大部分のニーズを満たします。

    アプリケーションはJavaプラットフォームのJSON APIの使用から開始するかもしれませんが、最終的にデータバインディングやストリーミングのような機能が必要になり、外部ライブラリのより豊富なAPIへの移行が必要になる場合があります。このシナリオを失敗とは見なしておらず、JavaプラットフォームにJSONデータバインディングやストリーミングのような高コスト機能を含める正当な理由とは考えていません。

  • 外部JSONライブラリを統合する。

    外部ライブラリをJavaプラットフォームとJDKに統合し、ダウンストリームフォークとして扱うことができます。これは、ライセンスとガバナンスに関する難しい問題を引き起こすでしょう。仕様の品質、互換性、リリーススケジュールなどに関する異なる基準から生じる、両方向の流れにおける継続的な緊張があるでしょう。(私たちは過去に、さまざまなXML APIでこの緊張を経験しました。)これらのコストは、JDKの追加の保守負担と相まって、外部ライブラリを統合するメリットを上回る可能性が高いです。

  • JSONはすでに外部ライブラリによってうまく処理されているため、何もしない。

    何もしないことは、特に単純なプログラムやJavaプラットフォームの新規ユーザーにとって、単純なタスクをより簡単に、より少ない儀礼で達成できるようにするという、より大きな目標に役立たないでしょう。

    アプリケーションに外部依存関係を追加することは、コストがかかり、リスクが増加します。JSONから利益を得られる可能性があるが、コストとリスクを最小限に抑えたいという保守担当者の希望からそうしていないアプリケーションも存在するでしょう。そのようなアプリケーションは、Javaプラットフォームに標準のJSON APIがあることから利益を得るでしょう。

  • JSONオブジェクト内の重複したメンバー名を許可する。

    これはJSONにおける長年の問題でした。初期の仕様では、単一のJSONオブジェクト内の重複したメンバー名の処理に関して未決定でした。JSONライブラリは一貫性のない動作をするか、重複名の処理ポリシーを選択するためのアプリケーション設定可能なオプションを提供していました。

    残念ながら、名前が重複したオブジェクトは根本的に曖昧です。2013年にECMAScriptディスカッションリストで重複名問題が議論された際、重複名を禁止することへの懸念は、それが既存のドキュメントを無効にするということでした。したがって、「一意であるべき」という言葉(「必須」ではなく)が保持され、現在の仕様に引き継がれました。特に、RFC 8259は次のように述べています:

    オブジェクト内の名前は一意であるべきです。

    ...

    すべての名前が一意なオブジェクトは、そのオブジェクトを受け取るすべてのソフトウェア実装が名前と値のマッピングに同意するという意味で相互運用可能です。オブジェクト内の名前が一意でない場合、そのようなオブジェクトを受け取るソフトウェアの動作は予測不能です。

    予測不能性は、複数の独立して開発されたJSONライブラリからなるシステムによってオブジェクトが処理される場合に発生します。これは、診断が困難なエラー、セキュリティ脆弱性、相互運用性の低下、および一般的な堅牢性の欠如につながる可能性があります。この現象はRFC 9413、「堅牢なプロトコルの維持」で議論されています。

    これらの理由から、重複名を無条件にエラーとして扱う厳格なアプローチを選択しました。この厳格なアプローチは、解析されたドキュメントの正確性に対する高い信頼性を提供します。2013年のECMAScriptの会話で言及されたエラーのあるドキュメントは、その間に修正され、それらのドキュメントを生成したソフトウェアも修正されたことを願っています。

  • 末尾のカンマ、コメント、またはその他の構文拡張をサポートする。

    JSON5のようなJSONのいくつかのバリアントがあり、配列やオブジェクト内のコメントや末尾のカンマをサポートしています。これらの拡張機能は、JSONドキュメントの手編集を容易にすることを目的としています。

    シンプルさと機械間通信に焦点を当てているため、これらの拡張機能はサポートしません。これらをサポートすると、テストマトリックスが拡大し、相互運用性エラーの可能性が増加し、全体的な開発および保守の負担が増加します。

    一般的な回避策は、解析前に拡張JSONドキュメントを前処理することです。例えば、'#'文字で始まる行の単一行コメントは、解析前に簡単に削除できます。

    String jsonc = Files.readString(Path.of("file-with-comments.json"));
    String json = jsonc.replaceAll("(?m)^\\s*#.*$", "");
    JsonValue jv = Json.parse(json);
    
  • 追加の変換メソッドを提供する。

    asBigDecimal()のような追加の変換メソッドを、利便性のために含めることができます。そのようなメソッドは実装が容易でしょう。しかし、メソッドが簡単に含められるという事実だけでは、APIに追加する正当な理由にはなりません。私たちの目標は、アプリケーションが上に構築できる最小限のAPIを提供することです。new BigDecimal(JsonNumber.toString())を書くのも同様に簡単です。

    各追加メソッドは1つの利便性かもしれませんが、それはまた1つの意見決定です。さらに、変換メソッドはJsonValue上で均一に定義されているため、APIを使いやすくするという意図と一致して、このメソッドセットを小さく焦点を絞ったものに保つことを目指しています。必要な操作の最小セットを提供することで、APIのユーザーは、特定のニーズに合わせて調整された追加レイヤーを自由に定義できます。

テスト

RFC 8259 JSONの正規形式のみが解析および生成されることを保証するために、JSON APIを厳密にテストします。これにより、APIの使用が他のJSONライブラリとの対話で一貫性を損なわないようになります。これを達成するために、JDKに包括的な単体テストを追加するだけでなく、多数のエッジケース入力を含む確立されたJSON解析テストスイートを活用します。

リスクと仮定

  • 入力JSONドキュメントが、Stringまたはchar配列としてメモリに収まり、解析結果もメモリに収まると仮定します。ツリーベースのモデルのため、ファイルやネットワーク接続のようなJSONソースを許可した場合、大きなドキュメントでのメモリ不足などの問題が発生する可能性があります。この決定は、ミニマリスト設計哲学に沿ったものです。

  • この提案のリスクは、この新しいAPIがすでに外部JSONライブラリを使用しているアプリケーションで使用され、混乱と混乱につながる可能性があることです。このリスクは、メリットによって上回られると考えています。

  • インキュベーション期間中、これらの領域のAPIを進化させるために、JSONドキュメントの生成と変換を含むユースケースに関する情報をさらに収集します。さらに、APIの設計に影響を与える可能性のある今後のパターンマッチング言語機能を引き続き検討します。

付録:天気予報の例

次のプログラムは、カリフォルニア州サンタクララ向けの7日間の天気予報のために、米国国立気象サービスREST APIにリクエストを発行します。レスポンスボディでJSONドキュメントを受信します。プログラムはドキュメントを解析し、構造内にナビゲートして、予報の配列を取得します。次に、各予報から温度を抽出し、それらを平均して結果を出力します。

import java.net.*;
import java.net.http.*;
import jdk.incubator.json.Json;
import jdk.incubator.json.JsonValue;

void main() throws Exception {
    var query = "https://api.weather.gov/gridpoints/MTR/97,83/forecast";
    var client = HttpClient.newHttpClient();
    var request = HttpRequest.newBuilder(URI.create(query)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    JsonValue json = Json.parse(response.body());
    json.get("properties").get("periods").asList().stream()
        .mapToInt(j -> j.get("temperature").asInt())
        .average()
        .ifPresent(IO::println);
}
インキュベーターAPIの有効化

JSON APIは、現時点ではインキュベーターモジュールであり、デフォルトで無効になっています。使用するには、コマンドラインオプション--add-modules jdk.incubator.jsonを介して有効にする必要があります。これにより、インキュベーターモジュールが解決可能なモジュールのセットに追加されます。上記の例のプログラムを実行するには、コンパイル時と実行時の両方でこのオプションを提供する必要があります。

平均予報プログラムを単一ファイルソースコードプログラムとして実行するには、次のようにします。

$ java --add-modules jdk.incubator.json Weather.java

出力は次のようになります。

WARNING: Using incubator modules: jdk.incubator.json
53.357142857142854

プログラムをjavacでコンパイルし、javaで実行するには、次のようにします。

$ javac --add-modules jdk.incubator.json Weather.java
$ java --add-modules jdk.incubator.json Weather

APIを対話的に試すにはjshellを使用できます。以前と同様に、コマンドラインでインキュベーターモジュールを有効にする必要があります。

$ jshell --add-modules jdk.incubator.json
jshell> import jdk.incubator.json.*
jshell> Json.parse("""
   ...> { "name": "Today", "temperature": 54 }
   ...> """)
$2 ==> {"name":"Today","temperature":54}
jshell> $2.get("temperature").asInt()
$3 ==> 54
jshell>