Configure Protobuf Validators

The HERE platform runs validators on the schema protobuf files that you publish to ensure that your protobuf files conform with the platform style. Use the information below to configure the validators as required.

To make changes in the configuration, modify the corresponding section of the proto-validate-plugin.xml.

Proto Module Validators

The chapters below describe all the proto module validators that the platform offers.

Exclude Packages

You can exclude certain packages from validation (such as Google's standard types) by adding an ignorePackage element in the configuration:

<configuration>
  <ignorePackages>
    <ignorePackage>google.protobuf</ignorePackage>
  </ignorePackages>
</configuration>

Backwards Compatibility Validator

This validation plugin ensures that any changes in your protobuf files that occur within a given major version are backwards compatible. If you introduce a breaking change, increment the major version number. The plugin uses semantic version parsing to find the previous release version. The validator retrieves the layer.fds file from the previous artifact in the Artifact Service or HERE Artifactory Repository, if available.

The plugin 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
• All of the above in nested messages

To activate the plugin, use the following configuration:

<configuration>
  <backwardsCompatibility>true</backwardsCompatibility>
</configuration>

File Extensions Validator

This validation plugin ensures that all protobuf files use the .proto file extension. This convention helps guarantee that a user of a protobuf definition knows which documents in .jar files contain message type specifications. This allows the .jar files to contain additional files for future enhancements without breaking existing clients.

To activate the plugin, use the following configuration:

<configuration>
  <fileExtension>true</fileExtension>
</configuration>

Google Style Validator

This check enforces Google's Protobuf Style Guide. This ensures syntactic consistency and minimizes the risk of naming problems, regardless of the specific protobuf tooling used.

To activate this validation plugin, use the following configuration:

<configuration>
  <googleStyle>true</googleStyle>
</configuration>

Major Version in Package Validator

This validation plugin checks that a package name contains the major version of an artifact. For example, version 2.3 should have v2 as part of its package name, such as: com.here.platform.schema.foo.v2. This allows namespacing different protobuf files if projects require access to multiple versions.

To activate this plugin, use the following configuration:

<configuration>
  <majorVersionInPackage>true</majorVersionInPackage>
</configuration>

Data Schema Module Validators

These validators only run for artifacts built by the data schema (ds) module.

Package Consistency Validator

You can configure this validation plugin only for the ds module. It forces the directory tree of the protobuf source files to correspond to the protobuf package declaration in the individual files.

Your applications may use multiple independent protobuf definitions. When generating their own language bindings, the protobuf definitions expect that they can extract all .jar files in a single root directory. In order to avoid filesystem overrides, and assuming that the naming conventions for package namespaces avoid namespace conflicts, this convention avoids filename clashes.

To activate the plugin, use the following configuration:

<configuration>
  <packageConsistency>true</packageConsistency>
</configuration>