スキーマ作成のベストプラクティス

この章では、スキーマを作成および整理するためのベストプラクティスについて説明します。 これらのガイドラインに従うことで、 HERE platform の一般的な使用感を改善し、スキーマをプラットフォームにアップロードするとき、またはローカルにインストールするときのエラーを最小限に抑えることができます。

スキーマの生成

独自 のスキーマを作成するには、 HERE が提供する Maven 原型を使用します。 原型は、スキーマの Scala および Java バインディングを生成するように設定されています。 Java 開発者と Scala 開発者の両方がスキーマを使用できるようにするために、スキーマプロジェクトからバインディングを除外しないことをお勧めします。

スキーマの命名

スキーマの名前を 30 文字未満にしてください。 このようにすると、スキーマ名が 1 行に収まり、 HERE platform ポータルで簡単に読み取ることができます。

スキーマプロジェクトの POM ファイルで、スキーマの名前を指定できます。

スキーマの説明

スキーマの説明に、スキーマの目的を含めます。 また、スキーマが他のスキーマに依存している場合は、これらの依存関係を説明にも一覧表示してください。

スキーマの説明をわかりやすく整理するために、 250 文字を超える長さにしないでください。 これにより、スキーマリスト内の 3 行のテキストに変換されます（ HERE platform ポータル > データ > スキーマを参照）。

スキーマドキュメント

スキーマを開発する場合は、スキーマが適切に文書化されていることを確認してください。 この重要な側面を無視すると、スキーマユーザーの回答を検索するためにコード分析に時間がかかることがあり、フラストレーションが生じる可能性があります。

HERE では、スキーマのドキュメントのソースとして、 Protobuf コードのコメントを使用することをお勧めします。 protoc-gen-doc プラグインを使用 .proto して、ファイル内のコメントからスキーマドキュメントのマークダウンを生成できます。 この方法を使用するには、 Protobuf コードを完全にコメント化する必要があります。

スキーマの原型を使用すると、スキーマのドキュメントを簡単に追加して公開できます。 スキーマプロジェクトを生成した後 proto/src/main/resources/description.md 、スキーマのドキュメントをファイルに保存できます。 スキーマユーザーは description.md 、スキーマが公開された後、 HERE platform ポータルからファイルをダウンロードできます。 このためには 、スキーマの詳細ページで [ ドキュメント ] ボタンをクリックします。

スキーマプロジェクトを生成 の例で作成したスキーマのマークダウンドキュメントを作成しましょう。

まず test_schema/proto/src/main/proto/com/here/example/v1/test_schema.proto 、次のようにコメントをファイルに追加します。

/// The file has a message that describes a geographical point.
syntax = "proto3";

package com.here.example.v1;

/**
* Represents a geographical point.
*/
message Point{
    int32 lat = 1; // The latitude of a point
    int32 lon = 2; // The longitude of a point
}

次に protoc-gen-doc 、ユーティリティを実行して、 Markdown 出力を description.md ファイルに保存します。 これを行うには --doc_opt 、次のようにオプションを適用します。

--doc_opt=markdown,description.md

結果 .md のファイルには、次のような内容が含まれています。

# Protocol Documentation
<a name="top"></a>

## Table of Contents

- [test_schema.proto](#test_schema.proto)
    - [Point](#com.here.example.v1.Point)

- [Scalar Value Types](#scalar-value-types)

<a name="test_schema.proto"></a>
<p align="right"><a href="#top">Top</a></p>

## test_schema.proto
The file has a message that describes a geographical point.

<a name="com.here.example.v1.Point"></a>

### Point
Represents a geographical point.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| lat | [int32](#int32) |  | The latitude of a point |
| lon | [int32](#int32) |  | The longitude of a point |

## Scalar Value Types

| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double |  | double | double | float |
| <a name="float" /> float |  | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool |  | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

description.md サンプルスキーマプロジェクトの既定のファイルを .md 、上記で生成したファイルで置き換え、スキーマで公開できるようになりました。 HTML に変換すると、レンダリングされたスキーマドキュメントは次のようになります。

パッケージの命名

スキーマプロジェクトの生成段階で、スキーマのグループ ID 、アーティファクト ID、およびパッケージ名を定義するように要求されます。 パッケージ名を指定しない場合は、代わりにグループ ID が使用されます。

HERE リソースネームをプラットフォームにアップロードすると、グループ ID とアーティファクト ID を使用してスキーマの HERE リソースネーム （スキーマ）が生成されます。 たとえば 、 HMC Building FootPrints スキーマの HERE リソースネーム はです hrn:here:schema:::com.here.schema.rib:building-footprints_v2:2.13.0。

パッケージ名は、 Protobuf 、 Java 、および Scala のパッケージ名で使用されます。

では groupId、会社の逆のドメイン名を使用します。 また、通常は、にチーム / 製品の階層をgroupId追加する必要があります (例 : com.some-company.automated-driving.schema) 。

アーティファクト ID には、など、プロジェクトにパッケージ化されているスキーマのタイプに固有の名前 building-footprintsを使用します。 アーティファクト ID をできるだけ短くしてください。

また、ご利用のスキーマのメジャーバージョンがパッケージ名に含まれていることを確認してください。 たとえば、バージョン 2.3 v2 は、パッケージ名の一部として次のようにする必要 com.here.platform.schema.foo.v2があります : 。 パッケージ名にメジャーバージョンが含ま れていることは、 Package Validator のメジャーバージョンによってさらに確認されます。

Java パッケージの命名規則に従うことをお勧めします。

バージョン管理

スキーマのバージョンを指定するには、セマンティックバージョニングシステム（ SemVer 2.0.0 ）を使用します。 HERE platform は 、下位互換性検証ツールを実行 して、特定のメジャーバージョン内の Protobuf ファイルの変更内容に下位互換性があることを確認します。

バリデータは、次の変更を探します。

• ファイルが削除されました
• メッセージが削除されました
• フィールドが削除されました
• フィールドタイプが変更されました
• フィールドラベルが変更されました
• フィールド番号が変更されました
• 列挙型 (enum) を削除しました
• 列挙型 (enum) 値が削除されました
• 列挙型 (enum) 値が変更されました
• プロトタイプの構文が変更されました

ファイルの命名

スキーマのすべての Protobuf ファイル .proto に拡張子が付いていることを確認してください。 また、 HERE platform は 、ファイル拡張子検証ツールを実行 して、これを確認します。

.protoファイルの命名には、snake_caseスタイルを使用します。 building_footprints_partition.protoおよびlocations_partition.protoは、 Protobuf ファイル名の正しい表記法の適切な例です。

パッケージの構造化

Protobuf ソースファイルのディレクトリツリーが、個 .proto 々のファイルの Protobuf パッケージ名に対応していることを確認してください。 たとえば proto/src/main/proto/com/here/example/v1/test_schema.proto 、ファイルには次のパッケージ宣言が含まれている必要 com.here.example.v1があります。 詳細について は、「スキーマプロジェクトの生成例」を参照してください。

スキーマで他のスキーマの Protobuf ファイルを使用している場合は import 、個 .proto 々のファイルのステートメントに、インポートされたリソースへのパスが次の形式で含まれていることを確認してください。

パッケージ名の宣言 + imported.posto ファイル名。スラッシュで区切ります

たとえば、以下のコード スニペットを参照してください。

import "com/here/platform/pb/location/optimizedmap/geometry/v2/geometry.proto";

詳細について は、「スキーマの拡張」を参照してください。

プラットフォームは 、パッケージ整合性検証ツールを実行.proto します。この検証ツールでは、 Protobuf ソースファイルのディレクトリツリーが、個々のファイルの Protobuf パッケージ宣言と一致するように強制されます。

コードスタイル処理

Protobuf コードには、 Google の Proto3 言語ガイドを使用してください。 および Google の Protobuf スタイルガイドに従って 、コード内のメッセージ、フィールド、および列挙体の名前を確認します。 HERE platform で は、コード の整合性を保つために Google スタイルバリデータも実行されます。

スキーマが他のスキーマに依存している場合 は、「スキーマの拡張」の章の説明に従って、必要な依存関係のセットを追加します。

データのレンダリング

作成したスキーマに GeoJSON レンダラ プラグインを実装することをお勧めします。 このよう にすると、スキーマを公開してレイヤーで使用した後、 HERE platform ポータルのカタログレイヤーの [ 検査 ] タブでレンダリングされたデータをより的確に把握できます。