Skip to main content

Schema Guidelines

Schemas are handled so that Git-based versioning reaches application schemas while existing schemas keep working. The result is that schemas are tracked per branch, which is what you want for review — but it also means two branches can hold different states of the same schema. This page explains the behavior and the discipline it calls for.

How schema tracking works​

Schemas that were referenced continue to work as they are. When you edit a schema, its content is written back into the schema file, so the schema can be tracked in Git from that point forward.

These changes are scoped per branch: an edit made in one branch affects that branch's schema only, until it is merged into other branches.

Newly created schemas follow this approach automatically. Older schemas are not converted automatically, so a mix of both can exist in the same application.

What to expect​

Older schemas continue to work as references across branches, showing the same content everywhere. Once a schema is edited in one branch, its content is written to Git and tracked from then on — in that branch. Other branches keep using the reference until a merge happens.

This is why a schema can appear to behave differently in two branches: one branch has the tracked content, the other still has the reference. It is not a defect, and the fix is always the same — merge the schema change to the parent branch and have dependent branches pull.

warning

Merge schema edits back to develop or your other parent branches as soon as possible. The longer an edited schema sits in one branch, the further the branches diverge, and workflow mappings depend on schema shape.

Working across multiple branches​

When several people work on the same application across multiple branches, one branch may still use a schema reference while another has moved to direct content. To keep this from compounding:

  • Merge branches regularly rather than at the end of a release.
  • Give a shared schema change its own branch, and merge it before the branches that depend on it go far. See Parallel Development with Multiple Developers.
  • After a schema change is merged, have every dependent branch check out the target branch, pull, and sync before continuing to map against the schema.

Migrating older schemas​

Migrating an older schema to the tracked format requires a manual edit. Once edited, the content is written back into the file and tracked in Git for that branch. The migration applies only to the branch where the edit was made, until it is merged into parent or sibling branches.

The recommended strategy:

  1. Create a branch from develop, or another up-to-date parent branch.
  2. Apply the schema edits in that branch, and nothing else.
  3. Merge that branch into every other relevant branch, accepting only the schema changes in the merge.

Keeping the branch to schema changes alone is what makes step 3 safe — a branch that also carries workflow changes cannot be merged into siblings without dragging those along.

Deleting schemas​

Do not delete a schema from a Git-enabled application. Deletion can break references in Git-enabled and cloned applications that still point at it. Deprecate the schema, or manage it through the registry instead.