Working with Protobuf Schemas

Protocol buffers (protobufs) are a language-neutral, platform-neutral extensible mechanism for serializing structured data in proto language. In the context of the HERE platform, protobufs are used to store data in a catalog layer. The Data Validation Library reads data from one or more catalog layers and writes the output to one or more layers.

Define Your Own Protobuf Schema

The data that your test application reads can be of various types depending on the test case. However, the results provided by the Validator, Analzyer, or Assessor, contain two parts:

• A common part -- predefined by the Data Validation Library's core protobuf schema
• An application-specific part -- tailored to your test case

In other words, the Validator typically has test results: PASS, FAIL, and so on, as defined in the common part. But, if a test has failed, you might want to include additional information on the error, such as the partition or geocoordinates.

For the Analyzer, you might want to include additional information on the error, such as thresholds or limits that were not met, or some aggregated error messages for diagnostics.

For the Assessor, you may want to have a pass-or-fail result only. If you do not require additional information for this phase, you can directly use the pre-defined core protobuf schema provided by the validation library.

For more information on defining your own protobuf schema, see "Create and Extend Schemas" in the SDK Developer Guide.

Use The Predefined Core Protobuf Schema

The Data Validation Library offers a core protobuf package with protobuf schema definitions for:

• TestResult: PASS, FAIL, ERROR, INSUFFICIENT_CONTEXT, INCOMPLETE_ATTRIBUTION, SKIPPED
• TestMetricSeverity: NONE, LOW, MEDIUM, CRITICAL
• TestAssessment: PASS, FAIL

To use the bindings for these definitions in your application, make sure you define your dependencies correctly for Java or Scala:

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>testing_v1_java</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>
<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>metrics_v1_java</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>
<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>assessment_v1_java</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

"com.here.platform.schema.data.validation.core" % "testing_v1_java" % "0.0.2",
"com.here.platform.schema.data.validation.core" % "metrics_v1_java" % "0.0.2",
"com.here.platform.schema.data.validation.core" % "assessment_v1_java" % "0.0.2",

"com.here.platform.schema.data.validation.core" % "testing_v1_scala" % "0.0.2",
"com.here.platform.schema.data.validation.core" % "metrics_v1_scala" % "0.0.2",
"com.here.platform.schema.data.validation.core" % "assessment_v1_scala" % "0.0.2",

To create your own protobuf schema using the Data Validation Library core protobuf sources you need to have a dependency to the Data Validation Library core component in all the pom.xml files of your proto project.

Depending on which processor you want to use, add one or more of the following <dependency> blocks for the Testing, Metrics, or Assessment processors:

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>testing_v1_proto</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>metrics_v1_proto</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>assessment_v1_proto</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

Deploy Your Own Protobuf Schema

If your schema was created using the HERE Schema Archetypes, run mvn clean deploy to deploy it.

Use Your Protobuf Schema In Your Test Application

To use your protobuf schema in your application, you need to add a dependency to the protobuf bindings for your application's language. The following code snippets illustrate this step, particularly for the validator processor. However, these code snippets also apply to the analyzer and assessor processors as well.

The code snippets are almost identical for Java and Scala; ensure that you choose the correct package name.

For Java you should add:

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>testing_v1_java</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

"com.here.platform.schema.data.validation.core" % "testing_v1_java" % "0.0.2",

For Scala you should add:

<dependency>
  <groupId>com.here.platform.schema.data.validation.core</groupId>
  <artifactId>testing_v1_scala</artifactId>
  <version>0.0.2</version>
  <type>zip</type>
</dependency>

"com.here.platform.schema.data.validation.core" % "testing_v1_scala" % "0.0.2",