Property Editor Value Schema Exposure

[mattbrailsford]

Summary

Introduce a mechanism for property editors to expose the expected schema/structure of their editable values, both on the server-side (C#) and client-side (TypeScript). Currently, the only type information exposed is the published model via IPropertyValueConverter.GetPropertyValueType(), but there's no equivalent for the editable/stored value that IContent.SetValue() accepts or that the property editor UI element works with.

Problem Statement

Property editors work with three distinct value models:

Model	Usage	Type Exposure
Published Model	IPublishedContent (read-only)	✅ IPropertyValueConverter.GetPropertyValueType()
Database/Editable Model	IContent.SetValue(), persistence	❌ None
Frontend Model	Property editor UI element value	❌ None

For the editable models, developers must "just know" what structure a property editor expects. This creates challenges for:

1. Programmatic content creation - Code that creates/updates content via IContentService has no way to discover what value structure a property editor expects
2. Content import/migration tools - Validation of imported content against expected schemas
3. External integrations - Systems pushing content via APIs have no contract to validate against
4. Testing - Generating valid test fixtures requires tribal knowledge of each property editor
5. AI tooling - AI assistants that help create or modify content need to understand what value structures are valid

Proposed Solution

Server-Side: IValueSchemaProvider Interface

An opt-in interface that property editors can implement to expose their value schema:

public interface IValueSchemaProvider
{
    /// <summary>
    /// Gets the CLR type expected when setting values via IContent.SetValue()
    /// </summary>
    Type GetValueType(object? configuration = null);

    /// <summary>
    /// Gets a JSON Schema describing the value structure.
    /// Configuration parameter allows schema to reflect data type settings
    /// (e.g., Block List schema depends on allowed block types).
    /// </summary>
    JsonSchema? GetValueSchema(object? configuration = null);
}

Property editors opt-in by implementing this interface:

[DataEditor(Constants.PropertyEditors.Aliases.MediaPicker3)]
public class MediaPicker3PropertyEditor : DataEditor, IValueSchemaProvider
{
    public Type GetValueType(object? configuration = null)
        => typeof(IEnumerable<MediaWithCropsDto>);

    public JsonSchema? GetValueSchema(object? configuration = null)
    {
        var multiple = (configuration as MediaPicker3Configuration)?.Multiple ?? false;

        var itemSchema = new JsonSchema
        {
            Type = JsonSchemaType.Object,
            Properties = new Dictionary<string, JsonSchema>
            {
                ["mediaKey"] = new() { Type = JsonSchemaType.String, Format = "uuid" },
                ["mediaTypeAlias"] = new() { Type = JsonSchemaType.String },
                ["crops"] = GetCropsSchema(configuration),
                ["focalPoint"] = GetFocalPointSchema()
            },
            Required = new[] { "mediaKey", "mediaTypeAlias" }
        };

        return multiple
            ? new JsonSchema { Type = JsonSchemaType.Array, Items = itemSchema }
            : itemSchema;
    }
}

Server-Side: IPropertyEditorSchemaService

A service to query schema information:

public interface IPropertyEditorSchemaService
{
    /// <summary>
    /// Gets the JSON Schema for a property editor's value structure.
    /// Returns null if the property editor doesn't provide a schema.
    /// </summary>
    JsonSchema? GetValueSchema(string propertyEditorAlias, object? configuration = null);

    /// <summary>
    /// Gets the CLR type expected when setting values.
    /// Returns null if the property editor doesn't provide type information.
    /// </summary>
    Type? GetValueType(string propertyEditorAlias, object? configuration = null);

    /// <summary>
    /// Validates a value against the property editor's schema.
    /// Throws if the property editor doesn't provide a schema.
    /// </summary>
    SchemaValidationResult Validate(
        string propertyEditorAlias,
        object? value,
        object? configuration = null);
}

Client-Side: valueSchema in Manifest

Add an optional valueSchema property to the property editor UI manifest using JSON Schema:

 interface MetaPropertyEditorUi {
     label: string;
     icon: string;
     group: string;
     propertyEditorSchemaAlias?: string;
     settings?: PropertyEditorSettings;
     supportsReadOnly?: boolean;

     // NEW: JSON Schema for the value structure
     valueSchema?: JsonSchema;
 }

Example:

  const manifest: ManifestPropertyEditorUi = {
      type: 'propertyEditorUi',
      alias: 'Umbraco.TinyMCE',
      name: 'Rich Text Editor',
      meta: {
          label: 'Rich Text Editor',
          icon: 'icon-browser-window',
          group: 'Rich Content',
          valueSchema: {
              type: 'object',
              properties: {
                  markup: { type: 'string' },
                  blocks: {
                      type: 'array',
                      items: { $ref: '#/definitions/block' }
                  }
              },
              required: ['markup']
          }
      }
  };

Client-Side: UmbPropertyEditorSchemaService

A context/service to query schemas:

interface UmbPropertyEditorSchemaService {
    getValueSchema(
        propertyEditorUiAlias: string,
        config?: UmbPropertyEditorConfig
    ): Promise<JsonSchema | undefined>;

    validate(
        propertyEditorUiAlias: string,
        value: unknown,
        config?: UmbPropertyEditorConfig
    ): Promise<SchemaValidationResult>;
}

Use Cases

1. Content Import Validation

public class ContentImportService
{
    public ImportResult Import(ContentImportModel import)
    {
        var contentType = _contentTypeService.Get(import.ContentTypeAlias);

        foreach (var property in import.Properties)
        {
            var propertyType = contentType.PropertyTypes.First(p => p.Alias == property.Alias);
            var schema = _schemaService.GetValueSchema(
                propertyType.PropertyEditorAlias,
                propertyType.Configuration);

            if (schema is null)
                continue; // No schema to validate against

            var validation = _schemaService.Validate(
                propertyType.PropertyEditorAlias,
                property.Value,
                propertyType.Configuration);

            if (!validation.IsValid)
            {
                return ImportResult.Failed(
                    $"Property '{property.Alias}': {validation.ErrorMessage}");
            }
        }

        // Proceed with import...
    }
}

2. AI Content Assistants

AI tools that help editors create or modify content need to understand valid value structures. With schema exposure, an AI assistant could:

• Generate valid Block List structures when asked to "add a hero section"
• Properly format Media Picker values when selecting images
• Validate AI-generated content before applying it

Without schemas, AI tools must rely on hardcoded knowledge of each property editor's internal format, which breaks with custom property editors or when core editors change.

public class AiContentToolHandler
{
    private readonly IContentService _contentService;
    private readonly IContentTypeService _contentTypeService;
    private readonly IPropertyEditorSchemaService _schemaService;
    private readonly IAiClient _aiClient;

    public async Task<IContent> GenerateContentAsync(Guid contentKey, string propertyAlias, string prompt)
    {
        var content = _contentService.GetById(contentKey);
        var contentType = _contentTypeService.Get(content.ContentTypeId);
        var propertyType = contentType.PropertyTypes.First(p => p.Alias == propertyAlias);

        // Get the schema for this property editor
        var schema = _schemaService.GetValueSchema(
            propertyType.PropertyEditorAlias,
            propertyType.Configuration);

        if (schema is null)
        {
            throw new InvalidOperationException(
                $"Property editor '{propertyType.PropertyEditorAlias}' does not expose a value schema.");
        }

        // Send schema to AI so it knows what structure to generate
        var aiResponse = await _aiClient.GenerateStructuredOutputAsync(
            prompt,
            schema);

        // Validate the AI response against the schema
        var validation = _schemaService.Validate(
            propertyType.PropertyEditorAlias,
            aiResponse.Value,
            propertyType.Configuration);

        if (!validation.IsValid)
        {
            throw new InvalidOperationException(
                $"AI generated invalid value: {validation.ErrorMessage}");
        }

        // Set the value on the content
        content.SetValue(propertyAlias, aiResponse.Value);
        _contentService.Save(content);

        return content;
    }

3. Test Data Generation

public class ContentTestFixtureGenerator
{
    public IContent GenerateTestContent(IContentType contentType)
    {
        var content = _contentService.Create("Test", -1, contentType.Alias);

        foreach (var propertyType in contentType.PropertyTypes)
        {
            var schema = _schemaService.GetValueSchema(
                propertyType.PropertyEditorAlias,
                propertyType.Configuration);

            if (schema is not null)
            {
                // Generate valid test data from schema
                var testValue = _testDataGenerator.FromSchema(schema);
                content.SetValue(propertyType.Alias, testValue);
            }
        }

        return content;
    }
}

Implementation Notes

• Backwards compatible - Existing property editors continue to work; schema exposure is opt-in
• JSON Schema standard - Uses the widely-adopted JSON Schema specification for interoperability
• Configuration-aware - Schemas can vary based on data type configuration (e.g., Block List allowed types)
• Core property editors first - Umbraco's built-in property editors should implement IValueSchemaProvider as reference implementations

Questions for Discussion

1. Should there be a higher-level API that provides schemas at the content type level (aggregating all property schemas)?
2. Should the schema service throw or return null when a property editor doesn't provide a schema?
3. For the frontend, should there be a method on UmbPropertyEditorUiElement interface as an alternative to manifest declaration (for dynamic/configuration-dependent schemas)?