Umbraco.JsonSchema.Extensions

MSBuild tasks for Umbraco to add JSON schema references, update JSON properties, and generate JSON schemas from .NET types.

Note: When building with the .NET 10 SDK or later (i.e. dotnet build), all tasks run from the net10.0 task assembly. With older .NET SDKs or .NET Framework MSBuild (i.e. Visual Studio or msbuild.exe), JsonPathUpdateValue and JsonSchemaAddReferences fall back to the netstandard2.0 task assembly, but JsonSchemaGenerate is only available on .NET 10 (see below).

JsonSchemaAddReferences

Adds references to a JSON schema file, grouped under a combining keyword (allOf by default). Each reference may carry a Weight metadata value to control its order (ascending, default 0). The references are merged using union semantics, so re-running the task does not create duplicates. An existing file is only written when references are added, so the task can run on every build without touching an up-to-date file.

<Target Name="AddJsonSchemaReferences" BeforeTargets="Build">
  <ItemGroup>
    <_References Include="https://json.schemastore.org/appsettings.json" />
    <_References Include="appsettings-schema.Umbraco.Cms.json#" />
  </ItemGroup>
  <JsonSchemaAddReferences JsonSchemaFile="$(MSBuildProjectDirectory)\appsettings-schema.json" References="@(_References)" />
</Target>

Parameter	Required	Description
JsonSchemaFile	Yes	Path to the JSON schema file to create or update
References	Yes	The references to add as $ref entries (the Weight metadata orders them)
TargetPath	No	JSON path to the object the references are added to (default: the schema root)
Combinator	No	The JSON Schema keyword the references are grouped under: allOf (default), anyOf or oneOf

By default the allOf is added at the root, so every reference constrains the whole schema. Set TargetPath to compose references into a nested location instead — for example to only extend a single property while leaving the rest of the schema owned by a base reference:

<Target Name="AddPackageSchemaReferences" BeforeTargets="Build">
  <ItemGroup>
    <!-- Base schema owns the top-level shape -->
    <_BaseReference Include="umbraco-package-schema.Umbraco.Cms.json#" />
    <!-- Package fragments only extend the extensions array items -->
    <_ExtensionReference Include="acme.umbraco-package-schema.json#/properties/extensions/items" />
  </ItemGroup>
  <JsonSchemaAddReferences JsonSchemaFile="$(MSBuildProjectDirectory)\umbraco-package-schema.json" References="@(_BaseReference)" />
  <JsonSchemaAddReferences JsonSchemaFile="$(MSBuildProjectDirectory)\umbraco-package-schema.json" References="@(_ExtensionReference)" TargetPath="$.properties.extensions.items" />
</Target>

TargetPath supports object property segments using dot or bracket notation, with an optional leading $ (e.g. $.properties.extensions.items or properties['extensions'].items). Intermediate objects are created when they do not exist; array indices are not supported.

By default references are combined with allOf (intersection — every referenced schema must match). Set Combinator to anyOf or oneOf to combine them as a union instead — useful when the target is itself a union (e.g. the items of a discriminated array), so each referenced schema only needs to match its own entries rather than all of them:

<JsonSchemaAddReferences JsonSchemaFile="$(MSBuildProjectDirectory)\umbraco-package-schema.json" References="@(_ExtensionReferences)" TargetPath="$.properties.extensions.items" Combinator="anyOf" />

JsonPathUpdateValue

Updates the value of a property in a JSON file using a JSON path expression. The file is only written when the property exists and its value changes, so the task can run on every build without touching up-to-date files.

<Target Name="UpdatePackageManifestVersion" DependsOnTargets="Build" AfterTargets="GetBuildVersion;GetUmbracoBuildVersion">
  <ItemGroup>
    <_PackageManifestFiles Include="**\package.manifest" />
  </ItemGroup>
  <JsonPathUpdateValue JsonFile="%(_PackageManifestFiles.FullPath)" Path="$.version" Value="&quot;$(PackageVersion)&quot;" />
</Target>

JsonSchemaGenerate

Generates a JSON schema from a C# type in an assembly. XML documentation comments are included as description fields in the generated schema, providing IntelliSense tooltips in editors.

Note: This task runs on .NET 10, so it requires the .NET 10 SDK (i.e. dotnet build) or Visual Studio 2026+ (MSBuild 18.0+), which supports running .NET tasks via the TaskHost. It is not available when building with Visual Studio 2022 or earlier.

Note: When executing this task from a class library (Microsoft.NET.Sdk with <OutputType>Library</OutputType>, the default) and the type being generated depends on assemblies from referenced NuGet packages (e.g. Umbraco.Core), set <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> in the project file. This ensures the dependency DLLs are copied next to the target assembly so they can be resolved at build time. This is already the default for executable projects, including the Web (Microsoft.NET.Sdk.Web), Worker (Microsoft.NET.Sdk.Worker), and Blazor WebAssembly (Microsoft.NET.Sdk.BlazorWebAssembly) SDKs.

Parameter	Required	Description
AssemblyPath	Yes	Path to the assembly file containing the type
TypeName	Yes	Fully qualified type name to generate the schema for
OutputPath	Yes	Output file path for the generated JSON schema
IncludeObsoleteProperties	No	Whether to include properties marked with [Obsolete] (default: false)

<!-- Add JSON schema file to package output and remove on clean -->
<PropertyGroup>
  <_JsonSchemaFile>appsettings-schema.MyPackage.json</_JsonSchemaFile>
</PropertyGroup>
<ItemGroup>
  <Content Include="$(_JsonSchemaFile)" PackagePath="" Visible="false" />
  <Clean Include="$(_JsonSchemaFile)" />
</ItemGroup>

<!-- Generate JSON schema on build (regenerated when assembly is newer) -->
<Target Name="GenerateAppsettingsSchema" AfterTargets="Build" Inputs="$(TargetPath)" Outputs="$(_JsonSchemaFile)">
  <Message Text="Generating $(_JsonSchemaFile)" Importance="high" />
  <JsonSchemaGenerate AssemblyPath="$(TargetPath)" TypeName="MyPackage.MyPackageSchema" OutputPath="$(MSBuildThisFileDirectory)$(_JsonSchemaFile)" />
  <ItemGroup>
    <FileWrites Include="$(_JsonSchemaFile)" />
  </ItemGroup>
</Target>