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
};

Create a new SharePoint list

Use the createSPList verb to create a new SharePoint list.

JSON values

  • listName – The name of the list for users to identify it with.
  • templateType – Which template to apply to the list. Typically you would use value 100. Template type values are documented in SPListTemplateType enumeration.
  • 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"
         }
    ]
}


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.

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>"
}

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

  • name – The name of the view.
  • viewFields – An array of the internal names of the fields in your view.
  • query – A CAML query string that contains the where clause for the view's query. See CAML schemas.
  • rowLimit – The row limit of the view.
  • isPaged – Specifies whether the view is paged.
  • makeDefault – If true, the view will be made the default for the list; otherwise, false.
  • scope – An optional setting to specify the scope of the view. For more details, see SPViewScope enumeration.

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 display 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

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

JSON values

  • title – The title of the extension.
  • location – A required parameter to specify where the command is displayed. Options are: ContextMenu or CommandBar.
  • 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 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
}

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 list or content type (existing or created through the site script).

Note

This action can be used to add created site columns to a list or content type.

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.

JSON values

  • url – The url of the link to add.
  • displayName – The display name of the link.
  • isWebRelativeTrue if the link is web relative; otherwise, 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",
   "isWebRelative": true
},
{
   "verb": "addNavLink",
   "url": "/Lists/Project Activities",
   "displayName": "Project Activities",
   "isWebRelative": true
 }

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"
}

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

Note

Hub sites are a new feature that are just rolling out to customers in Targeted Release in March 2018. This action might not be available for use in your environment. To learn more, see SharePoint hub sites overview.

{
    "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.

{
    "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.
  • 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 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 SharePoing Groups

Use the addPrincipalToGroup 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