Management API: Add JSON Schema support for data types and content types

[Migaroez]

Description

This PR adds JsonSchemas for Datatypes and contentTypes to allow tooling to discover the dynamic parts of the payloads for content creation trough the management api.

For datatypes, this is done by implementing IValueSchemaProvider on a DataEditor. The GetValueSchema(object? configuration) method allows the PropertyEditorSchemaService to pass in a configuration (existing on the datatype) to the datatype's DataEditor to get the dynamic schema.
This PR comes with IValueSchemaProvider for (hopefully) all core DataEditors.
For labels we inform the tooling that the value will be ignored

For ContentTypes, the ContentTypeJsonSchemaService generates the necessary schema based on the defined IContentType and suplies references ("$ref": "/umbraco/management/api/v1/data-type/0cc0eba1-9960-42c9-bf9b-60e150b429ae/schema") to the datatype of each property defined.

UPDATE: The validation endpoint/service method (and also a bunch of tests) have been removed from this PR due to a possible license issue.

Inspiration

This PR is a direct result of the work done in #21274

New dependencies

JsonSchema.Net: used to validate a value against a specific datatype

New endpoints

Data Type Schema Endpoints

Method	Route	Description
GET	/umbraco/management/api/v1/data-type/{id}/schema	Gets the JSON Schema for a data type's property values
GET	/umbraco/management/api/v1/data-type/schema	Gets the JSON Schema for multiple datatypes
POST	/umbraco/management/api/v1/data-type/{id}/schema/validate	Validates a value against the data type's JSON Schema

Content Type Schema Endpoints

Method	Route	Description
GET	/umbraco/management/api/v1/document-type/{id}/schema	Gets a JSON Schema for a document
GET	/umbraco/management/api/v1/media-type/{id}/schema	Gets a JSON Schema for a media type
GET	/umbraco/management/api/v1/member-type/{id}/schema	Gets a JSON Schema for a member type

Things that are open for discussion

The interface might be in the wrong location: Since all these json schema's only make sense from a management api perspective it seems strange that the interface and implementation is in the core project. We could change this to live in the management api project with a collectionbuilder and adding an editorAlias property to the IValueSchemaProvider interface to signal which provider matches which editor. The possible problem with this is that if a IValueSchemaProvider ever relies on a method in the editor to add a constraint or read configuration or something alike, then they must live in the same file. This isn't a problem for packages, but might pose a problem for core.

Testing

Create datatypes and document types and see if when queried they return the expected schema.

[AndyButland]

Impressive piece of work @Migaroez. Overall it looks good to me and a nice solution to the problem.

I've left a few minor comments inline.

There are some failing tests as I assume you have seen that will need to be looked at to see what's going wrong.

There's an endpoint mentioned in the PR description - "Gets the JSON Schema for multiple datatypes" - that isn't implemented. If not needed, suggest just to remove this from the description.

With regard to:

The interface might be in the wrong location: Since all these json schema's only make sense from a management api perspective it seems strange that the interface and implementation is in the core project.

I would say this is OK where it is. It means if package developers want to create a property editor, they can do so with just a core reference, and not have to take a reference on the management API.

Great effort on the unit testing, but perhaps there's a little more logic that would be good to see if you can get it under automated test:

• ContentTypeJsonSchemaService
• The block editor schemas generated from the property editors.

Is there any value in caching the property editor generated schemas? Perhaps not, as they aren't making any data requests, but on the other hand they only change when the data type configuration changes and perhaps if tools are regularly calling these there might be value in doing so.

I haven't tested so far, only reviewed the code - I'm assuming your AI stakeholders will handle that side of things, but if not, I can take a look toward the end of the week.

[mattbrailsford]

Overall it looks good, but I do have a few queries.

1. Which value schema are these exposing? As per my linked discussion, a property technically has 3 property values (IPublishedContent [published value], IContent [raw value], PropertyEditorUI [editor value]). Given this is based around the property editor definitions, am I right in assuming this should be the schema for the editor? (which is ideally what I'm after)

2. I do see one significant issue in that property editors don't have to have a server side component to them. It is entirely possible to define a property editor client side and just use a broad propertyEditorSchema like JSON. These won't therefore expose a schema from the endpoint.

3. This also doesn't cover schemas for just general propertyEditorUI elements that are not exposed as property editors. The propertyEditorUI manifest system is used for more than just content property editors. It can be used (and is) in add-ons to provide a means of creating dynamic UI (UI Builder, Commerce Payment Provider Settings, Umbraco AI Provider Settings). These again aren't covered here.

The later two points are the main reason I saw this being something that is defined on the propertyEditorUI manifest to say what the property editor component is expecting as a value.

PS I chatted to Phil about this and I do think this is spot on for his MCP purposes, my comments are more related to Umbraco AI Copilot which has more of a UI level scope, rather than management API endpoint scope.

[Migaroez]

There's an endpoint mentioned in the PR description - "Gets the JSON Schema for multiple datatypes" - that isn't implemented. If not needed, suggest just to remove this from the description.

Pushed now 🙈

[Migaroez]

Is there any value in caching the property editor generated schemas? Perhaps not, as they aren't making any data requests, but on the other hand they only change when the data type configuration changes and perhaps if tools are regularly calling these there might be value in doing so.

I think we are fine without

[Migaroez]

1. Which value schema are these exposing? As per my linked discussion, a property technically has 3 property values (IPublishedContent [published value], IContent [raw value], PropertyEditorUI [editor value]). Given this is based around the property editor definitions, am I right in assuming this should be the schema for the editor? (which is ideally what I'm after)

These are the PropertyEditorUI values the FromEditor methods on the DataEditors expect. So anything higher is fine too, contentEditingService and management API.
I would strongly like to discourage anything from directly setting values on an IContent or directly in the DB, but in principle we could add additional schema's for these too.

[Migaroez]

2. I do see one significant issue in that property editors don't have to have a server side component to them. It is entirely possible to define a property editor client side and just use a broad propertyEditorSchema like JSON. These won't therefore expose a schema from the endpoint.

True, and these would therefor use the PlainJsonPropertyEditor or even the PlainStringPropertyEditor. If a UI configuration uses these plain propertyEditors they are implicitly saying: I do not care about the integrety of the data that is being sent by other clients as they do not support any validation/transformation of the data on the backend.

When tooling requests the schema for a documenttype they get

"x-umbraco-properties": {
  "title": {
    "dataTypeId": "0cc0eba1-9960-42c9-bf9b-60e150b429ae",
    "editorAlias": "Umbraco.TextBox",
    "mandatory": false,
    "variations": "Nothing"
  },
  "blocklist": {
    "dataTypeId": "6ccabb65-aff8-4f27-be24-3f8d724cae67",
    "editorAlias": "Umbraco.BlockList",
    "mandatory": false,
    "variations": "Nothing"
  }
}

Maybe we should add the editorUiAlias to this as well so the tooling can lookup any frontend defined schemas for the value?

I know it's not the best of anwsers, but it is the result of allowing flexible property editor registration without enforcing a single source of truth.

[Migaroez]

3. This also doesn't cover schemas for just general propertyEditorUI elements that are not exposed as property editors. The propertyEditorUI manifest system is used for more than just content property editors. It can be used (and is) in add-ons to provide a means of creating dynamic UI (UI Builder, Commerce Payment Provider Settings, Umbraco AI Provider Settings). These again aren't covered here.

I am hoping another PR will come along that supports schema retrieval on the frontend that augments/replaces the backend one for a given client. If you think this is urgent then I will talk to the team and see what we can do.

[mattbrailsford]

Maybe we should add the editorUiAlias to this as well so the tooling can lookup any frontend defined schemas for the value?

I think that's the best you can do. Ultimately so long as there is a path to a schema, it can be worked out, and that's a nice fallback.

[mattbrailsford]

I am hoping another PR will come along that supports schema retrieval on the frontend that augments/replaces the backend one for a given client. If you think this is urgent then I will talk to the team and see what we can do.

Given the primary use case for Umbraco AI Copilot will be content / media I think what we have in this PR is a great step forward. Schemas for property editor UI manifests would be a nice next step for opening things up beyond content. I'm happy for that to come in another PR so long as it's on the roadmap.