Semantic versioning

If your solution has multiple clients sharing the same content types, you can turn on and enforce semantic versioning of content types globally by configuration.

You can also enable semantic versioning per content type by specifying a version in the definitions manifest for the content type.

When you enable versioning for a content type, the changes made to the content type are validated. The new version is also validated to ensure that it semantically matches those changes and that you do not have an outdated version locally. For example, adding a property is a minor change, while removing a property is a major change. Removing a property from a content type could break a client because it relies on that property being present.

The create content typecreate content type and manifest importmanifest import endpoints have two parameters that also control what upgrades or downgrades are allowed, in addition to the version you specify on the content type. See Allowed Upgrades and Allowed Downgrades and Force below in this topic.

The version is automatically incremented if you change a content type from the admin user interface. If you try to make a major (potentially breaking) change, you get a warning and must confirm that you want to perform the change.

You can enable forced semantic versioning of content types through code or configuration.

In appsettings.json:

In code, you can configure the ContentModelOptions class:

The allowed upgrades parameter controls what types of updates you can do to definitions. Only content types are versioned. You can use this parameter as a guard so that you do not accidentally push major changes to, for example, production.

This only applies to the content type endpoints. By specifying the allowed downgrades parameter, you can reset the version number on definitions on the server with your local version number (only supported for content types at the moment) and revert other changes -- much like the Revert to Default button in the admin user interface on a content type. The difference is that it will not revert to how the content type is defined in code but how it is defined locally in your manifest. Use this parameter with caution. This is a way to force updates on content types.

This only applies to the manifest endpoint. Same as Allowed Downgrades, but with less granularity. With the force parameter, Allowed Upgrades and Downgrades are automatically set to Major.