Schema workflows

Schemas define the organization of data in each partition of a layer, including both the structure of the data and its content.

In the HERE platform, schemas are defined using Protocol Buffers. For more information on these concepts, see Schemas.

The OLP CLI provides tools for managing schemas, such as:

• Create a new schema
• Show the details of the schema
• List all schemas that you have access to
• Download the schema package
• Grant permissions on a schema
• Revoke permissions on a schema
• Delete the schema

For more details, see schema commands.

Create a New Schema

Follow the steps below to create a new schema project:

1. Generate a schema project using the provided archetype.
2. Define a data schema.
3. Publish the schema artifact.

For more details, see Archetypes Developer Guide.

Show the Details of the Schema

To verify the details of the schema published to the HERE platform, run the olp schema show command. To run this command, you need to know the schema's HERE Resource Name (HRN).

To learn your schema HRN, do one of the following:

• Go to the platform portal, select the Data tab, click Browse schemas, and look the schema up by its name, description, or group (as specified in the schema project POM file). Then, click the schema, select the Overview tab, and copy the schema's HRN to clipboard.

• Use the olp schema list command and pass your schema's name or summary, or part of it, to the filter parameter. In the output, you'll find the HRN of your schema.

For example, to view the details of the schema with the hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 HRN, you can execute the following command:

olp schema show \
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 --json

olp schema show ^
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 --json

The command displays the following results:

{
    "summary": "Schema project for OLP",
    "schemaValidationResults": [
        {
            "fileExtension": true,
            "module": "proto",
            "packageConsistency": false,
            "backwardsCompatibility": true,
            "googleStyle": true,
            "majorVersionInPackage": true
        },
        {
            "fileExtension": false,
            "module": "ds",
            "packageConsistency": true,
            "backwardsCompatibility": false,
            "googleStyle": false,
            "majorVersionInPackage": false
        }
    ],
    "hrn": "hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0",
    "created": "2018-06-26T11:36:30.321Z",
    "groupId": "com.here.platform.cli.schema.test",
    "name": "Schema",
    "artifactId": "olp_cli_example_schema_v1",
    "type": "proto",
    "updated": "2018-06-26T11:36:40.745Z",
    "version": "1.0.0",
    "variants": [{
        "id": "ds",
        "url": "/artifact/hrn:here:artifact::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1_ds:1.0.0/olp_cli_example_schema_v1_ds-1.0.0.zip"
    }],
    "artifacts": [
        {
            "hrn": "hrn:here:artifact::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1_java:1.0.0",
            "created": "2018-06-26T11:36:30.321Z",
            "groupId": "com.here.platform.cli.schema.test",
            "artifactId": "olp_cli_example_schema_v1_java",
            "version": "1.0.0",
            "updated": "2018-06-26T11:36:40.745Z"
        },
        {
            "hrn": "hrn:here:artifact::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1_proto:1.0.0",
            "created": "2018-06-26T11:36:30.321Z",
            "groupId": com.here.platform.cli.schema.test",
            "artifactId": "olp_cli_example_schema_v1_proto",
            "version": "1.0.0",
            "updated": "2018-06-26T11:36:40.745Z"
        },
        {
            "hrn": "hrn:here:artifact::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1_scala:1.0.0",
            "created": "2018-06-26T11:36:30.321Z",
            "groupId": "com.here.platform.cli.schema.test",
            "artifactId": "olp_cli_example_schema_v1_scala",
            "version": "1.0.0",
            "updated": "2018-06-26T11:36:40.745Z"
        }
    ]
}

Note that the hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 schema HRN in the example above serves as a placeholder where you should pass the HRN of your own schema.

For more details about schema validation results, see Configuring Protobuf Validators.

List all schemas

To list the schemas to which you have access, run the olp schema list command.

olp schema list

The command lists the HRNs of the schemas to which you have access, each in a new line.

hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0
hrn:here:schema::org:com.here.platform.cli.schema.test:public_schema1_v1:1.0.0
hrn:here:schema::org:com.here.platform.cli.schema.test:public_schema2_v1:1.0.0
 
Use olp schema show <schema HRN> to display more information about a schema

Download the schema package

A schema package is a data bundle that contains:

• Local schema definition file(s)
• Any definition files for schema dependencies
• A manifest that declares the top-level Message
• A JavaScript renderer (if available)

To download a schema package, run the olp schema get command.

olp schema get \
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 \
   --output /tmp/ds_bundle

olp schema get ^
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 ^
   --output /tmp/ds_bundle

The command displays the following results:

Schema package was successfully downloaded to /tmp/ds_bundle/olp_cli_example_schema_v1_ds-1.0.0.zip

Grant permissions

You can grant schema permission to any app, group, or user.

The following steps show how to grant schema permission to the application:

1. Create an app or use existing one.

   • To create an app, use the olp app create command with --json flag and save the APP_ID value to use in the next steps.

2. To grant permission to the app to perform selected action on a schema, use the olp schema permission grant command.

   Linux

   Windows

   olp schema permission grant \
          hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 \
          --app APP_ID --read --modify --share

   olp schema permission grant ^
          hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 ^
           --app APP_ID --read --modify --share

   
      Granted read, modify, share access for the app APP_ID to the schema hrn:here:schema::org:com.here.example:test_schema_v1:1.0.0
      

Revoke permissions

To revoke permissions from the app to the schema, use the olp schema permission revoke command.

olp schema permission revoke \
    hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 \
     --app APP_ID --read --modify --share

olp schema permission revoke ^
    hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0 ^
     --app APP_ID --read --modify --share

Revoked read, modify, share access for the app APP_ID to the schema hrn:here:schema::org:com.here.example:test_schema_v1:1.0.0

Delete the schema

Enter the olp schema delete command and specify your schema HRN.

olp schema delete \
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0

olp schema delete ^
   hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0

The command displays the following results:

Schema hrn:here:schema::org:com.here.platform.cli.schema.test:olp_cli_example_schema_v1:1.0.0
has been removed