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.0.0 \
-Dversion=1.0.0 \
-DmajorVersion=1
mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema ^
-DarchetypeArtifactId=project_archetype ^
-DarchetypeVersion=2.0.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.0.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.0.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;
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>
<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>1.0.15</here.plugin.version>
<artifact.wagon.version>2.0.0</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.
Note
The schema won't be visible on the platform if the project was built and deployed without the schema.yml
included in the root folder.
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.