Generate a Schema Project

To generate a new schema project, run mvn archetype:generate with the following parameters:

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema \
                       -DarchetypeArtifactId=project_archetype \
                       -DarchetypeVersion=2.1.0 \
                       -Dversion=1.0.0 \
                       -DmajorVersion=1

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema ^
                       -DarchetypeArtifactId=project_archetype ^
                       -DarchetypeVersion=2.1.0 ^
                       -Dversion=1.0.0 ^
                       -DmajorVersion=1

Define the following Maven Archetype parameters when prompted:

• groupId: Reversed Internet domain name, such as com.your-domain.some-product.schema.

  Note

  The groupId should usually include a team/product hierarchy to the groupId, such as com.some-company.automated-driving.schema. This way, different teams can manage their schemas independently.

  When you deploy a schema to the Artifact Service, its groupId is being reserved by your organization, and no other realm can reuse it in this case. So, specifying generic groupId values like com.example, com.here.schema, and 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.

• artifactId: Identifier specific to the schema types packaged in the project, such as road_topology. The archetype appends the major version of your data schema to the artifactId, such as road_topology_v1.

• version: Version of your schema project. Use the three-part semantic versioning according to the SemVer 2.0.0 standard, optionally followed by a revision.

• package: Identifier used in the protobuf, Java, and Scala package names. If you do not specify this value, the groupId is used.

• majorVersion: Major version of your data schema contained in the package name. With this parameter, you can use multiple major schema versions simultaneously.

The new schema project contains the following modules:

• proto

  Contains protocol buffer definitions. You can extend existing files or place additional protobuf files in the same location.

  You can also provide detailed documentation for your schema in the proto/src/main/resources/description.md file. Schema users can later download the description.md file from the HERE platform portal once the schema is published to the platform.

• java

  Generates Java source code from the definitions in the proto module and compiles classes for serializing and deserializing protocol buffer messages in Java applications. You can add the resulting artifact as a dependency in a Maven build. Note that only classes for the project-local definitions are compiled, which helps manage dependencies.

• scala

  Generates Scala source code from the definitions in the proto module and compiles classes for serializing and deserializing protocol buffer messages in Scala applications. You can add the resulting artifact as a dependency in a Maven build. Note that only classes for the project-local definitions are compiled, which helps manage dependencies.

• ds

  Contains a data schema (ds) bundle that is used to dynamically decode partitions. You can place a GeoJSON renderer for the schema here. The HERE platform portal uses a renderer to visualize partition data on top of the base map.

Example Schema Project Generation

The commands below illustrate how to generate a sample schema project:

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema \
                       -DarchetypeArtifactId=project_archetype \
                       -DarchetypeVersion=2.1.0 \
                       -DartifactId=test_schema \
                       -Dversion=1.0.0 \
                       -Dpackage=com.here.example \
                       -DmajorVersion=1

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema ^
                       -DarchetypeArtifactId=project_archetype ^
                       -DarchetypeVersion=2.1.0 ^
                       -DartifactId=test_schema ^
                       -Dversion=1.0.0 ^
                       -Dpackage=com.here.example ^
                       -DmajorVersion=1

After running the command and providing the groupId value, the following schema definition structure is generated:

├───ds
│   └───src
│       ├───assembly
│       └───main
│           └───resources
│               └───renderers
├───java
├───proto
│   └───src
│       ├───assembly
│       └───main
│           ├───proto
│           │   └───com
│           │       └───here
│           │           └───example
│           │               └───v1
│           └───resources
├───scala
├───schema.yml
└───pom.xml

The proto/src/main/proto/com/here/example/v1/test_schema.proto file contains the following content:

syntax = "proto3";

package com.here.example.v1;

// Declare any dependent resources in the main POM file and add the import statements here:
// import "com/company/dependentGroupId/filename.proto";

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

The pom.xml file in the schema project root сontains the main schema details, such as name, description, version, and the like. Declarations of other schemas that the given schema is dependent on are also included in pom.xml. See below for a sample pom.xml body:

  ...

  <artifactId>test_schema_v1</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>

  <name>Schema</name>
  <description>Schema project for OLP</description>

  <distributionManagement>
    <repository>
      <id>HERE_PLATFORM_ARTIFACT</id>
      <layout>here</layout>
      <!-- This custom url serves to invoke the HERE wagon extension that handles OAUTH
           and re-writes Maven URIs for the HERE secure repository.-->
      <url>here+artifact-service://artifact-service</url>
    </repository>
  </distributionManagement>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
    <protobuf.version>3.6.0</protobuf.version>
    <scala.version>2.11.8</scala.version>
    <scala.compat.version>2.11</scala.compat.version>
    <here.plugin.version>2.1.0</here.plugin.version>
    <artifact.wagon.version>2.0.5</artifact.wagon.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.google.protobuf</groupId>
        <artifactId>protobuf-java</artifactId>
        <version>${protobuf.version}</version>
        <scope>compile</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  ...

The schema.yml is a descriptor file that indicates that your project is a schema project. See below for a sample schema.yml body:

#
# Marker file to indicate this is a schema project
#
name: "${project.name}"
summary: "${project.description}"

# Set this to false if the schema is meant only for use as a component of other schemas
layerSchema: true

The name and summary properties define the name and description of your schema respectively. By default these values are taken from pom.xml file. The general rule of thumb is not to change these properties in the schema.yml file and define them only in pom.xml. The layerSchema property defines whether this schema should be used as a standalone schema. Setting it to false means that the schema will only be used as a dependency for another schema and will not be visible on the platform nor listed via OLP CLI.

The proto/src/main/resources/description.md file is an empty file where you put detailed schema documentation in the Markdown format.

The ds/src/main/resources/renderers folder is the place where you can put a GeoJSON renderer that becomes bundled with your schema once published to the HERE platform. The renderer is written in JavaScript and is used for visualizing partition data on top of the base map in the HERE platform portal. For more information, see the Implement a GeoJSON Renderer chapter.