JSON スキーマをプラットフォームに公開します

目的: JSON スキーマを生成してビルドし、プラットフォームに公開します

複雑さ: 初心者向け

所要時間: 20 分

前提条件: 資格情報を取得し、資格情報を確認します

HERE platform では、他のプラットフォームユーザーとパイプラインの間でデータを共有および転送するために使用されるスキーマを定義できます。スキーマは、カタログレイヤー内のパーティションの構造を記述する関連メッセージのコレクションです。一連のアーティファクトで構成される高レベルの構造体です。

このチュートリアルでは、 JSON スキーマを生成して構築し、プラットフォームに公開する方法を示します。公開されている JSON スキーマに関する情報の取得方法および JSON スキーマのダウンロード方法について説明します。

このチュートリアルでは、次のトピックについて説明します。

JSON スキーマを生成します
JSON スキーマ構造体
JSON スキーマプロジェクトを更新します
JSON スキーマを検証してパッケージ化します
JSON スキーマをプラットフォームに公開します
公開されたスキーマの詳細情報を取得します
スキーマをダウンロードします
Maven 原型を使用します

このチュートリアルを実行するには、 CLI がインストールされ、プラットフォームとリポジトリ資格情報の両方がローカルマシンに設定されている必要があります。

プラットフォーム資格情報が正しく設定されていることを確認するには、「資格情報の確認」チュートリアルで予期した結果が返されていることを確認してください。

JSON スキーマを生成します

JSON スキーマを生成するには、 OLP CLI を使用する方法と Maven 原型を使用する方法の 2 つの方法があります。

このチュートリアルでは、 OLP CLI を使用して JSON スキーマを生成します。

OLP CLI には、スキーマの新しい Maven プロジェクトを生成する olp schema generate コマンドが用意されています。

com.here.platform.tutorial グループ ID と generate_json_schema アーティファクト ID を使用して、現在のディレクトリに JSON スキーマプロジェクトを生成しましょう。

olp schema generate com.here.platform.tutorial generate_json_schema

注

グループ ID には、通常、などのグループ ID に対するチーム / 製品の階層が含まれている必要 com.some-company.automated-driving.schemaがあります。このようにして、異なるチームがスキーマを個別に管理できます。

スキーマをアーティファクトサービスに展開すると、そのグループ ID が組織によって予約され、この場合は他のレルムで再利用できなくなります。したがって com.example、、 com.here.schema、、などの汎用グループ ID の値を指定 com.here.exampleすると、スキーマをアーティファクトサービスリポジトリにアップロードできなくなり、カタログで使用したり、他のユーザーと共有したりできなくなります。

OLP CLI は次の出力を返します。

Schema has been successfully generated in /home/user/generate_json_schema.

JSON スキーマが生成されたら、生成されたプロジェクトの構造を確認できます。

JSON スキーマ構造体

olp schema generate このコマンドは、次の構造のプロジェクトを生成します。

generate_json_schema/
├── ds
│   ├── pom.xml
│   └── src
│       ├── assembly
│       │   └── json.xml
│       └── main
│           └── resources
│               ├── renderers
│               │   └── ReadMe.txt
│               └── ResourcesReadMe.txt
├── json
│   ├── pom.xml
│   └── src
│       ├── assembly
│       │   └── json.xml
│       └── main
│           ├── json
│           │   └── com
│           │       └── here
│           │           └── platform
│           │               └── tutorial
│           │                   └── generate_json_schema
│           │                       └── v1
│           │                           └── generate_json_schema.json
│           └── resources
│               └── description.md
├── pom.xml
└── schema.yml

上の構造から、生成されたプロジェクトにds、json、モジュール、schema.yml および pom.xml ファイルが含まれていることがわかります。

ds このモジュールには、 Data スキーマ（ DS; データセンター）バンドルが含まれています。 ds/src/main/resources/renderers このフォルダーは、 HERE platform に公開された後にスキーマにバンドルされる GeoJSON レンダラーを配置できる場所です。レンダラーは JavaScript で記述され、 HERE platform ポータルのベースマップの上にパーティションデータを表示するために使用されます。詳細については、 GeoJSON レンダラの実装のドキュメントを参照してください。

json このモジュールには、スキーマの JSON メッセージの定義が含まれています。 json/src/main/json/com/here/platform/tutorial/generate_json_schema/v1/generate_json_schema.json このファイルは、データ形式を記述するメインの JSON ファイルです。

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "mainMessageId",
    "definitions": {
        "MainMessage": {
            "type": "object",
            "properties": {
                "lat": {
                    "description": "Latitude",
                    "type": "integer"
                },
                "lon": {
                    "description": "Longitude",
                    "type": "integer"
                }
            },
            "required": [
                "lat", "lon"
            ]
        }
    }

デフォルトのメイン JSON ファイルには、 2 つの必須プロパティ lat および integer タイプの lon を含むデータ形式が記述されています。

メインの JSON ファイルの内容は、 JSON 構文に準拠し、 JSON スキーマを参照するプロパティを含み、そのスキーマ仕様に従う必要があります。これらの要件は、バリデータによって確認されます。

このjson/src/main/resources/description.md ファイルは空のファイルで、スキーマの詳細なドキュメントをマークダウン形式で保存できます。

pom.xml スキーマプロジェクトのルートにあるファイルには name、、 description、などのスキーマの主な詳細情報 versionが含まれています。 pom.xml のデフォルト値を上書きする場合は、olp schema generateコマンドの実行時に、name、descriptionまたは version のパラメータを指定します。

特定のスキーマが依存している他のスキーマの宣言も pom.xml、次の場所に含まれています。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.here.platform.tutorial</groupId>
  <artifactId>generate_json_schema_v1</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>

  <name>JSON Schema</name>
  <description>JSON Schema project for OLP</description>

  <inceptionYear>2022</inceptionYear>

  <distributionManagement>
    <repository>
      <id>HERE_PLATFORM_ARTIFACT</id>
      <layout>here</layout>
      <!-- This custom url serves to invoke the HERE wagon extension that handles OAUTH
           and re-writes Maven URIs for the HERE secure repository.-->
      <url>here+artifact-service://artifact-service</url>
    </repository>
  </distributionManagement>

  <parent>
    <groupId>com.here.platform</groupId>
    <artifactId>sdk-standalone-bom_2.12</artifactId>
    <version>2.43.1</version>
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
    <here.plugin.version>2.1.18</here.plugin.version>
    <artifact.wagon.version>2.0.11</artifact.wagon.version>
  </properties>

  <repositories>
    <repository>
      <id>HERE_PLATFORM_ARTIFACT</id>
      <layout>here</layout>
      <url>here+artifact-service://artifact-service</url>
    </repository>
  </repositories>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-source-plugin</artifactId>
          <version>3.0.1</version>
          <executions>
            <execution>
              <id>attach-sources</id>
              <phase>verify</phase>
              <goals>
                <goal>jar-no-fork</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>1.7</version>
        <inherited>false</inherited>
        <executions>
          <execution>
            <id>copy-schema</id>
            <phase>package</phase>
            <goals>
              <goal>run</goal>
            </goals>
            <configuration>
              <target>
                <echoproperties destfile="${project.build.directory}/build.properties"/>
                <copy file="${project.basedir}/schema.yml" overwrite="true" todir="${project.build.directory}">
                  <filterset begintoken="${" endtoken="}" filtersfile="${project.build.directory}/build.properties"/>
                </copy>
              </target>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>3.0.0-M2</version>
        <executions>
          <execution>
            <id>enforce-property</id>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <requireProperty>
                  <property>project.groupId</property>
                  <message>Project groupId must be specified.</message>
                  <regex>^[a-zA-Z_]+[a-zA-Z0-9_-]*(\.[a-zA-Z0-9_]+[a-zA-Z0-9_-]*)+$</regex>
                  <regexMessage>Project groupId must be specified as reverse domain name.</regexMessage>
                </requireProperty>
              </rules>
              <fail>true</fail>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>1.6</version>
        <inherited>false</inherited>
        <executions>
          <execution>
            <id>attach-artifacts</id>
            <phase>package</phase>
            <goals>
              <goal>attach-artifact</goal>
            </goals>
            <configuration>
              <artifacts>
                <artifact>
                  <file>${project.build.directory}/schema.yml</file>
                  <type>yml</type>
                  <classifier>here-schema</classifier>
                </artifact>
              </artifacts>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>flatten-maven-plugin</artifactId>
        <version>1.1.0</version>
        <configuration>
          <flattenMode>bom</flattenMode>
          <outputDirectory>${project.build.directory}</outputDirectory>
          <flattenedPomFilename>${project.artifactId}-${project.version}.pom</flattenedPomFilename>
        </configuration>
        <executions>
          <execution>
            <id>flatten</id>
            <phase>process-resources</phase>
            <goals>
              <goal>flatten</goal>
            </goals>
          </execution>
          <execution>
            <id>flatten.clean</id>
            <phase>clean</phase>
            <goals>
              <goal>clean</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
    <extensions>
      <extension>
        <groupId>com.here.platform.artifact</groupId>
        <artifactId>artifact-wagon</artifactId>
        <version>${artifact.wagon.version}</version>
      </extension>
    </extensions>
  </build>
  <modules>  
    <module>json</module>
    <module>ds</module>
  </modules>
</project>

schema.yml プロジェクトのルートにあるファイルは、プロジェクトがスキーマプロジェクトであることを示す記述子ファイルです。

name: "${project.name}"
summary: "${project.description}"
layerSchema: true
type: "json"

name および summary のプロパティは、それぞれスキーマの name および description を定義します。デフォルト pom.xml では、これらの値はファイルから取得されます。一般的な目安は、schema.yml ファイル内のこれらのプロパティを変更せず、pom.xml でのみ定義することです。

layerSchema このスキーマをスタンドアロンスキーマとして使用するかどうかを定義します。これをに設定 false すると、スキーマは別のスキーマの依存関係としてのみ使用され、プラットフォームにも OLP CLI にも表示されなくなります。

注

プロジェクトがビルドされ、ルートフォルダーに schema.myl が含まれていない状態で展開された場合、スキーマはプラットフォームに表示されません。

JSON スキーマプロジェクトを更新します

JSON スキーマプロジェクトを作成したら、ニーズを反映してプロジェクトを更新できます。

このチュートリアルで json/src/main/json/com/here/platform/tutorial/generate_json_schema/v1/generate_json_schema.json は、追加のプロパティを提供し documentation 、このスキーマをファイルに記述することで、メインの JSON ファイルを更新します。

まず、メインの JSON ファイルの更新から始めましょう。

zoom_level タイトル、 Zoom Level説明 The relative vertical stacking of multiple points with the same latitude and longitude.、およびタイプを含む新しいオプションプロパティ integerを追加します。

更新されたメイン JSON ファイルは次のようになります。

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "mainMessageId",
    "definitions": {
        "MainMessage": {
            "type": "object",
            "properties": {
                "lat": {
                    "description": "Latitude",
                    "type": "integer"
                },
                "lon": {
                    "description": "Longitude",
                    "type": "integer"
                },
                "zoom_level":{
                    "description": "The relative vertical stacking of multiple points with the same latitude and longitude.",
                    "type": "integer"
                }
               },
            "required": [
                "lat", "lon"
            ]
        }
    }
}

次のステップでは、スキーマに関するドキュメントを追加します。 olp schema generate 新しいスキーマプロジェクトを生成するとき --documentation に、パラメーターで OLP CLI コマンドを使用して、準備したドキュメントを追加できます。ドキュメントをスキーマプロジェクトに渡すには、 2 つの方法があります。外部ドキュメントまたは特定の HERE ドキュメントを参照する場合は、 URL をドキュメントに渡すことができます。また、独自のスキーマの説明を含める場合は、マークダウンファイルへのパスを指定することもできます。

すでに生成されたスキーマプロジェクトがあり、ドキュメントを更新または追加する場合は、json/src/main/resources/description.md ファイルを更新するか、schema.yml ファイルのdocUrl フィールドを追加または更新する必要があります。

json/src/main/resources/description.md 次のドキュメントをファイルに追加します。

This schema was generated for the `Publish JSON schema to the Platform` tutorial.

The main json file describes the data format including the following properties required and optional parameters:

Required properties:

`lat` - the measurement of distance north or south of the Equator.
`lon` - the measurement east or west of the prime meridian.

Optional properties:

`zoom_level` - a number that defines how large or small the contents of a map appear in a map view.

スキーマプロジェクトが更新されたら、プロジェクトを検証してパッケージ化し、変更内容がプロジェクト自体に影響を与えていないことを確認する必要があります。

JSON スキーマを検証してパッケージ化します

OLP CLI に olp schema package は、スキーマプロジェクトをビルドおよび検証するためのコマンドが用意されています。

olp schema package このコマンドは、スキーマプロジェクトを更新し、プラットフォームに展開する前にプロジェクトが有効であることを確認する場合に役立ちます。スキーマを変更しない場合は、このコマンドを使用する必要はありません。

スキーマのビルド中に、プラグインの検証によって、 JSON スキーマプロジェクトに有効なメイン JSON ファイルが含まれていることを確認します。 2 つのJSONSyntax と JSONSchema バリデータがあります。 JSONSyntax バリデータは、ファイルの内容が構文的に正しい JSON であることを確認します。 JSONSchema バリデータは、 JSON に $schema スキーマ仕様を定義し、その仕様に従うプロパティが含まれていることを確認します。 olp schema package コマンドの実行後、json/target/json/META-INF/validation-results.json ファイルに検索できる検証結果。

次の OLP CLI コマンドを使用して、更新された JSON スキーマプロジェクトをビルドしましょう。

olp schema package --input /home/user/generate_json_schema

OLP CLI は次の出力を返します。

Schema has been built successfully.

上記のメッセージは、 JSON スキーマプロジェクトが有効で、メインの JSON メッセージが Maven プラグインによって検証されたことを示しています。次 json/target/json/META-INF/validation-results.json のファイルが生成されます。

{
  "passedValidators" : [ "JSONSyntax", "JSONSchema" ]
}

スキーマプロジェクトに無効な JSON ファイルが含まれている場合、 olp schema package コマンドは次の出力をログファイルへのパスで返します。このログファイルでは、プロジェクトの問題に関する追加情報を見つけることができます。

ERROR: Schema packaging failed.
Log file path: /tmp/olpcli2445382190186474494.log

スキーマプロジェクトでバリデータを無効にするには、 json/pom.xml および ds/pom.xml ファイルで jsonSyntax および jsonSchema を false に設定します。

      <plugin>
        <groupId>com.here.platform.schema.maven_plugins</groupId>
        <artifactId>json-validate-plugin</artifactId>
        <version>${here.plugin.version}</version>
        <executions>
          <execution>
            <id>validate</id>
            <phase>compile</phase>
            <goals>
              <goal>validate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <jsonSyntax>false</jsonSyntax>
          <jsonSchema>false</jsonSchema>
        </configuration>
      </plugin>

注

プラグインを無効にすることはお勧めしません。無効にすると、スキームが正しく動作しなくなる可能性があります。

プロジェクトが検証およびパッケージ化されたら、プラットフォームに公開できます。

スキーマをプラットフォームに公開します

olp schema put OLP CLI コマンドを使用して、 JSON スキーマをプラットフォームに展開してみましょう。

olp schema put --input /home/user/generate_json_schema

OLP CLI は次の出力を返します。


WARNING: Please wait while the command is completed. This may take several minutes.

Schema hrn:here:schema::realm:com.here.tutorial:generate_json_schema_v1:1.0.0 has been created.

Please use 'olp schema show' command to get more information.

スキーマが展開されると、 OLP CLI またはポータルで詳細を確認できます。

公開されたスキーマの詳細情報を取得します

次 olp schema show のコマンドを使用して、展開されたスキーマについての詳細情報を取得しましょう。


olp schema show hrn:here:schema::realm:com.here.test:test_schema_v1:1.0.0

OLP CLI は、次の情報を返します。


Details of the JSON schema:
schema version           1.0.0
artifact id              generate_json_schema_v1
group id                 com.here.platform.tutorial
type                     json
summary                  JSON Schema project for HERE Platform
Schema validation results:
module         JSON syntax                   JSON schema
json           true                          true
ds             true                          true

Artifacts:
hrn:here:artifact::realm:com.here.platform.tutorial:generate_json_schema_v1_json:1.0.0
hrn:here:artifact::realm:com.here.platform.tutorial:generate_json_schema_v1_ds:1.0.0

上記の出力から、展開されたスキーマ、特にスキーマ version、 group id、、についての一般的な情報を取得します。 artifact idスキーマ type、およびスキーマ summary。スキーマの検証結果は、どのプラグインがどのモジュールに使用されたかを示します。出力の最後の情報はアーティファクトです。

JSON スキーマを展開すると、次の 2 つのアーティファクトも展開されます。 _json および _ds。

_json アーティファクトには、スキーマの定義 JSON メッセージを含む zip ファイルが含まれています。アーティファクトには、メインの JSON ファイルと JSON 形式の検証結果が含まれています。オプションのファイルはです description.md。このファイルにはドキュメントが含まれています

注

documentation.md ファイルは docUrl 、ファイルの schema.yml プロパティで上書きできます。に docUrl は高い優先順位が付け docUrl られているため、 documentation.md と docUrl の両方が指定されている場合は、が使用されます。

スキーマの生成時に documentation.md ファイルを上書きするに olp schema generate は、コマンドで --doc-url <URL to the documentation> パラメーターを使用します。

_ds アーティファクトには、 JSON メッセージとデータスキーマ (DS) バンドルを含む zip ファイルが含まれています。 _ds アーティファクトをダウンロードするには、「 Download スキーマ」セクションを参照してください。

スキーマをダウンロードします

_ds JSON メッセージを含むパッケージをダウンロードする olp schema get ために、 OLP CLI にはコマンドが用意されています。


olp schema get hrn:here:schema::realm:com.here.test:test_schema_v1:1.0.0 --output ~/Desktop/ds_package

OLP CLI は次の出力を返します。

Schema package was successfully downloaded to ~/Desktop/ds_package/generated_schema_v1_ds-1.0.0.zip

ダウンロードされた zip ファイルの構造は次のとおりです。

generated_schema_v1_ds-1.0.0/
├── com
│   └── here
│       └── platform
│           └── tutorial
│               └── generate_json_schema
│                   └── v1
│                       └── generate_json_schema.json
├── META-INF
│   ├── layer.manifest.json
│   └── validation-results.json
├── renderers
│   └── ReadMe.txt
└── ResourcesReadMe.txt

上記のプロジェクト構造から _ds 、パッケージにメイン generate_json_schema.json メッセージ、 validation-results.json 検証結果、 layer.manifest.json およびトップレベルメッセージを宣言するマニフェストが含まれていることがわかります。

Maven 原型を使用します

スキーマを生成、検証、アップロードするオプションが追加されました。 JSON スキーマプロジェクトは Maven プロジェクトなので 'Maven のコマンドを使用してスキーマを操作できますこの目的のために、 SDK for Java & Scala では json_archetype 、を使用して JSON スキーマプロジェクトを生成できるを提供しています。

注

以下のコマンドを実行するに Maven は、ローカルマシンにがインストールされている必要があります。

で JSON スキーマプロジェクトを生成 json_archetypeするには、 olp schema generate com.here.platform.tutorial generate_json_schemaJSON スキーマを生成セクションのコマンドと同じように、次の Maven コマンドを使用します。

Linux

窓

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema \
-DarchetypeArtifactId=json_archetype \
-DarchetypeVersion=2.1.129 \
-DartifactId=generate_json_schema \
-Dversion=1.0.0 \
-DgroupId=com.here.platform.tutorial \
-DmajorVersion=1

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema ^
-DarchetypeArtifactId=json_archetype ^
-DarchetypeVersion=2.1.129 ^
-DartifactId=generate_json_schema ^
-Dversion=1.0.0 ^
-DgroupId=com.here.platform.tutorial ^
-DmajorVersion=1

生成されたスキーマを検証してビルドするには、olp schema package コマンドに類似したプロジェクトのルートから mvn install コマンドを使用します。

olp schema put コマンドを使用せ mvn deploy ずにスキーマを展開するには、生成されたプロジェクトのルートからコマンドを実行します。

スキーマを展開したら、このチュートリアルで説明した OLP CLI コマンドを使用して、展開済みのスキーマを検査できます。

結論

このチュートリアルでは、 OLP CLI および Maven を使用して JSON スキーマをプラットフォームに生成、構築、および公開する方法を練習しました。また、 JSON スキーマ構造体と JSON スキーマを操作できる OLP CLI コマンドについても学習しました。

詳細情報

OLP CLI を使用してスキーマを操作する方法の詳細については、『 OLP CLI ガイド』を参照してください。

JSON スキーマをプラットフォームに公開します

JSON スキーマをプラットフォームに公開します

JSON スキーマを生成します

注

JSON スキーマ構造体

注

JSON スキーマプロジェクトを更新します

JSON スキーマを検証してパッケージ化します

注

スキーマをプラットフォームに公開します

公開されたスキーマの詳細情報を取得します

注

スキーマをダウンロードします

Maven 原型を使用します

注

結論

詳細情報

「」に一致する結果は件です

「」に一致する結果はありません

開発者

JSON スキーマ をプラットフォーム に公開します

JSON スキーマ を生成します

注

JSON スキーマ 構造体

注

JSON スキーマ プロジェクトを更新します

JSON スキーマ を検証してパッケージ化します

注

スキーマ をプラットフォーム に公開します

公開されたスキーマ の詳細情報を取得します

注

スキーマ をダウンロードします

Maven 原型を使用します

注

結論

詳細情報

「」に一致する結果は 件です

「」に一致する結果はありません

開発者

JSON スキーマをプラットフォームに公開します

JSON スキーマを生成します

JSON スキーマ構造体

JSON スキーマプロジェクトを更新します

JSON スキーマを検証してパッケージ化します

スキーマをプラットフォームに公開します

公開されたスキーマの詳細情報を取得します

スキーマをダウンロードします

「」に一致する結果は件です