1. 概要

JSON-LD は、リンクトデータを表すためのJSONベースのRDF[X40X]形式です。 ハイパーメディア機能を使用して既存のJSONオブジェクトを拡張できます。 言い換えると、マシンが読み取り可能な方法でリンクを含める機能です。

このチュートリアルでは、JSON-LD形式を直接POJOにシリアル化および逆シリアル化するためのJacksonベースのオプションをいくつか見ていきます。 また、例を理解できるようにするJSON-LDの基本的な概念についても説明します。

2. 基本概念

JSON-LDドキュメントを初めて見ると、一部のメンバー名が@文字で始まっていることがわかります。 これらはJSON-LDキーワードであり、それらの値はドキュメントの残りの部分を理解するのに役立ちます。

JSON-LDの世界をナビゲートし、このチュートリアルを理解するには、次の4つのキーワードに注意する必要があります。

  • @context は、ドキュメントの解釈に必要なすべてのKey-Valueマップを含むJSONオブジェクトの説明です。
  • @vocab は、 @context の可能なキーであり、@contextオブジェクトをはるかに短くするためのデフォルトの語彙を導入します。
  • @id は、リソース自体への直接リンクを表すリソースプロパティとして、または任意のフィールドをリンクとしてマークする @type 値として、リンクを識別するためのキーワードです。
  • @type は、リソースレベルまたは@contextのいずれかでリソースタイプを識別するためのキーワードです。 たとえば、埋め込みリソースのタイプを定義します

3. Javaでのシリアル化

続行する前に、以前のチュートリアルを見て、 Jackson ObjectMapper、 Jackson Annotations 、および custom JacksonSerializersのメモリを更新する必要があります。

すでにJacksonに精通しているので、 @JsonProperty アノテーションを使用して、任意のPOJOの2つのカスタムフィールドを@idおよび@typeとして簡単にシリアル化できることに気付くかもしれません。 ただし、 @contextを手動で作成するのは大変な作業であり、エラーが発生する可能性もあります

したがって、このエラーが発生しやすいアプローチを回避するために、@contextの生成に使用できる2つのライブラリを詳しく見てみましょう。 残念ながら、どちらもJSON-LDのすべての機能を生成することはできませんが、それらの欠点についても後で説明します。

4. Jackson-Jsonldによるシリアル化

Jackson-Jsonld は、JSON-LDドキュメントを生成するための便利な方法でPOJOの注釈を有効にするJacksonモジュールです。

4.1. Mavenの依存関係

まず、jackson-jsonldpom.xmlへの依存関係として追加しましょう。

<dependency>
    <groupId>com.io-informatics.oss</groupId>
    <artifactId>jackson-jsonld</artifactId>
    <version>0.1.1</version>
</dependency>

4.2. 例

次に、サンプルPOJOを作成し、@context生成用に注釈を付けましょう。

@JsonldResource
@JsonldNamespace(name = "s", uri = "http://schema.org/")
@JsonldType("s:Person")
@JsonldLink(rel = "s:knows", name = "knows", href = "http://example.com/person/2345")
public class Person {
    @JsonldId
    private String id;
    @JsonldProperty("s:name")
    private String name;

    // constructor, getters, setters
}

私たちが行ったことを理解するために、手順を分解してみましょう。

  • @JsonldResource を使用して、JSON-LDリソースとして処理するためにPOJOにマークを付けました
  • @JsonldNamespace で、使用する語彙の省略形を定義しました
  • @JsonldType で指定したパラメーターは、リソースの@typeになります
  • @JsonldLink アノテーションを使用して、リソースへのリンクを追加しました。 処理されると、 name パラメーターがフィールド名として使用され、@contextへのキーとしても追加されます。 href がフィールド値になり、[ X165X] rel は、@contextにマップされた値になります
  • @JsonldId でマークしたフィールドは、リソースの@idになります
  • @JsonldProperty で指定したパラメーターは、@contextのフィールド名にマップされた値になります。

次に、JSON-LDドキュメントを生成しましょう。

まず、JsonldModuleObjectMapperに登録する必要があります。 このモジュールには、Jacksonが@JsonldResourceアノテーションでマークされたPOJOに使用するカスタムシリアライザーが含まれています。

次に、続行して ObjectMapper を使用して、JSON-LDドキュメントを生成します。

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(new JsonldModule());

Person person = new Person("http://example.com/person/1234", "Example Name");
String personJsonLd = objectMapper.writeValueAsString(person);

その結果、personJsonLd変数には次のものが含まれるはずです。

{
  "@type": "s:Person",
  "@context": {
    "s": "http://schema.org/",
    "name": "s:name",
    "knows": {
      "@id": "s:knows",
      "@type": "@id"
    }
  },
  "name": "Example Name",
  "@id": "http://example.com/person/1234",
  "knows": "http://example.com/person/2345"
}

4.3. 考慮事項

プロジェクトにこのライブラリを選択する前に、次のことを考慮する必要があります。

  • @vocab キーワードを使用することはできないため、 @JsonldNamespace を使用してフィールド名を解決するための省略形を提供するか、完全なInternationalized Resource Identifier(IRI)を書き出す必要があります。 ) 毎回
  • コンパイル時にのみリンクを定義できるため、リンクランタイムを追加するには、リフレクションを使用してアノテーションのパラメーターを変更する必要があります。

5. Hydra-Jsonldによるシリアル化

Hydra-Jsonldは、 Hydra-Java ライブラリのモジュールであり、主にSpringアプリケーションの便利なJSON-LD応答作成を可能にするために構築されています。 Hydra Vocabulary を使用して、JSON-LDドキュメントをより表現力豊かにします。

ただし Hydra-Jsonldモジュールには、Jackson Serializerと、SpringFrameworkの外部でJSON-LDドキュメントを生成するために使用できるいくつかの注釈が含まれています。

5.1. Mavenの依存関係

まず、hydra-jsonldの依存関係をpom.xmlに追加しましょう。

<dependency>
    <groupId>de.escalon.hypermedia</groupId>
    <artifactId>hydra-jsonld</artifactId>
    <version>0.4.2</version>
</dependency>

5.2. 例

次に、@context生成用にPOJOに注釈を付けましょう。

Hydra-Jsonldは、アノテーションを必要とせずに、デフォルトの@contextを自動的に生成します。 デフォルトに満足している場合は、@ idを追加するだけで、有効なJSON-LDドキュメントを取得できます。

デフォルトの語彙はschema.org語彙、 @type Java class 名であり、POJOのパブリックプロパティはすべて結果のJSON-LDドキュメント。

この例では、これらのデフォルトをカスタム値でオーバーライドしましょう。

@Vocab("http://example.com/vocab/")
@Expose("person")
public class Person {
    private String id;
    private String name;

    // constructor

    @JsonProperty("@id")
    public String getId() {
        return id;
    }

    @Expose("fullName")
    public String getName() {
        return name;
    }
}

繰り返しになりますが、関連する手順を詳しく見てみましょう。

  • Jackson-Jsonldの例と比較すると、Spring Framework以外のHydra-Jsonldの制限のため、POJOからknowsフィールドを省略しました。
  • @Vocabアノテーションを使用して優先語彙を設定します
  • クラスで@Exposeアノテーションを使用して、別のリソース@typeを設定します。
  • プロパティに同じ@Exposeアノテーションを使用して、そのマッピングを@contextのカスタム値に設定しました。
  • プロパティから@idを生成するために、Jacksonの@JsonPropertyアノテーションを使用しました

次に、ObjectMapperに登録できるJacksonModuleのインスタンスを構成しましょう。 JacksonHydraSerializerをBeanSerializerModifierとして追加して、シリアル化されているすべてのPOJOに適用できるようにします

SimpleModule getJacksonHydraSerializerModule() {
    return new SimpleModule() {
        @Override
        public void setupModule(SetupContext context) {
            super.setupModule(context);

            context.addBeanSerializerModifier(new BeanSerializerModifier() {
                @Override
                public JsonSerializer<?> modifySerializer(
                  SerializationConfig config, 
                  BeanDescription beanDesc, 
                  JsonSerializer<?> serializer) {
                    if (serializer instanceof BeanSerializerBase) {
                        return new JacksonHydraSerializer((BeanSerializerBase) serializer);
                    } else {
                        return serializer;
                    }
                }
            });
        }
    };
}

それでは登録しましょうモジュール ObjectMapper そしてそれを使用しますまた、null以外の値のみを含めるようにObjectMapperを設定する必要があります有効なJSON-LDドキュメントを作成するには:

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(getJacksonHydraSerializerModule());
objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

Person person = new Person("http://example.com/person/1234", "Example Name");

String personJsonLd = objectMapper.writeValueAsString(person);

これで、personJsonLd変数に次のものが含まれるはずです。

{
  "@context": {
    "@vocab": "http://example.com/vocab/",
    "name": "fullName"
  },
  "@type": "person",
  "name": "Example Name",
  "@id": "http://example.com/person/1234"
}

5.3. 考慮事項

Spring Frameworkの外部でHydra-Jsonldを使用することは技術的には可能ですが、元々はSpring-HATEOASで使用するために設計されました。 その結果、Jackson-Jsonldで見たように、注釈付きのリンクを生成する方法はありません。 一方、一部のSpring固有のクラスでは自動的に生成されます。

プロジェクトにこのライブラリを選択する前に、次のことを考慮する必要があります。

  • Spring Frameworkで使用すると、追加機能が有効になります
  • Spring Frameworkを使用していない場合、リンクを生成する簡単な方法はありません。
  • @vocabの使用を無効にすることはできません。オーバーライドすることしかできません。

6. Jsonld-JavaとJacksonによる逆シリアル化

Jsonld-Java は、JSON-LD 1.0仕様とAPIのJava実装であり、残念ながら最新バージョンではありません。

1.1仕様バージョンの実装については、 TitaniumJSON-LDライブラリをご覧ください。

JSON-LDドキュメントを逆シリアル化するには、圧縮と呼ばれるJSON-LD API機能を使用して、ObjectMapperを使用してPOJOにマップできる形式に変換しましょう。

6.1. Mavenの依存関係

まず、 jsonld-javaの依存関係を追加しましょう。

<dependency>
    <groupId>com.github.jsonld-java</groupId>
    <artifactId>jsonld-java</artifactId>
    <version>0.13.0</version>
</dependency>

6.2. 例

このJSON-LDドキュメントを入力として使用してみましょう。

{
  "@context": {
    "@vocab": "http://schema.org/",
    "knows": {
      "@type": "@id"
    }
  },
  "@type": "Person",
  "@id": "http://example.com/person/1234",
  "name": "Example Name",
  "knows": "http://example.com/person/2345"
}

簡単にするために、inputJsonLdというString変数にドキュメントのコンテンツがあると仮定します。

まず、圧縮してStringに変換し直してみましょう。

Object jsonObject = JsonUtils.fromString(inputJsonLd);
Object compact = JsonLdProcessor.compact(jsonObject, new HashMap<>(), new JsonLdOptions());
String compactContent = JsonUtils.toString(compact);
  • Jsonld-Javaライブラリの一部であるJsonUtils、のメソッドを使用して、JSON-LDオブジェクトを解析および記述できます。
  • compact メソッドを使用する場合、2番目のパラメーターとして空のMapを使用できます。 このように、圧縮アルゴリズムは、キーがIRIフォームに解決される単純なJSONオブジェクトを生成します

compactContent変数には次のものが含まれている必要があります。

{
  "@id": "http://example.com/person/1234",
  "@type": "http://schema.org/Person",
  "http://schema.org/knows": {
    "@id": "http://example.com/person/2345"
  },
  "http://schema.org/name": "Example Name"
}

次に、このようなドキュメント構造に合うように、Jacksonアノテーションを使用してPOJOを調整しましょう。

@JsonIgnoreProperties(ignoreUnknown = true)
public class Person {
    @JsonProperty("@id")
    private String id;
    @JsonProperty("http://schema.org/name")
    private String name;
    @JsonProperty("http://schema.org/knows")
    private Link knows;

    // constructors, getters, setters

    public static class Link {
        @JsonProperty("@id")
        private String id;

        // constructors, getters, setters
    }
}

そして最後に、JSON-LDをPOJOにマッピングしましょう。

ObjectMapper objectMapper = new ObjectMapper();
Person person = objectMapper.readValue(compactContent, Person.class);

7. 結論

この記事では、POJOをJSON-LDドキュメントにシリアル化するための2つのJacksonベースのライブラリと、JSON-LDをPOJOに逆シリアル化する1つの方法について説明しました。

強調したように、両方のシリアル化ライブラリには、使用する前に考慮する必要のある欠点があります。これらのライブラリが提供できるよりも多くのJSON-LDの機能を使用する必要がある場合は、 JSON-LD出力形式のRDFライブラリ。

いつものように、ソースコードはGitHubにあります。