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