WordPress VIP Block Governance plugin

This WordPress plugin adds additional governance capabilities to the block editor. This is accomplished via three dimensions:

Insertion: restricts what kind of blocks can be inserted into the block editor. Only what’s allowed can be inserted, and nothing else. This means that even if new core blocks are introduced they would not be permitted.
Interaction: This adds the ability to control the styling available for blocks at any level.
Features: controls access to the code editor and block locking.

We have approached this plugin from an opt-in standpoint. An empty effective rule set severely limits the editing experience, although the plugin ships with a permissive fallback rule set. The goal is to create a stable editor with new blocks and features being enabled explicitly via rules, rather than implicitly via updates.

This plugin is currently developed for use on WordPress sites hosted on the VIP Platform.

Try it out
Installation
- Install on WordPress VIP
- Install via ZIP file
Usage
Code Filters
Admin Settings
Endpoints
- vip-governance/v1/rules
  - Example
Analytics
Development
- Tests

Try it out

Try out the VIP Governance plugin in your browser with WordPress Playground.

Installation

To use the WordPress VIP Block Governance plugin after activation, skip to Usage.

Install on WordPress VIP

The WordPress VIP Block Governance plugin is authored and maintained by WordPress VIP, and made available to all WordPress sites by the VIP Integrations Center. Customers who host on WordPress VIP or use vip dev-env to develop locally have access to this plugin automatically. We recommend this activation method for WordPress VIP customers.

Enable the Integration by adding it to your organization. Once that is complete, you can activate the integration on your application. Activation is for the current environment only, so you may need to activate the Integration on multiple environments.

Install via ZIP file

The latest version of the plugin can be downloaded from the repository's Releases page. Unzip the downloaded plugin and add it to the plugins/ directory of your site's GitHub repository.

Usage

On WordPress VIP, place your governance rules in governance-rules.json in your private folder. When that file does not exist, the plugin uses the permissive governance-rules.json bundled with the plugin. The source can also be changed with the filters described below.

Note: The private folder is only supported on VIP sites, or while using vip dev-env locally.

Schema Basics

You can find the JSON Schema for authoring rules here. Use https://api.wpvip.com/schemas/plugins/governance.json as the $schema value to get code completion and validation in supported editors. At runtime, the plugin parses JSON and applies its own required rule-logic checks rather than evaluating this schema file directly.

We have allowed significant space for customization. This means it is also possible to create unintended rule interactions. We recommend making rule changes one or two at a time to troubleshoot these interactions.

Each rule is an object in an array. The one required property is type, which can be default, role, or postType. At most one default rule is allowed. Although the parser accepts an empty file or object as no rules, use a functional default rule for a usable editor configuration.

Rules not of type default require an additional field. These are broken down below, along with examples of their possible values:

Rule Type	Required Field	Possible Values
`role`	`roles`	name/slug of any default or custom roles
`postType`	`postTypes`	name/slug of any default or custom post types

Each rule can have any of the following properties.

allowedFeatures: This is an array of the features that are allowed in the block editor. This list will expand with time, but we currently support two values: codeEditor (viewing the content of your post as code in the editor) and lockBlocks (ability to lock/unlock blocks that restrict movement/deletion). Use an empty array or omit the property when no optional features should be enabled by that rule.
blockSettings: These are specific settings related to the styling available for a block. They match the settings available in theme.json under the key blocks. The definition for that can be found here. Unlike theme.json, you can nest these rules under a block name to apply different settings depending on the parent of a particular block.
allowedBlocks: These are the blocks allowed to be inserted into the block editor. You can also put allowedBlocks in an exact parent's blockSettings. In the default cascading mode this adds child candidates to the root list; use restrictive hierarchy mode when the parent list must be exclusive.

Non-default rule types are combined with the default rule to avoid needless repetition. Matching non-default rules have the following ascending priority:

Post Type
Role

Only the first matching rule of each type in file order is used. A matching role rule replaces each field it defines from the matching post-type rule; fields omitted from the role rule retain the post-type value. The default rule is then additive: its allowedBlocks and allowedFeatures are appended, and its blockSettings are recursively merged. If a user has multiple roles, order role rules carefully because the first intersecting role rule wins.

Wildcards

The wildcard * can be used within allowedBlocks and within blockSettings to target more than 1 block. The intention is that it will limit repeated rules, and allow greater flexibility in controlling the editor experience.

For an example of this feature, refer to the example file here.

Note: allowedBlocks are not respected when a parent blockSettings also has a wildcard. For example, this will not work:

❌ Using `allowedBlocks` under a parent wildcard:

{
  "$schema": "https://api.wpvip.com/schemas/plugins/governance.json",
  "version": "1.0.0",
  "rules": [
    {
      "type": "default",
      "allowedFeatures": [ "codeEditor", "lockBlocks" ],
      "allowedBlocks": [ "core/*" ],
      "blockSettings": {
        "core/*": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ],  // ← Not allowed under "core/*"
          "color": {
            "text": true,
          }
        }
      }
    }
  ]
}

Instead, only apply block settings to wildcards, and specify allowedBlocks to individual parent blocks:

✅ Using `allowedBlocks` under defined blocks:

{
  "$schema": "https://api.wpvip.com/schemas/plugins/governance.json",
  "version": "1.0.0",
  "rules": [
    {
      "type": "default",
      "allowedFeatures": [ "codeEditor", "lockBlocks" ],
      "allowedBlocks": [ "core/*" ],
      "blockSettings": {
        "core/*": {
          "color": {
            "text": true
          }
        },
        "core/quote": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ]
        },
        "core/media-text": {
          "allowedBlocks": [ "core/paragraph", "core/heading" ]
        }
      }
    }
  ]
}

Quick Start

By default, the plugin uses this governance-rules.json. To start using the plugin with your own rules, create governance-rules.json in your private folder. We recommend duplicating one of the starter rule sets provided below and adapting it for your needs. For in-editor schema support, use https://api.wpvip.com/schemas/plugins/governance.json.

With this default rule set, all blocks and all features are enabled. It is sensible to set your default rule to the settings you want for your least privileged user then add capabilities with role and/or post type-specific rules.

Starter Rule Sets

Below is some rule sets that you can use to build your governance-rules.json. They cover a wide range of use cases.