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

LuukPeters · 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.)

LuukPeters · 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.