Define a Data Schema

If your schema does not incorporate any elements from other schemas, you need to define only those protobuf definitions that are located in the proto module. You can break down your definitions into multiple files or import other protobuf files.

For more details, see the Protocol Buffers Language Guide.

Example Schema Project Definition

Based on the schema project generated in the previous chapter, let's add an altitude field to our schema. For this, edit the proto/src/main/proto/com/here/example/v1/test_schema.proto file as follows:

syntax = "proto3";

package com.here.example.v1;

// MainProtobufMessage is a placeholder, and its value must match the package/messagename in the
// mainMessage tag of the layer-manifest-plugin in the schema_ds module.
message MainProtobufMessage {
    int32 lat = 1;
    int32 lon = 2;
    int32 alt = 3;
}

To verify the change, enter the following command:

mvn package

Extend a Schema

By extending a schema, you avoid having to define data structures that already exist in other schemas. If you need to make a schema dependent on another schema, add the required dependencies as described below:

1. For the proto module, add the dependency definition in the POM file. The dependency must be on another proto module packaged with an archetype-generated project.
2. For the java module, add the dependency definition in the POM file. The dependency must be on another java module packaged with an archetype-generated project.
3. For the scala module, add the dependency definition in the POM file. The dependency must be on another scala module packaged with an archetype-generated project.
4. For the scala_2.12 module, add the dependency definition in the POM file. The dependency must be on another scala_2.12 module packaged with an archetype-generated project.
5. Import and use the protobuf definitions from the dependency in your proto module definitions where it's needed.

The project is now ready, and you can define your custom data structure.

Example Schema Project Extension

Based on the schema project generated above, let's use the HERE-provided HMC Address Attribution (v2.62.0) schema to extend your schema by adding a postal code field. To find this schema, in the HERE platform portal, select the Data tab and click Browse schemas.

Follow the steps below to extend the schema:

1. Add the following dependency to the proto/pom.xml file:

   <dependency>
     <groupId>com.here.schema.rib</groupId>
     <artifactId>address-attributes_v2_proto</artifactId>
     <version>2.58.2</version>
     <type>zip</type>
   </dependency>
   

2. Add the following dependency to the java/pom.xml file:

   <dependency>
     <groupId>com.here.schema.rib</groupId>
     <artifactId>address-attributes_v2_java</artifactId>
     <version>2.58.2</version>
     <type>jar</type>
   </dependency>
   

3. Add the following dependency to the scala/pom.xml file:

   <dependency>
     <groupId>com.here.schema.rib</groupId>
     <artifactId>address-attributes_v2_scala</artifactId>
     <version>2.58.2</version>
     <type>jar</type>
   </dependency>
   

4. Add the following dependency to the scala_2.12/pom.xml file:

   <dependency>
     <groupId>com.here.schema.rib</groupId>
     <artifactId>address-attributes_v2_scala_2.12</artifactId>
     <version>2.58.2</version>
     <type>jar</type>
   </dependency>
   

5. Edit the proto/src/main/proto/com/here/example/v1/test_schema.proto file as follows:

   syntax = "proto3";
   
   package com.here.example.v1;
   
   // Declare any dependent resources in the main POM file and add the import statements here:
   import "com/here/schema/rib/v2/address_attributes.proto";
   
   // MainProtobufMessage is a placeholder, this value must match the package/messagename in
   // the mainMessage tag of the layer-manifest-plugin in the schema_ds module.
   message MainProtobufMessage {
       int32 lat = 1;
       int32 lon = 2;
       com.here.schema.rib.v2.PostalCode postal_code = 3;
   }
   

6. To verify the change, run the following command:

   mvn package