365Fanatic / Guides / SharePoint

Site design as JSON: extract, clean, add back and activate in the GUI

SharePointJSONPnPSharePointSite designsite script

A site script is JSON (actions). A site design is the GUI button that runs one or more scripts. JSON from a living site = PnP. Classic SharePoint Online Management Shell only exports scripts already in the tenant.

Extract (PnP)

PowerShell
# PnP: generate JSON from a living site (the extract).
Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/intranet" -Interactive -ClientId "<app-id>"
Get-PnPSiteScriptFromWeb -Url "https://contoso.sharepoint.com/sites/intranet" `
  -IncludeAll `
  | Set-Content -Path .\intranet.sitescript.json -Encoding utf8

Export an existing script (SPO)

PowerShell
# SharePoint Online Management Shell: export an EXISTING site script (not generate from a web).
Connect-SPOService -Url "https://contoso-admin.sharepoint.com"
Get-SPOSiteScript | Format-Table Id, Title
$s = Get-SPOSiteScript -Identity "<guid>"
$s.Content | Set-Content .\exported.sitescript.json -Encoding utf8

Clean the JSON

  • Maximaal 30 acties per script. Splits anders in meerdere scripts onder één design.
  • Verwijder triggerFlow met flow-IDs van de bron.
  • Verwijder addPrincipalToSPGroup met personen. Gebruik groepen.
  • Vervang absolute tenant-URLs.
  • Houd createSPList, addSPField, addNav, theme/branding als die overdraagbaar zijn.
  • UTF-8 zonder BOM. Ongeldige JSON = Add-SPOSiteScript faalt zonder duidelijke reden.
  • Volgorde: lijst maken, dan kolommen, dan views.

Add back

PowerShell
# Add the cleaned JSON back — PnP
$json = Get-Content .\intranet.sitescript.clean.json -Raw
$script = Add-PnPSiteScript -Title "Intranet v2" -Description "Cleaned from intranet" -Content $json
Add-PnPSiteDesign -Title "Intranet" -Description "Apply from the GUI" `
  -WebTemplate 64 -SiteScriptIds $script.Id
# WebTemplate 64 = Team site (Group). 68 = Communication site. 1 = Team site without a group.

# Add the cleaned JSON back — SPO Management Shell
$json = Get-Content .\intranet.sitescript.clean.json -Raw
$added = Add-SPOSiteScript -Title "Intranet v2" -Content $json
Add-SPOSiteDesign -Title "Intranet" -WebTemplate 64 -SiteScripts $added.Id -Description "Apply from the GUI"

Activate in the GUI

SharePoint admin center → Content services → Site designs: you see the design, can bind it to new sites, or set it as default for team/communication. On an existing site: gear → Site designs → Apply a site design. Rights: SharePoint admin to create designs; site owner to apply.

Frequent errors and how to fix them

These are the messages people type into search when the module will not start. The exact wording is here so this page can be found.

The term 'Connect-SPOService' is not recognized
SharePoint Online Management Shell / Microsoft.Online.SharePoint.PowerShell is not installed, or you are in PowerShell 7 without the module.
403 Forbidden on Connect-SPOService
Not a SharePoint admin, or you are not using the tenant-admin URL (https://CONTOSO-admin.sharepoint.com).
PnP vs SharePoint Online Management Shell
Connect-SPOService is the classic module; Connect-PnPOnline is PnP. Do not mix them in one script.

Questions about this, or need help setting it up? We are happy to think along.

Message on LinkedIn →