How to handle data type alias change between Umbraco 13 > 15

Luuk · April 15, 2025, 9:25am

I’m wondering how Umbraco handles property editors that have a new alias in Umbraco 15 without breaking the data types they are set on. I’m testing an Umbraco 15 package and how it behaves when someone updates Umbraco 13 (and the Umbraco 13 version of the package) to Umbraco 15. I’m having issues on how to let Umbraco know that the Umbraco 15 property editor is the same one as in Umbraco 13 when the alias changes. Let me explain by first showing what Umbraco does with a textbox;

Lets say I create a property on a node of the data type textstring:

The textstring data type uses the Textbox property editor what has an alias of Umbraco.TextBox as we can see:

Now, when upgrading this database to Umbraco 15, everything keeps working as it should, but we can see that the property editor for the Textstring is now Umb.PropertyEditorUi.TextBox.

I know that Umbraco.TextBox in the screenshot is the property editor schema, but I fail to see how Umbraco knows that the property editor with alias Umb.PropertyEditorUi.TextBox is the same editor as the Umbraco.TextBox editor in Umbraco 13. If I do the same with my own property editor, it just won’t understand it:

Umbraco 13:

Umbraco 15 (where the alias of the property editor has changed):

Don’t get me wrong, this makes sense, since the property editor in Umbraco 15 has a completely different alias of ProudNerds.PropertyEditorUi.VideoPlayer compared to proudnerds.videoplayer.editor it just doesn’t know. When I set is manually, to starts working correctly again.

I know I can just keep the property editor alias the same between Umbraco 13 and 15 and that will work, but I would have liked to update the alias to reflect the convention Umbraco is using. Also I want to know how Umbraco has fixed this issue. Or is it as simple as Umbraco running a migrations on update? Or is there any other logic for connecting the old and new property editors together? Or do I need to do something with the a property editor schema? I just don’t get that concept (yet).

Otherwise I just need to keep the aliases the same

Nik · April 15, 2025, 9:45pm

Hi Luuk,

This post caught my eye and I’ve been browsing the source code to get a better understanding of what’s going on.

In short, there are two types of alias at play here, but the most important one from a data perspective is actually the latter one Umbraco.TextBox - this is what’s called the propertyEditorSchemaAlias or the Data Type and this hasn’t actually changed between v13 and v15.

The other alias you are seeing is the UI Alias for the new back office propertyEditorUiAlias - In the manifest for the editor UI, this helps it know what the component is called.

I figured this out by looking at this file in the Umbraco Source code : Umbraco-CMS/src/Umbraco.Web.UI.Client/src/packages/property-editors/text-box/manifests.ts at contrib · umbraco/Umbraco-CMS · GitHub

As you can see both are referenced here, which, as I understand it, helps tie the UI to the data type.

Hope that helps.

Thanks

Nik

jacob · April 16, 2025, 7:10am

What Nik says is correct, and in addition, this additional property editor ui alias is applied through one of the 14.0.0 migrations - specifically this one:

github.com/umbraco/Umbraco-CMS

src/Umbraco.Infrastructure/Migrations/Upgrade/V_14_0_0/AddEditorUiToDataType.cs

10e56a52f

using System.Text.Json.Serialization;
using Microsoft.Extensions.Logging;
using NPoco;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Infrastructure.Persistence.Dtos;
using Umbraco.Extensions;

namespace Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_14_0_0;

public class AddEditorUiToDataType : MigrationBase
{
    private readonly IKeyValueService _keyValueService;
    private readonly IJsonSerializer _jsonSerializer;
    private readonly ILogger<AddEditorUiToDataType> _logger;

    public AddEditorUiToDataType(IMigrationContext context, IKeyValueService keyValueService, IJsonSerializer jsonSerializer, ILogger<AddEditorUiToDataType> logger)
        : base(context)

This file has been truncated. show original

You could add a package migration to include your own adaptation of this, if you wanted.

leekelleher · April 16, 2025, 7:37am

As an example of a package doing this, here’s the migration code in Contentment:
(heavily inspired by the code Jacob linked to )

github.com/leekelleher/umbraco-contentment

v6.x/src/Umbraco.Community.Contentment/Migrations/Upgrade/V_6_0_0/AddEditorUiToDataType.cs

dev

/* Copyright © 2013-present Umbraco.
 * This Source Code has been derived from Umbraco CMS.
 * https://github.com/umbraco/Umbraco-CMS/blob/release-14.0.0/src/Umbraco.Infrastructure/Migrations/Upgrade/V_14_0_0/AddEditorUiToDataType.cs
 * Modified under the permissions of the MIT License.
 * Modifications are licensed under the Mozilla Public License.
 * Copyright © 2024 Lee Kelleher.
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */

using Umbraco.Cms.Infrastructure.Migrations;
using Umbraco.Cms.Infrastructure.Persistence.Dtos;
using Umbraco.Extensions;

namespace Umbraco.Community.Contentment.Migrations.Upgrade.V_6_0_0;

internal sealed class AddEditorUiToDataType : MigrationBase
{
    public const string State = "{contentment-editorui-datatype-schema}";

This file has been truncated. show original

(Note, that Contentment is using string constants from a static class instead of the literal strings.)

Luuk · April 16, 2025, 7:40am

Thanks all! I’m going to look into this! I prefer not to use migrations if its not needed, but I understand it a lot better now.

Luuk · April 30, 2025, 8:21am

Allright, I’ve been busy getting this to work. The example @leekelleher provided was a bit simpler and probably suited for my situation. However, I don’t get it to work. The issue is that the Umbraco migration ‘messes’ up the database befor my own migration can run and it will fail.

These are my data types in the Umbraco 13 database:

After I add this database to my Umbraco 15 version, it gets updated like this:

It updated the property editor alias to Umbraco.Plain.String. So if I execute any code to just update the propertyEditorUiAlias, I cannot find my database by it’s original property editor alias. Based on the examples, I’d expect the propertyEditorUiAlias to be filled with the original propertyEditorAlias (that happends), but that it wouldn’t touch the original propertyEditorAlias. That’s what the code of Lee does.

I can see it happening in the source code here:

dataTypeDto.EditorAlias = dataTypeMigrationData.EditorAlias?.NullOrWhiteSpaceAsNull()
                                                  ?? "Umbraco.Plain.String";

github.com/umbraco/Umbraco-CMS

src/Umbraco.Infrastructure/Migrations/Upgrade/V_14_0_0/AddEditorUiToDataType.cs

10e56a52f

using System.Text.Json.Serialization;
using Microsoft.Extensions.Logging;
using NPoco;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Infrastructure.Persistence.Dtos;
using Umbraco.Extensions;

namespace Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_14_0_0;

public class AddEditorUiToDataType : MigrationBase
{
    private readonly IKeyValueService _keyValueService;
    private readonly IJsonSerializer _jsonSerializer;
    private readonly ILogger<AddEditorUiToDataType> _logger;

    public AddEditorUiToDataType(IMigrationContext context, IKeyValueService keyValueService, IJsonSerializer jsonSerializer, ILogger<AddEditorUiToDataType> logger)
        : base(context)

This file has been truncated. show original

I’m not sure why though and what it means. I guess I’m missing something here, but I have to say, the concept of the data types, data type UIs, data type schema’s etc is still a bit unclear how everything is related. In the contentment code, I also saw propertyEditorSchema’s getting registrered in the manifest:

github.com/leekelleher/umbraco-contentment

v6.x/src/Umbraco.Community.Contentment.Client/src/property-editor-ui/data-list/manifests.ts

dev

// SPDX-License-Identifier: MPL-2.0
// Copyright © 2024 Lee Kelleher

const schema: UmbExtensionManifest = {
	type: 'propertyEditorSchema',
	name: '[Contentment] Data List  Property Editor Schema',
	alias: 'Umbraco.Community.Contentment.DataList',
	meta: {
		defaultPropertyEditorUiAlias: 'Umb.Contentment.PropertyEditorUi.DataList',
		settings: {
			properties: [
				{
					alias: 'dataSource',
					label: '#contentment_labelDataSource',
					description: '{#contentment_configureDataSource}.',
					propertyEditorUiAlias: 'Umb.Contentment.PropertyEditorUi.ConfigurationEditor',
					config: [
						{ alias: 'addButtonLabelKey', value: 'contentment_configureDataSource' },
						{ alias: 'configurationType', value: 'contentmentDataSource' },
						{ alias: 'maxItems', value: 1 },

This file has been truncated. show original

What is THAT for? I thought schema’s were for the backend validation of property editor values, but why is it in a manifest? Is that something I’m missing? My manifest looks like this:

export const manifests: Array<UmbExtensionManifest> = [
	{
		type: 'propertyEditorUi',
		alias: "ProudNerds.PropertyEditorUi.VideoPlayer",
		name: "Proud Nerds video player property editor",
		js: () => import("./proud-nerds-video-property-editor-ui.element"),
		meta: {
			label: "Video player",
			icon: "icon-play",
			group: "Proud Nerds",
			propertyEditorSchemaAlias: "proudnerds.videoplayer.editor",
			settings: {
				properties: [
					{
						alias: "customAspectRatioEnabled",
						label: "Custom aspect ratio",
						description: "Allow user to set custom aspect ratio on video's that support it.",
						propertyEditorUiAlias: "Umb.PropertyEditorUi.Toggle"
					}
				]
			}
		}
	}
];

Luuk · May 1, 2025, 2:04pm

Alright, I’m going to more or less answer my own question. I see what happends and it works now, but I don’t understand (yet) why it works like this.

Let’s start with the Umbraco 13 version of the package. it has a manifest for the property editor for a video player and is defined like this (with an alias of proudnerds.videoplayer.editor):

{
  ...
  "propertyEditors": [
    {
      "alias": "proudnerds.videoplayer.editor",
      "name": "Video player",
      ...
    }
  ],
  "css": [
   ...
  ],
  "javascript": [
    ...
  ]
}

In the Umbraco 13 database, Umbraco seems to be already creating a migration record in the umbracoKeyValue database:

At this point, it’s already determining what the EditorUiAlias and the EditorAlias are going to be in Umbraco 14+. I don’t really understand why the EditorAlias is going to be Umbraco.Plain.String and I’m also not sure if there are any complications and if this makes sense.

Anyway, forward to Umbraco 15 and the migration that migrates the data editors. Looking at the source code of the migration, it takes that record from the keyValue table and uses that. So the final result is that the EditorAlias gets a value of Umbraco.Plain.String and the EditorUiAlias gets the old value of the EditorAlias.

So I guess the best course of action is to just use the original EditorAlias as the EditorUiAlias in Umbraco 15:

export const manifests: Array<UmbExtensionManifest> = [
	{
		type: 'propertyEditorUi',
		alias: "proudnerds.videoplayer.editor",
		...
		meta: {
			...
			propertyEditorSchemaAlias: "Umbraco.Plain.Json",
			...
		}
	}
];

This seem to work. And it saves me creating a migration of my own. But I’m left with so many questions:

Does it make sense that the original EditorAlias should be changed to Umbraco.Plain.String?
Should I still make a custom migration?
Why is there a migration record in the keyValue table of Umbraco 13?
What’s the difference between a ‘manifest based’ and ‘code based’ editor? And why does it matter?