JSON Schema for SharePoint Site Designs

The schema validation and IntelliSense for SharePoint Site Designs (well, actually Site Script Actions) is not as full-featured as I would like. I put some effort into improving the experience of developers when building site scripts in VSCode, and in this post I will discuss my frustration and how I resolve (most) of them.

Getting started with Site Scripts

I am assuming you have an understanding of the SharePoint Site Design/Site Script capabilities. If you need to get up to speed, start with the The Ultimate Guide to SharePoint Site Designs and Site Scripts from Laura Kokkarinen.

In that post, Laura refers to several tools that aid in the creation of site action scripts. Those are fine tools. But my workflow is different. At some point, the site script, which is just a JSON file, ends up in my code repository. And along with other code assets, I usually modify it using Visual Studio Code. That is where the frustration begins.

Using VSCode to author Site Scripts

Let's start with creating a script from an existing site. The Get-SPOSiteScriptFromWeb cmdlet will generate a site action json file based on a site. Running the command:

Get-SPOSiteScriptFromWeb https://tenant.sharepoint.com/sites/hub -IncludeTheme -IncludeBranding

will result is something like this:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
  "actions": [
    {
      "verb": "setSiteBranding",
      "navigationLayout": "Megamenu",
      "headerLayout": "Standard",
      "headerBackground": "Strong",
      "showFooter": true
    },
    {
      "verb": "applyTheme",
      "themeJson": {
        "palette": {
          // snipped
        }
      }
    }
  ]
}

Everything looks good. Except pasting that exact JSON into VSCode shows errors:

I played around with the order of actions, and received different errors. All of them are erroneous though. So I did some digging.

JSON Schema improvements

Researching JSON Schema support in VSCode led me to various pages. I did find an "error" in the schema published by Microsoft. The schema uses the allOf keyword, and uses the additionalProperties attribute. This combination produces an error as illustrated on the Understanding JSON Schema site. When I manually removed the additionalProperties attribute from definitions that also include allOf, the errors no longer show.

In addition to updating the schema, I found that VSCode has extensive support for IntelliSense and snippets for JSON files. My favorite is defining snippets directly in the schema. By adding an attribute to the JSON schema, we can have VSCode show the list of available actions. And, when selected, the required properties are added to the document!

Another helpful tweak is adding snippets for RegEx patterns. Once finishing these tasks, I was quite productive authoring a script in VSCode.

Site design JSON schema extension

Like most programmers, I don't particularly like one-off tasks. In this scenario, if the official schema is updated, I would need to make the changes again. So I automated it! Then I wrapped it up into a Visual Studio Code extension!

The extension will download and enhance the JSON schema for site script actions. I would love any feedback! And record issues in the GitHub repo.