Skip to main content

Managing data structures with the JSON Editor

info
This documentation only applies to Snowplow BDP. See the feature comparison page for more information about the different Snowplow offerings.
info

The JSON editor is ideal for more complex data structures that require nesting or more advanced data types. For simple data structures, use the Data Structures Builder.

Creating a new data structure

Select whether you'd like to create an Event or an Entity. You can always change this selection at a later date.

Choice between builder and JSON editor optionsChoice between builder and JSON editor options

You can now write the first version of your JSON schema for this data structure. Some template JSON is provided in the code window to start you off.

Once you are done, click the Validate button and we'll validate that your schema is valid JSON markup. Assuming it passes validation, you can save your data structure as a draft.

See the Working with drafts section for more information about the draft workflow.

Click Save as draft to save your data structure as a draft. As this is the first version of your data structure, it will be created as version 1-0-0 when you later deploy it to your development environment.

Editing a data structure

Make the required edits to the JSON schema. You can use the 'Difference' toggle above the editor to see a 'diff' view against the latest Production version of your data structure.

In the example below we have changed the maxLength of example_field_1.

Once you are happy with your changes, click Validate to ensure you have valid JSON markup. Then click Publish to development environment to save your changes to your development environment.

The versioning dialog will appear, at this point you have three options:

  • Increment a minor version to indicate a non-breaking change to the schema. In our example, this would increment the schema to from 1-0-1 to 1-0-2.
  • Increment a major version to indicate a breaking change to the schema. In our example, this would increment the schema from 1-0-1 to 2-0-0.
  • Patch the current version, this will overwrite the existing schema without increasing the version. In our example, this would leave the schema at 1-0-1.
Selecting the "patch" option

Patching can be useful in development environments, but should be done carefully and should never be done in production. See amending schemas for an explanation and some suggestions.

For more information see Versioning your data structures.

Once you have selected the appropriate version, click Deploy to development environment and your data structure will be deployed to your development environment ready for you to test.

You can identify data structures where the Development version is ahead of the Production version by the yellow background on the version number. In this example both user and alert have been edited on development.