JavaのJackson APIにおける@JsonRawValueアノテーションの使い方とは？

@JsonRawValueアノテーションは、メソッドとフィールドの両方に適用できるアノテーションで、フィールドやプロパティを宣言された形式のままシリアライズするために使用されます。

通常、Javaクラス内にString型のフィールドがある場合、その値はJSON出力時に引用符（" "）で囲まれます。しかし、該当するフィールドに@JsonRawValueアノテーションを付与すると、Jacksonライブラリはこの引用符を省略し、文字列の内容をそのまま生のJSONとして出力します。

この機能は、すでにJSON形式の文字列として保持しているデータを、エスケープされた文字列ではなくネストされたJSONオブジェクトとして埋め込みたい場合に特に便利です。

構文

@Target(value={ANNOTATION_TYPE,METHOD,FIELD})
@Retention(value=RUNTIME)
public @interface JsonRawValue

上記の定義からも分かるように、このアノテーションはアノテーション型、メソッド、フィールドに対して指定でき、実行時（RUNTIME）に保持されます。

使用例

以下の例では、empAddressフィールドがJSON形式の文字列になっています。@JsonRawValueを付与することで、このJSON文字列はEmployeeオブジェクト全体のJSON出力の一部として、引用符なしでそのまま組み込まれます。

import com.fasterxml.jackson.annotation.JsonRawValue;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;

public class JsonRawValueAnnotationTest {
    public static void main(String args[]) throws JsonProcessingException {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(new Employee());
        System.out.println(jsonString);
    }
}

// Employeeクラス
class Employee {
    public int empId = 115;
    public String empName = "Sai Chaitanya";

    @JsonRawValue
    public String empAddress = "{\"doorNumber\": 1118, \"street\": \"IDPL Colony\", " + "\"city\": \"Hyderabad\"}";
}

実行結果

{
  "empId" : 115,
  "empName" : "Sai Chaitanya",
  "empAddress" : {"doorNumber": 1118, "street": "IDPL Colony", "city": "Hyderabad"}
}

出力結果を見ると、empAddressフィールドが二重引用符で囲まれた文字列ではなく、ネストされたJSONオブジェクトとして出力されていることが確認できます。これが@JsonRawValueアノテーションの効果です。

注意点

@JsonRawValueを使用する際は、対象の文字列が有効なJSONであることを保証する必要があります。無効なJSON文字列を含むフィールドにこのアノテーションを付けると、生成されるJSON全体が不正な形式になってしまうため、注意が必要です。