Adding custom schemas

One of the benefits of using Snowplow is that you can design your own schemas for your events.

tip

See our explanation on what schemas are for and what they look like.

To track an event with a custom schema, you would need code like this (using the Browser tracker as an example):

import { trackSelfDescribingEvent } from '@snowplow/browser-tracker';

trackSelfDescribingEvent({
  event: {
    schema: 'iglu:com.example/my-schema/jsonschema/1-0-0',
    data: {
        ...
    }
  }
});

For Micro to understand this event, it will need to know about com.example/my-schema/jsonschema/1-0-0 or any other relevant schemas. There are two ways you can achieve this:

• Point Micro to an Iglu registry that contains your schemas. This is a good option if you use Snowplow BDP UI or API to create schemas, or if you have deployed your own Iglu registry.
• Add schemas to Micro directly. This can be handy for quickly testing a schema.

Whichever approach you choose, you can use the the API to check if Micro is able to reach your schemas (replace com.example and my-schema as appropriate).

curl localhost:9090/micro/iglu/com.example/my-schema/jsonschema/1-0-0

Pointing Micro to an Iglu registry

Place your Iglu registry URL and API key (if any) into two environment variables: MICRO_IGLU_REGISTRY_URL and MICRO_IGLU_API_KEY.

Make sure to fully spell out the URL, including the protocol (http:// or https://). For most Iglu registries, including those provided by Snowplow BDP, the URL will end with /api — make sure to include that part too, for example: https://com-example.iglu.snplow.net/api. Static registries, such as http://iglucentral.com, are an exception — you don’t need to append /api to the URL.

tip

In Snowplow BDP, you can find your Iglu registry URLs and generate API keys via the console.

The following Docker command will pick up the environment variables and pass them to Micro:

 export MICRO_IGLU_REGISTRY_URL=https://com-example.iglu.snplow.net/api
 export MICRO_IGLU_API_KEY=abcdef123456


docker run -p 9090:9090 \
  -e MICRO_IGLU_REGISTRY_URL \
  -e MICRO_IGLU_API_KEY \
  snowplow/snowplow-micro:2.1.2

This will ensure Micro uses your Iglu registry, in addition to Iglu Central.

For more flexibility, see Advanced usage.

Adding schemas directly to Micro

Limitations

Currently, this method does not work for marking schemas as superseded.

Structure your schema file or files like so:

schemas
└── com.example
    └── my-schema
        └── jsonschema
            ├── 1-0-0
            └── 1-0-1

note

This folder structure is significant. Also note that the schema files must be named 1-0-0, 1-0-1, and so on, not 1-0-0.json or 1-0-1.json.

Next, you will need to place the schemas in /config/iglu-client-embedded/ inside the container.

docker run -p 9090:9090 \
  --mount type=bind,source=$(pwd)/schemas,destination=/config/iglu-client-embedded/schemas \
  snowplow/snowplow-micro:2.1.2

tip

You can read more about bind mounts in the Docker documentation.