Create and Extend Schemas

The HERE platform allows you to define schemas that are used for sharing and transferring data between other platform users and pipelines. The HERE platform portal uses schema artifacts to dynamically decode data stored on the platform. The platform uses protobuf files to define these schemas. A schema is a collection of related protobuf messages (stored in one or multiple .proto files) that describe the structure of a partition in a catalog layer.

Schema Archetypes

The HERE Data SDK provides a schema Maven Archetype for setting up your own schema projects. Schema archetypes aim to:

  • Simplify and streamline the creation of schemas in a way that is consistent with the HERE platform requirements.

  • Facilitate the development, publication, and accessibility of schema documentation for other platform users.

  • Autogenerate Java and Scala language bindings as well as the Data Schema bundle from the schema that contains all the schema's protobuf definitions.

  • Bundle a GeoJSON renderer JavaScript plugin with the schema for visualizing partition data on top of the base map after publishing the schema to the platform.

Note: Maven

Schema projects are supported by the Maven build system only. Our Maven integration relies on the presence of an extension, called a Maven wagon, that handles the authorization and URL rewriting during the Maven workflow. To get around this for other build systems, like Gradle or sbt, you might need a separate process that uses Maven to populate your local cache, then have your build tooling read from that cache. For more information, see the Artifact Service chapter in Dependency Management.

Schema Validators

The schema archetype uses validation plugins authored by HERE and is only intended for use in projects generated from the provided archetype. To be accepted to the platform, a set of proto and data schema (ds) module validators check the schema against these requirements:

  1. All files have the .proto extension.
  2. The code in .proto files follows the Google's Protobuf Style Guide.
  3. The package name contains the major version of an artifact.
  4. The .proto files are stored in full package hierarchy.
  5. Any changes in .proto files relating to a major version stay backwards compatible.

Create a Schema Project

We recommend that you keep your schema projects separate from your data processor projects and then include them as a dependency. This simplifies maintenance, clearly separates schema versions from your processor versions, and allows for better encapsulation and inheritance.

Follow the steps below to create a new schema project:

  1. Generate a schema project using the provided archetype.
  2. Define and extend a data schema.
  3. Follow the best practices for schema creation.
  4. Configure protobuf validators.
  5. Implement a GeoJSON renderer. (Omit this step if rendering is not needed)
  6. Publish a schema artifact.
  7. Migrate an existing schema project.

results matching ""

    No results matching ""