Best Practices for Schema Creation

This chapter describes some of the best practices for creating and organizing your schemas. Following these guidelines helps improve your HERE platform experience in general and minimize a number of errors when you upload your schema to the platform or install it locally.

Schema Generation

Use HERE-provided Maven Archetype for creating your own schemas. The archetype has been configured in such a way that it generates Scala and Java bindings for schemas. It is recommended not to exclude any of the bindings from a schema project to enable both Java and Scala developers to use your schemas.

Schema Naming

Try to make the names of your schemas not longer than 30 characters. This way, your schema name fits in one line and is easy to read in the HERE platform portal.

You can specify the name of your schema in the schema project POM file.

Schema Descriptions

In a schema description, include the purpose of your schema. Also, if your schema is dependent on other schemas, try to list these dependencies in the description as well.

To keep your schema descriptions neat and readable, do not make them longer than 250 characters. This translates into 3 lines of text in the schemas list (HERE platform portal > Data > Browse schemas).

Schema Documentation

When developing a schema, make sure that your schema is well documented. Ignoring this important aspect may result in frustration and extra time spent on code analysis in search of answers for your schema users.

HERE recommends using comments in your protobuf code as a source for your schema documentation. You can use the protoc-gen-doc plugin to generate Markdown schema documentation from comments in your .proto files. To use this approach, you should thoroughly comment out your protobuf code.

Schema archetypes allow you to easily add and publish your schema documentation. After generating a schema project, you can put documentation for your schema in the proto/src/main/resources/description.md file. Schema users can then download the description.md file from the HERE platform portal once the schema is published. For this, users click the Documentation button on the schema details page.

Let's create Markdown documentation for the schema that was created in the Generate a Schema Project example.

First, let's add comments to the test_schema/proto/src/main/proto/com/here/example/v1/test_schema.proto file as shown below:

/// 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
}

Next, let's run the protoc-gen-doc utility and save the Markdown output into the description.md file. To do this, you can apply the --doc_opt option as follows:

--doc_opt=markdown,description.md

The resulting .md file contains the content as below:

# 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 |

You can now substitute the default description.md file from the example schema project with the .md file generated above and publish it with the schema. Once converted to HTML, the rendered schema documentation may look as below:

Schema Documentation
Schema Documentation

Package Naming

You are prompted to define the group ID, artifact ID, and package name for your schema at the stage of generating a schema project. If you don't specify any package name, the group ID is used instead.

Group ID and artifact ID are used to generate the schema's HERE Resource Name (HRN) once you upload your schema to the platform. For example, the HRN of the HMC Building Footprints schema is hrn:here-cn:schema:::com.here.schema.rib:building-footprints_v2:2.13.0.

The package name is used in the protobuf, Java, and Scala package names.

For groupId, use your company's reversed domain name. In addition, you should usually add a team/product hierarchy to the groupId, for example, com.some-company.automated-driving.schema.

Note

When a schema is being deployed to the Artifact Service - its groupId is being reserved by the organization of the schema owner. Users from other organizations will not . be able to deploy their schemas if they share the same groupId. So, specifying generic groupId values like com.example, com.here.schema, com.here.example may make it impossible to upload the schema to the Artifact Service repository and thus using it in catalogs or sharing it with other users.

For artifact ID, use a name specific to the type of schemas packaged in the project, such as building-footprints. Try to keep the artifact ID as short as possible.

Also, make sure that the major version of your schema is included in the name of your package. For example, version 2.3 should have v2 as part of its package name, such as: com.here.platform.schema.foo.v2. The presence of the major version in the package name is additionally verified by the Major Version in Package Validator.

We recommend following Java package naming conventions.

Versioning

Use the semantic versioning system (SemVer 2.0.0) to designate the version of your schema. The HERE platform runs the Backwards Compatibility Validator to check that any changes in your protobuf files within a given major version are backwards compatible.

The validator looks for the following changes:

  • File removed
  • Message removed
  • Field removed
  • Field type changed
  • Field label changed
  • Field number changed
  • Enum removed
  • Enum value removed
  • Enum value changed
  • Proto syntax changed

File Naming

Make sure that all your protobuf files in the schema have the .proto extension. The HERE platform additionally runs the File Extensions Validator to check this.

For naming .proto files, use the snake_case style. building_footprints_partition.proto and locations_partition.proto are good examples of how proper protobuf file names should look like.

Package Structuring

Make sure that the directory tree of the protobuf source files corresponds to the protobuf package name in the individual .proto files. For example, the proto/src/main/proto/com/here/example/v1/test_schema.proto file must contain the following package declaration: com.here.example.v1. For more information, see Example Schema Project Generation.

If your schema uses protobuf files from other schemas, make sure that the import statement in an individual .proto file contains the path to the imported resource in the following format:

package name declaration + imported .proto file name, separated by forward slashes

For example, see the code snippet below:

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

For more information, see Extend a Schema.

The platform runs the Package Consistency Validator that forces the directory tree of the protobuf source files to match the protobuf package declaration in individual .proto files.

Code Styling

Use the Google's Proto3 Language Guide for your protobuf code. And follow the Google's Protobuf Style Guide for the names of messages, fields, and enums in your code. The HERE platform additionally runs the Google Style Validator to ensure code consistency.

If your schema is dependent on other schemas, add a set of required dependencies as described in the Extend a Schema chapter.

Data Rendering

It is recommended that you implement a GeoJSON rendering plugin for the schemas that you create. This way, after publishing the schema and using it with a layer, you can better understand your data rendered on the Inspect tab of the catalog layer in the HERE platform portal.

results matching ""

    No results matching ""