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>1.0.14</here.plugin.version>
     <artifact.wagon.version>2.0.0</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.0.0 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>