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. See configuration.

You can also turn on semantic versioning per content type by initially specifying a version in the definitions manifest on the content type.

When you enable versioning for a content type, the type of changes are being 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 make a client break because it relies on that property being present.

The create content type and manifest import
endpoints have two parameters that also control what types of 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.

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

Configure

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

In appsettings.json:

{
  "EPiServer": {
    "CMS": {
      "ContentModel": {
        "EnableSemanticVersioning":  true
      }
    }
  }
}

In code you can configure the ContentModelOptions class:

services.Configure<ContentModelOptions>(options =>
{
        options.EnableSemanticVersioning = true;
});

Allowed upgrades

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.

Allowed downgrades

Only applies to the content types 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 update content types.

Force

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.