Creating a custom schema

A custom .buildschema.json schema allows you to provide documentation and type annotations for your MSBuild project, targets and/or props files, allowing the MSBuild Editor to provide a much better experience for the properties, items, targets, and metadata that they define or use.

For details of the .buildschema.json schema format, see Schema Structure.

Schema Location

The MSBuild Editor will attempt to locate a sidecar schema for the project file and every targets and props file that it reads via direct and transitive import.

The sidecar schema must have the same name as the MSBuild file with the additional extension .buildschema.json. For example, the sidecar schema for Hello.csproj would be Hello.csproj.buildschema.json, and the sidecar schema for MyBuildLogic.targets would be MyBuildLogic.targets.buildschema.json.

The sidecar schema file must be located in the same directory as the MSBuild file it describes.

NuGet Packages

When authoring a custom schema for a NuGet package that contains MSBuild targets, the schema should be included in the package and installed alongside the MSBuild file. For an example, see the T4.BuildTools NuGet package.

Using the JSON Schema

A JSON schema is available to provide IntelliSense and validation when editing .buildschema.json files. It is located at https://github.com/mhutch/MonoDevelop.MSBuildEditor/blob/main/MonoDevelop.MSBuild/Schemas/buildschema.json.

Visual Studio Code is the recommended JSON editor for .buildschema.json files, as it provides validation and IntelliSense for JSON pointers, and fully supports draft-07 schema features. An association can be set up in .vscode/settings.json that affects all .buildschema.json files on your machine or in a particular repository:

{
  "files.associations": {
    "*.buildschema.json": "jsonc"
  },
  "json.schemas": [
    {
      "fileMatch": [
        "/*.buildschema.json"
      ],
      "url": "https://github.com/mhutch/MonoDevelop.MSBuildEditor/blob/main/MonoDevelop.MSBuild/Schemas/buildschema.json"
    }
  ],
}

The buildschema.json JSON schema can also be used in Visual Studio, and intentionally declares its target as draft-04 so that Visual Studio will load it. However, the schema actually uses draft-07 features are that ignored by the Visual Studio JSON editor, so some validations and completions will be missing when using Visual Studio.

To use this schema in Visual Studio, paste the above schema URL into the Schema field at the top of the JSON source editor. You will need to do this separately for every .buildschema.json file. This association will be persisted in the .csproj file.