Schema evolution

Over time, your Uni's data model may need to be updated to adapt to new business needs. At Vendia, this process is referred to as schema evolution. Schema evolution is a safe and easy way to make non-breaking changes to your Uni's data model and API without incurring any additional cost. It can be performed in both the Share UI and CLI.

What types of changes are allowed?

Only additive or non-breaking changes can be made. Here are some examples of the types of changes that are allowed:

• New types and their associated properties can be added
• New properties of an existing type can be added
• New enum values of an existing property can be added

Here are some examples of the types of the changes that are not allowed:

• Existing types cannot be removed
• Existing properties cannot be removed
• Changing the type of an existing property is not allowed
• Changing the required flag for an existing property is not allowed

Because breaking changes are not allowed, you can rest assured knowing that any changes introduced via schema evolution will never break existing applications in production. There is, potentially, one exception to this rule - see Removing an index via schema evolution below.

Schema evolution in the Vendia Share UI

1. Navigate to your Uni landing page.
2. Click on the "Schema" tab to view your Uni's current JSON schema.
3. Click on the "Evolve schema" button.
4. Follow the step-by-step instructions to update your schema and intiate schema evolution!

Schema evolution with the Share CLI

1. If it's your first time using the Vendia Share CLI, visit the CLI docs to get up and running first. Additionally, the CLI docs on schema evolution are located here.
2. Create a JSON file locally with your updated JSON schema (e.g., updated-schema.json). You can always copy/paste your current JSON schema from your Uni's "Schema" tab in the Vendia UI.
3. Run the following command once you're happy with your schema changes:

share uni evolve --uni your-uni-name --schema updated-schema.json

You should receive the following output from the above command: Schema evolution initiated.

If you are removing an index, you'll need to add the --allowed-breaking-change=INDEX_REMOVED flag to your CLI command, but read this section on index removal first!

Adding and removing indexes

Indexes are extremely useful for filtering list queries efficiently or sorting query results by indexed fields. Learn more about adding indexes to your data model here.

Indexes can be added or removed during schema evolution, but only one index can be changed per call to schema evolution. An index change can be a single index addition OR removal - replacing or moving an index from one field to another counts as two changes, one removal and one add. This must be carried out in two phases: first, use schema evolution to remove the unwanted index and, once that completes, use schema evolution again to add the desired index.

Removing an index via schema evolution

Removing an existing index can be a dangerous or potentially "breaking" change and should be carried out with caution. Removing an index will break any list queries using the "order" argument to sort by the indexed field and can severely degrade the performance of list queries using the "filter" argument in conjunction with the indexed field.

In order to remove an index you must explicitly opt-in to allowing index removal by agreeing to a confirmation in the Share UI or passing a flag to the CLI command (share uni evolve --allowed-breaking-change=INDEX_REMOVED)

If you've discovered that you've broken something in an application by removing an index, you should evolve your schema again and add the index back.