Site design JSON schema

The site design is a list of actions. For more complex actions, such as creating a list, there are also subactions. Each action is specified by a "verb" value. Verb actions are run in the order they appear in the JSON script. Only the verb actions listed here can be used; otherwise, an "unable to handle action" error will be thrown when trying to upload a site script. More actions will be added over time.

The overall JSON structure is specified as follows:

{
    "$schema": "schema.json",
        "actions": [
            ...
            <one or more verb actions>
            ...
        ],
        "bindata": { },
        "version": 1
};

You can view - and reference - the latest schema here: https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json

Applying site designs multiple times

Actions can be runned more than once on a site. Rerunning actions on the same site with the same parameters will result in an update to the existing schema and not duplication of schema.

Create a new SharePoint list

Use the createSPList verb to create a new SharePoint list.

Note

Once createSPList is applied on a site, runnning the createSPList with the same list name will act as an update to the existing list.

JSON values

  • listName – The name of the list.

  • templateType – Which template to apply to the list. Typically you would use value 100. The full list of template type values are documented in SPListTemplateType enumeration - but the ones we currently support include:

    List Template Name Enum
    Generic List 100
    Document Library 101
    Survey 102
    Links 103
    Announcements 104
    Contacts 105
    Events 106
    Tasks 107
    Discussion Board 108
    PictureLibrary 109
    Site Pages 119
    Issue Tracking 1100

    If you use 101 or 119 and reference the default names ("Documents" or "Site Pages") you can modify the library created with the template. See example below.

  • subactions – An array of actions that run in the order listed to create your list.

Example

{
    "verb": "createSPList",
    "listName": "Customer Tracking",
    "templateType": 100,
    "subactions": [
        {
            "verb": "setDescription",
            "description": "List of Customers and Orders"
        }
    ]
},
{
    "verb": "createSPList",
    "listName": "Documents",
    "templateType": 101,
    "subactions": [
        {
            "verb": "setDescription",
            "description": "This is a modified default document library"
        }
    ]
}

The subactions array provides additional actions to specify how to construct the list. Subactions are also specified using a verb value.

setTitle

Sets a title which identifies the list in views.

JSON value

  • title – The title of the new list.

Example

{
   "verb": "setTitle",
   "title": "Customers and Orders"
}

setDescription

Sets the description of the list.

JSON value

  • description – The description of the new list.

Example

{
   "verb": "setDescription",
   "description": "List of Customers and Orders"
}

addSPField

Adds a new field.

JSON values

  • fieldType – The field type can be set to Text, Note, Number, Boolean, User, or DateTime. For other data types, see the addSPFieldXml action.
  • displayName – The display name of the field.
  • internalName – An optional attribute. If provided, specifies the internal name of the field. If not provided, the internal name is based on the display name.
  • isRequiredTrue if this field is required to contain information; otherwise, false.
  • addToDefaultViewTrue if the field will be added to the default view; otherwise, false.
  • enforceUnique – An optional attribute that defaults to false. If true, all values for this field must be unique.

Example

{
   "verb": "addSPField",
   "fieldType": "Text",
   "displayName": "Customer Name",
   "isRequired": false,
   "addToDefaultView": true
}

deleteSPField

Deletes a default field that was provided by the selected template type.

JSON value

  • displayName – The display name to identify the field to delete.

Example

{
   "verb": "deleteSPField",
   "displayName": "Modified"
}

addSPFieldXml

Enables defining fields and their elements using Collaborative Application Markup Language (CAML). For reference, see Field element (Field).

Currently these field constructs cannot be designated as site columns nor added to content types. To create site columns with Field XML use the createSiteColumnXml action.

JSON value

  • schemaXml – The CAML block to define the field.
  • addToDefaultViewTrue if the field will be added to the default view; otherwise, false.

Example

{
    "verb": "addSPFieldXml",
    "schemaXml": "<Field Type=\"Choice\" DisplayName=\"Project Category\" Required=\"FALSE\" Format=\"Dropdown\" StaticName=\"ProjectCategory\" Name=\"ProjectCategory\"><Default>Operations</Default><CHOICES><CHOICE>Operations</CHOICE><CHOICE>IT</CHOICE><CHOICE>Legal</CHOICE><CHOICE>Engineering</CHOICE></CHOICES></Field>"
}

addSPLookupFieldXml

Enables defining lookup fields and their dependent lists element using Collaborative Application Markup Language (CAML). For reference, see Field element (Field).

JSON value

  • schemaXml – The CAML block to define the field.
  • targetListName – The name that identifies the list this lookup field is referencing. Provide either this or targetListUrl.
  • targetListUrl – A web-relative URL that identifies the list this lookup field is referencing. Provide either this or targetListName.
  • addToDefaultViewTrue if the field will be added to the default view; otherwise, false.

Example

{
  "verb": "addSPLookupFieldXml",
  "schemaXml": "<Field Type=\"Lookup\" DisplayName=\"Contoso Project Category\" Required=\"FALSE\" EnforceUniqueValues=\"FALSE\" ShowField=\"Title\" UnlimitedLengthInDocumentLibrary=\"FALSE\" RelationshipDeleteBehavior=\"None\" ID=\"{101f1f89-d667-4c7f-9ebc-76cb5831d0a2}\" StaticName=\"ContosoProjectCategory\" Name=\"ContosoProjectCategory\" />",
  "targetListName": "Contoso Project Master"
}

addSiteColumn

Subaction to add a previously defined site column directly to a list (existing or created through the site script).

JSON value

  • internalName – The internal name of the site column to add.
  • addToDefaultView – Optional attribute that defaults to false. If true, the newly added field will also be added to the default view.

Example

 {
    "verb": "addSiteColumn",
    "internalName": "siteColumnUser",
    "addToDefaultView": true
 }

addSPView

Defines and adds a view to the list. Use this action to specify the desired columns and how you want the list items displayed (using a CAML query). Action properties allow you to specify row limits, and whether the view is paged and recurses over items in nested folders. You can also designate your constructed view as the default.

JSON value

Example

{
    "verb": "addSPView",
    "name": "Contoso Projects by Category",
    "viewFields": 
    [
        "ID", 
        "Title",
        "siteColumnUser",
        "ProjectCategory"
    ],
    "query": "<OrderBy><FieldRef Name=\"ProjectCategory\" /><FieldRef Name=\"siteColumnUser\" Ascending=\"FALSE\" /></OrderBy>",
    "rowLimit": 100,
    "isPaged": true,
    "makeDefault": true
}

removeSPView

Removes a view from a list. This action can also be used to remove a view applied by the site template.

JSON value

  • name – The name of the view to remove.

Example

{
    "verb": "removeSPView",
    "name": "All Items"
}

addContentType

Adds a content type to the list. Currently these are limited to the default content types included in the site template or ones defined in a script by using the createContentType action.

Note

Currently we do not support adding enterprise content types.

JSON value

  • name – The name of the content type to add.

Example

{
   "verb": "addContentType",
   "name": "name"
}

removeContentType

Removes a content type that was provided by the selected template type.

JSON value

  • name – The name of the content type to remove.

Example

{
   "verb": "removeContentType",
   "name": "name"
}

setSPFieldCustomFormatter

Sets column formatting for a field. For more information, see Use column formatting to customize SharePoint.

JSON values

  • fieldDisplayName – The display name of the field to operate on.
  • formatterJSON – A JSON object to use as the field CustomFormatter.

Example

In this example, we are formatting a number column as a data bar.

                {
                    "verb": "setSPFieldCustomFormatter",
                    "fieldDisplayName": "Effort (days)",
                    "formatterJSON":
                    {
                        "debugMode": true,
                        "elmType": "div",
                        "txtContent": "@currentField",
                        "attributes": {
                            "class": "sp-field-dataBars"
                        },
                        "style": {
                            "width": {
                                "operator": "?",
                                "operands": [
                                    {
                                        "operator": ">",
                                        "operands": [
                                            "@currentField",
                                            "20"
                                        ]
                                    },
                                    "100%",
                                    {
                                        "operator": "+",
                                        "operands": [
                                            {
                                                "operator": "toString()",
                                                "operands": [
                                                    {
                                                        "operator": "*",
                                                        "operands": [
                                                            "@currentField",
                                                            5
                                                        ]
                                                    }
                                                ]
                                            },
                                            "%"
                                        ]
                                    }
                                ]
                            }
                        }
                    }
                }

associateFieldCustomizer

Registers field extension for a list field. For more information on these client-side extensions, see Build field customizer tutorial.

JSON values

  • internalName – The internal name of the field to operate on.
  • clientSiteComponentId – The identifier (GUID) of the extension in the app catalog. This property value can be found in the manifest.json file or in the elements.xml file.
  • clientSiteComponentProperties – An optional parameter, which can be used to provide properties for the field customizer extension instance.

Example

{
    "verb": "createSPList",
    "listName": "Custom List with Slider Extension",
    "templateType": 100,
    "subactions": [
        {
            "verb": "SetDescription",
            "description": "Custom list to illustrate SharePoint site scripting"
        },
        {
            "verb": "addSPField",
            "fieldType": "Text",
            "displayName": "Text Field",
            "isRequired": false,
            "addToDefaultView": true
        },
        {
            "fieldType": "Number",
            "displayName": "Number Field",
            "internalName": "ElectricSlide",
            "addToDefaultView": true,
            "isRequired": true
        },
        {
            "verb": "associateFieldCustomizer",
            "internalName": "ElectricSlide",
            "clientSideComponentId": "35944670-3111-4482-b152-9e9d1sean9f7",
            "clientSideComponentProperties": "{\"sampleText\":\"Yes - added by a site design, what?\"}"
        }
    ]
}

associateListViewCommandSet

Associates a ListViewCommandSet to the list

JSON values

  • title – The title of the extension.
  • location – A required parameter to specify where the command is displayed. Options are: ContextMenu or CommandBar.
  • clientSideComponentId – The identifier (GUID) of the extension in the app catalog. This property value can be found in the manifest.json file or in the elements.xml file.
  • clientSideComponentProperties – An optional parameter, which can be used to provide properties for the extension instance.

Example

{
    "verb": "createSPList",
    "listName": "CustomList",
    "templateType": 100,
    "subactions": [
        {
            "verb": "SetDescription",
            "description": "Custom list to illustrate SharePoint site scripting"
        },
        {
            "verb": "addSPField",
            "fieldType": "Text",
            "displayName": "Text Field",
            "isRequired": false,
            "addToDefaultView": true
        },
        {
            "verb": "addSPField",
            "fieldType": "Number",
            "displayName": "Number Field",
            "internalName": "ElectricSlide",
            "addToDefaultView": true,
            "isRequired": true
        },
        {
            "verb": "associateListViewCommandSet",
            "title": "HelloWorld",
            "location": "CommandBar"
            "clientSideComponentId": "13234283-d6c2-408f-a9ef-31a920c8ae78",
            "clientSideComponentProperties": "{\"sampleText\":\"added by a site design\"}"
        }
    ]
}

Define a new site column

Use the createSiteColumn verb to define a new site column that can then be associated to a list directly or by using the addContentType action.

JSON value

  • fieldType – The type of column to add. Supported values - like SPField - are Text, Note, Number, Boolean, User, and DateTime. For other data types, refer to the addSPFieldXml script action.
  • internalName – The internal name of the site column.
  • displayName – The display name of the site column.
  • isRequiredTrue if this field is required to contain information; otherwise, false.
  • group – An optional attribute to designate the column group.
  • enforceUnique – An optional attribute that defaults to false. If true, all values for this field must be unique.

Example

{
    "verb": "createSiteColumn",
    "fieldType": "User",
    "internalName": "siteColumn4User",
    "displayName": "Project Owner",
    "isRequired": false
}

Use the createSiteColumnXml verb to define a new site column for those complex data types not supported by createSiteColumn. These columns can then be associated to a list directly or by using the addContentType action.

JSON value

  • schemaXml – The CAML block to define the field.
  • pushChanges – Indicates whether this change should be pushed to lists that already reference this field. Defaults to true.

Example

{
    "verb": "createSiteColumnXml",
    "schemaXml": "<Field Type=\"Choice\" DisplayName=\"Project Status\" Required=\"FALSE\" Format=\"Dropdown\" StaticName=\"ProjectStatus\" Name=\"ProjectStatus\"><Default>In Progress</Default><CHOICES><CHOICE>In Progress</CHOICE><CHOICE>In Review</CHOICE><CHOICE>Done</CHOICE><CHOICE>Has Issues</CHOICE></CHOICES></Field>"
}

Define a new content type

Use createContentType to define a new content type that can then be associated to a list by using the addContentType action.

JSON value

Note

When referencing the content type ID, only one of the three references are required - ID, parentName, or parentId.

  • name – The name of the content type to create.
  • description – The optional description of the content type.
  • parentName – Name of the parent content type.
  • parentId – ID of the parent content type.
  • id – ID of the content type.
  • hidden – Specifies whether the content type is visible or hidden.
  • subactions – Specifies subactions to run on the content type. These are used to designate the site columns to add.

Example

{
    "verb": "createContentType",
    "name": "Contoso Projects",
    "description": "custom list content type",
    "parentName": "Item",
    "hidden": false,
    "subactions":
        [
            {
                "verb": "addSiteColumn",
                "internalName": "siteColumn1Text"
            },
            {
                "verb": "addSiteColumn",
                "internalName": "siteColumn2Number"
                },
            {
                "verb": "addSiteColumn",
                "internalName": "siteColumn3Note"
            }
        ]
}

addSiteColumn

Subaction to add a previously defined site column directly to a content type (existing or created through the site script).

JSON value

  • internalName – The internal name of the site column to add.

Example

 {
    "verb": "addSiteColumn",
    "internalName": "siteColumnUser"
 }

removeSiteColumn

Subaction to remove a site column from a list or content type.

JSON value

  • internalName – The internal name of the site column to remove.

Example

 {
    "verb": "removeSiteColumn",
    "internalName": "siteColumnUser"
 }

Use the addNavLink verb to add a new navigation link to the site QuickLaunch or Hub navigation.

JSON values

  • url – The url of the link to add.
  • displayName – The display name of the link.
  • navComponent – The component where to add the link, QuickLaunch or Hub. The default is QuickLaunch.
  • isWebRelativetrue if the link is web relative; otherwise, false. The default is false.
  • parentDisplayName – An optional parameter. If provided, it makes this navigation link a child (sub link) of the navigation link with this displayName. If both this and parentUrl are provided, it searches for a link that matches both to be the parent.
  • parentUrl – An optional parameter. If provided, it makes this navigation link a child (sub link) of the navigation link with this url. If both this and parentDisplayName are provided, it searches for a link that matches both to be the parent.
  • isParentUrlWebRelative – An optional parameter. true if the link is web relative; otherwise, false. The default is false.

Example

Note

If you add a link to a nested site item such as a list, be sure to add the path reference from the root.

{
   "verb": "addNavLink",
   "url": "/Customer Event Collateral",
   "displayName": "Event Collateral",
   "navComponent":"Hub",
   "isWebRelative": true
},
{
   "verb": "addNavLink",
   "url": "/Lists/Project Activities",
   "displayName": "Project Activities",
   "isWebRelative": true
 },
 {
    "verb": "addNavLink",
    "url": "https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-design-overview",
    "displayName": "SharePoint Site Design Overview",
    "parentDisplayName": "Documents"
 }

Use the removeNavLink verb to remove a navigation link from the site.

JSON values

  • url – The url of the link to remove.
  • displayName – The display name of the link.
  • navComponent – The component where to remove the link from, QuickLaunch or Hub. The default is QuickLaunch.
  • isWebRelativeTrue if the link is web relative; otherwise, false.

Example

Note

This action can be used to remove site links added by the collaboration and communication site templates (for example, "home", "documents", "pages", "conversations", etc.).

{
    "verb": "removeNavLink",
    "displayName": "Home",
    "isWebRelative": true
},
{
    "verb": "removeNavLink",
    "displayName": "Pages",
    "isWebRelative": true
},
{
    "verb": "removeNavLink",
    "displayName": "Conversations",
    "isWebRelative": true
},
{
    "verb": "removeNavLink",
    "url": "/_layouts/15/groupstatus.aspx?Target=TEAM",
    "displayName": "Teams",
    "isWebRelative": true
}

Handle special characters

The sites created in other languages than English may contain special characters. Use UTF-8 encoding to read the JSON content containing special characters.

Get-Content '<Folder_location_to_site_script>\site-script.json' -Raw -Encoding UTF8

Apply a theme

Use the applyTheme verb to add a custom theme to the site. For more information about how to construct and upload these themes, see SharePoint site theming. Note that this site action only works for applying custom themes; to apply one of our in-product SharePoint themes, create a copy as a custom one and reference that one.

JSON value

  • themeName – The name of the theme to apply.

Example

{
   "verb": "applyTheme",
   "themeName": "Blue Yonder"
}

Set branding properties

Use the setSiteBranding verb to specify the navigation layout, the header layout and header background.

Note

Setting the navigation layout only works on the communication site template and for the hub navigation.

JSON value

  • navigationLayout – Specify the navigation layout as Cascade or Megamenu
  • headerLayout – Specify the header layout as Standard or Compact
  • headerBackground – Specify the header background as None, Neutral, Soft or Stong

Example

{
    "verb": "setSiteBranding",
    "navigationLayout": "Megamenu",
    "headerLayout": "Compact",
    "headerBackground": "Strong"
}

Use the setSiteLogo verb to specify a logo for your site.

Note

This action only works on the communication site template (68).

JSON value

  • url – The url of the logo image to use.

Example

{
    "verb": "setSiteLogo",
    "url": "/Customer Event Collateral/logo.jpg"
}

Join a hub site

Use the joinHubSite verb to join the site to a designated hub site.

JSON value

  • hubSiteId – The ID of the hub site to join.
  • name – An optional string specifying the name of the hub site.

Example

{
    "verb": "joinHubSite",
    "hubSiteId": "e337cc17-b355-45d2-8dd4-e056f1bcf6f6"
}

Install an add-in or solution

Use the installSolution action to install a deployed add-in or SharePoint Framework solution from the tenant app catalog.

JSON values

Example

Note

To get the solution ID, sign in to a site by using the Connect-PnPOnline cmdlet, and then run Get-PnPApp. This returns a list of your deployed solutions. For multi-geo tenants, use the Product ID after setting up the solution in each geo location. Obtain the Product ID by uplaoding the solution to the app catalog or in the solution's definition.

{
    "verb": "installSolution",
    "id": "d40e4edc-a6da-4cd8-b82d-bba970976803"
}

Register an extension

Use the associateExtension action to register a deployed SharePoint Framework extension from the tenant app catalog.

Note

For more details on how to create and configure a SharePoint Framework extension, check out: Overview of SharePoint Framework Extensions.

JSON values

  • title – The title of the extension in the app catalog.
  • location – Used to specify the extension type. If it is used to create commands, then where the command would be displayed; otherwise this should be set to ClientSideExtension.ApplicationCustomizer.
  • clientSideComponentId – The identifier (GUID) of the extension in the app catalog. This property value can be found in the manifest.json file or in the elements.xml file.
  • clientSideComponentProperties – An optional parameter, which can be used to provide properties for the extension instance.
  • registrationId – An optional parameter, which indicates the type of the list the extension is associated to (if it is a list extension).
  • registrationType – An optional parameter, which should be specified if the extension is associated with a list.
  • scope – Indicates whether the extension is associated with a Web or a Site.

Example

{
    "verb": "associateExtension",
    "title": "SPFXApplicationCustomizer Example",
    "location": "ClientSideExtension.ApplicationCustomizer",
    "clientSideComponentId": "40d64749-a6e5-4691-b440-1e32fb6sean5",
    "scope": "Web"
}

Trigger a flow

Use the triggerFlow verb to kick off a custom flow.

JSON values

  • url – A trigger URL of the flow.
  • name – The name of the flow.
  • parameters – An optional set of parameters to pass into the flow.

Example

 {
    "verb": "triggerFlow",
    "url": "<A trigger URL of the Flow.>",
    "name": "Record and tweet site creation event",
    "parameters": {
        "event": "Microsoft Event",
        "product": "SharePoint"
    }
}

Configure regional settings

Use the setRegionalSettings action to configure the regional settings of the site (/_layouts/15/regionalsetng.aspx).

JSON values

Example

{
    "verb": "setRegionalSettings",
    "timeZone": 2, /* Greenwich Mean Time */
    "locale": 1050, /* Croatia */
    "sortOrder": 6, /* Croatian */
    "hourFormat": "24"
}

Add users (principals) to SharePoint Groups

Use the addPrincipalToSPGroup action to manage addition of users and groups to select default SharePoint groups. For more information, see Understanding SharePoint Groups. This action can be used for licensed users, security groups, and Office 365 Groups.

JSON values

  • principal – A required parameter to specify the name of the principal (user or group) to add to the SharePoint group.
  • group – A required parameter to specify the SharePoint group to add the principal to.

Example

Note

This action currently only supports the Visitors (permission level: read), Members (permission level: contribute or edit, depending on the site template), and Owners (permission level: full control) groups. Principals must be added individually.

{
    "verb": "addPrincipalToSPGroup",
    "principal": "sean@contosotravel.onmicrosoft.com", /* user */
    "group": "Owners"
},    
{
    "verb": "addPrincipalToSPGroup",
    "principal": "travelops", /* sg */
    "group": "Owners"
},
{
    "verb": "addPrincipalToSPGroup",
    "principal": "itexecutives", /* mail-enabled sg */
    "group": "Members"
},
{
    "verb": "addPrincipalToSPGroup",
    "principal": "Adventure@contosotravel.onmicrosoft.com", /* o365 group */
    "group": "Visitors"
}

Manage guest access

Use the setSiteExternalSharingCapability action to manage guest access. For more information, see Manage external sharing for your SharePoint Online environment.

JSON values

  • capability – A required parameter to specify the sharing option for the site collection. The four options are: Disabled, ExistingExternalUserSharingOnly, ExternalUserSharingOnly, ExternalUserAndGuestSharing

Example

{
   "verb": "setSiteExternalSharingCapability",
   "capability": "Disabled"
}

See also