Migrate an Existing Schema Project

For projects created using schema archetype 0.6.4 or earlier: to publish and share your schema, you must update the schema project to the latest version by following these instructions:

1. Add the following sections to the pom.xml located in your project's root directory:

   • project node:

     <distributionManagement>
       <repository>
         <id>HERE_PLATFORM_ARTIFACT</id>
         <layout>default</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>
     
     <repositories>
       <repository>
         <id>HERE_PLATFORM_ARTIFACT</id>
         <layout>default</layout>
         <url>here+artifact-service://artifact-service</url>
       </repository>
     </repositories>
     

   • project > properties node:

     <protobuf.version>3.6.0</protobuf.version>
     <here.plugin.version>2.1.8</here.plugin.version>
     <artifact.wagon.version>2.0.5</artifact.wagon.version>
     

   • project > build node:

     <extensions>
       <extension>
         <groupId>com.here.platform.artifact</groupId>
         <artifactId>artifact-wagon</artifactId>
         <version>${artifact.wagon.version}</version>
       </extension>
     </extensions>
     

   • project > build > plugins node:

     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-antrun-plugin</artifactId>
       <version>1.7</version>
       <executions>
         <execution>
           <id>test-schema</id>
           <phase>package</phase>
           <goals>
             <goal>run</goal>
           </goals>
           <configuration>
             <exportAntProperties>true</exportAntProperties>
             <target>
               <condition property="skipSchemaAttach" value="false" else="true">
                 <available file="${project.basedir}/schema.yml"/>
               </condition>
             </target>
           </configuration>
         </execution>
         <execution>
           <id>copy-schema</id>
           <phase>package</phase>
           <goals>
             <goal>run</goal>
           </goals>
           <configuration>
             <skip>${skipSchemaAttach}</skip>
             <target>
               <echoproperties destfile="${project.build.directory}/build.properties"/>
               <copy todir="${project.build.directory}" file="${project.basedir}/schema.yml" overwrite="true">
                 <filterset begintoken="${" endtoken="}" filtersfile="${project.build.directory}/build.properties"/>
               </copy>
             </target>
           </configuration>
         </execution>
       </executions>
     </plugin>
     <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>build-helper-maven-plugin</artifactId>
       <version>1.6</version>
       <configuration>
         <skipAttach>${skipSchemaAttach}</skipAttach>
       </configuration>
       <executions>
         <execution>
           <id>attach-artifacts</id>
           <phase>package</phase>
           <goals>
             <goal>attach-artifact</goal>
           </goals>
           <configuration>
             <artifacts>
               <artifact>
                 <file>${project.build.directory}/schema.yml</file>
                 <type>yml</type>
                 <classifier>here-schema</classifier>
               </artifact>
             </artifacts>
           </configuration>
         </execution>
       </executions>
     </plugin>
     

2. Update proto/pom.xml as follows:

   • plugin > executions > execution > phase element in layer-manifest-plugin, proto-validate-plugin, and maven-assembly-plugin Maven plugin definitions from package to compile:

     <phase>compile</phase>
     

   • project > build > plugins node:

     <plugin>
       <artifactId>maven-jar-plugin</artifactId>
       <executions>
           <execution>
             <id>default-jar</id>
             <phase>package</phase>
             <configuration>
               <classifier>empty</classifier>
             </configuration>
           </execution>
         </executions>
     </plugin>
     

3. Update java/pom.xml as follows:

   • plugin > version element in the protoc-jar-maven-plugin Maven plugin definition:

     <version>3.6.0.1</version>
     

   • plugin > executions > execution > configuration > protocVersion element in the protoc-jar-maven-plugin Maven plugin definition:

     <protocVersion>3.6.0</protocVersion>
     

4. Update scala/pom.xml as follows:

   • plugin > executions > execution > configuration > protocVersion element in the protoc-scala-maven-plugin Maven plugin definition:

     <protocVersion>3.6.0</protocVersion>
     

   • scalapb-runtime_2.11 definition in the dependencies > dependency block:

     <dependency>
       <groupId>com.thesamet.scalapb</groupId>
       <artifactId>scalapb-runtime_2.11</artifactId>
       <version>0.8.0</version>
     </dependency>
     

5. Create a schema marker file schema.yml in the root folder of your schema project with the following content:

   #
   # 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
   # Note: When the layerSchema property is set to false, the schema won't be visible in the
   # schema list in the HERE platform portal or via OLP CLI
   
   layerSchema: true
   

Note that the project.name and project.description values are taken from the POM file. These values identify your schema on the platform. For more information, see the Publish a Schema Artifact chapter.

If the schema project contains only one schema, you need to create a schema.yml file in the main directory on the same level as the POM file. If it is a multischema project, each with its own modules, then you need to create different schema.yml files in the root of each module.

Upgrading schema plugins from v1.x.x to v2.x.x

HERE Maven plugins v2.1.8 include bug fixes that are not backwards compatible with schemas v1.x.x and earlier. Among the fixes is the possibility to structure the schema proto files in custom directories (including placing them directly into the proto > src > main > proto directory) when Package Consistency validator is disabled.

In order to use the latest HERE Maven plugins you must upgrade your schema project as per instructions below:

1. Update java/pom.xml as follows:

   • plugin > executions > execution > configuration element in the protoc-jar-maven-plugin Maven plugin definition:

     Replace content of inputDirectories tag with the following configuration:

     <inputDirectories>
       <include>${project.build.directory}/proto</include>
     </inputDirectories>
     

     Replace content of includeDirectories tag with the following configuration:

     <includeDirectories>
       <include>${project.build.directory}/proto</include>
       <include>${project.build.directory}/proto-lib</include>
     </includeDirectories>
     

2. Update scala/pom.xml as follows:

   • plugin > executions > execution > configuration element in the protoc-scala-maven-plugin Maven plugin definition:

     Replace content of inputDirectories tag with the following configuration:

     <inputDirectories>
       <include>${project.build.directory}/proto</include>
     </inputDirectories>
     

     Replace content of includeDirectories tag with the following configuration:

     <includeDirectories>
       <include>${project.build.directory}/proto-lib</include>
     </includeDirectories>
     

3. Add the following configuration to assembly > fileSets section in ds/src/assembly/proto.xml:

   <!-- protos from dependencies -->
   <fileSet>
     <directory>${project.build.directory}/proto-lib</directory>
     <outputDirectory/>
   </fileSet>
   

Skipping the above-mentioned updates may lead to build-time errors.

Adding scala 2.12 module to your schema project

In order to add the scala 2.12 module to your schema, you need to upgrade the HERE Maven plugins version in your project to v2.1.8 or later. For upgrade instructions from v1.x.x to v2.x.x, see the previous chapter.

Follow these steps to add the new scala_2.12 module to your project:

1. Create a new module in your schema:

   • Create a scala_2.12 directory in your root project folder.
   • Copy the scala 2.11 Maven module configuration from scala/pom.xml to scala_2.12/pom.xml.

   • Update the modules section of the pom.xml file in your root project directory to include the new module. Example:

     <modules>
       <module>proto</module>
       <module>java</module>
       <module>scala</module>
       <module>scala_2.12</module>
       <module>ds</module>
     </modules>
     

2. Update scala_2.12/pom.xml as follows:

   • Rename artifactId from <schema-name>_scala_2.11 or <schema-name>_scala to <schema-name>_scala_2.12 where <schema-name> is the name of your schema. Please note that no changes should be made in scala/pom.xml in order for your schema to be backwards compatible with the previous versions.
   • Update name and description appropriately for the new module.

   • Update the scala-library version in dependencies section to 2.12.x as shown in the example below:

     <dependency>
       <groupId>org.scala-lang</groupId>
       <artifactId>scala-library</artifactId>
       <version>2.12.12</version>
     </dependency>
     

   • In the dependencies section, replace the scalapb-runtime_2.11dependency with the scalapb-runtime_2.12 one as follows:

     <dependency>
       <groupId>com.thesamet.scalapb</groupId>
       <artifactId>scalapb-runtime_2.12</artifactId>
       <version>0.8.0</version>
       <exclusions>
         <exclusion>
           <groupId>org.scala-lang</groupId>
           <artifactId>scala-library</artifactId>
         </exclusion>
       </exclusions>
     </dependency>
     

   • In the build > plugins > protoc-scala-maven-plugin plugin:

     • Rename the artifactId of the protoc-scala-maven-plugin to protoc-scala-maven-plugin_2.12.

     • Remove the dependencies section of the plugin if it exists. The final protoc-scala-maven-plugin_2.12 configuration may look like this:

       <plugin>
         <groupId>com.here.platform.schema.maven_plugins</groupId>
         <artifactId>protoc-scala-maven-plugin_2.12</artifactId>
         <version>${here.plugin.version}</version>
         <executions>
           <execution>
             <phase>generate-sources</phase>
             <goals>
               <goal>scala-protoc-mojo</goal>
             </goals>
             <configuration>
               <protocVersion>${protoc.version}</protocVersion>
               <inputDirectories>
                 <include>${project.build.directory}/proto</include>
               </inputDirectories>
               <includeDirectories>
                 <include>${project.build.directory}/proto-lib</include>
               </includeDirectories>
               <includeStdTypes>true</includeStdTypes>
             </configuration>
           </execution>
         </executions>
       </plugin>
       

3. If your schema project contains Scala 2.11 and 2.12 modules, do not use the scala.version or scala.compat.version Maven properties. These variables may lead to runtime issues making either Scala 2.11 or 2.12 bindings unusable.