Creating a ruleset

OverviewCopy Anchor Link

The guided editor builds an API Governance ruleset from a form. You pick rules from a library of P4A recipes and MuleSoft's own rulesets, or describe your own, and P4A writes the Validation Profile YAML for you. You don't need to know the YAML format, and you don't need a repository.

What you build is a workspace ruleset: it belongs to one of your workspaces, and every active member of that workspace can open, edit and deploy it. A workspace ruleset deploys to your own Exchange with no review. It never appears in the public catalog. To list a ruleset there, see Submitting a ruleset.

The API and the MCP tools call workspace rulesets "drafts", as in /api/ruleset-drafts and save_ruleset_draft.

The editor covers rules for API specifications (REST and similar APIs). For rules it can't show as a form, edit that rule's YAML on its own.

Starting a workspace rulesetCopy Anchor Link

There are three ways in:

• On the Rulesets page, click New ruleset. The Workspace tab, next to Community and MuleSoft, lists every workspace ruleset you can open, as cards like the other tabs. Each card shows the ruleset's workspace, its rules by severity and the API types it targets. Search, filter by workspace or API type, and sort, or switch to the table view with the Tiles and Table buttons. Each card and row has Edit, Deploy and Delete buttons. Deploy and Delete appear only when you're allowed to use them, and a ruleset in an archived workspace shows View instead of Edit.
• On a workspace's page, open the Rulesets tab. The Workspace rulesets card lists that workspace's rulesets, and New ruleset starts one in it.
• On a catalog ruleset's page, click Customize this ruleset, pick the workspace (when you have more than one) and click Save as workspace ruleset. P4A saves a copy of the ruleset's YAML, named after the ruleset with "(custom)" added, and opens it in the editor. The copy doesn't record which ruleset it came from. Its asset ID must be unique in the workspace, so to copy the same ruleset twice into one workspace, change the first copy's Exchange asset ID before you save the second.

A new workspace ruleset has three steps:

1. Basics. Pick the workspace (when you have more than one) and give the ruleset a name. A description, an Exchange asset ID and a Default version are optional. The asset ID can use lowercase letters, digits and hyphens; if you leave it empty, the first deploy makes one from the name. The default version is the first version you deploy.
2. Rules. Click Add a rule to pick rules from the rule library. See Editing rules.
3. Review. Check the YAML P4A wrote, then click Save.

Nothing is stored until you click Save. The editor then opens the saved ruleset.

Editing rulesCopy Anchor Link

A saved workspace ruleset's page has four sections: Details (name, description, asset ID and default version), Rules, History and Deployments. The quick links bar at the top jumps to each one. Rules has two tabs, Rules and YAML.

The Rules tab lists the rules as cards, with the YAML next to them. Every rule has a Severity, a Rule name and a Message:

• Severity decides the outcome. A violation makes an API non-conformant, a warning is worth fixing but doesn't block, and info is advice only.
• The Message is what an API author sees when the rule fails.

To add a rule, click Add a rule. The rule library opens with every rule you can add, grouped by where it comes from:

• Custom rule, at the top, adds an empty rule you build yourself (see below). Custom rule (YAML) lets you write the rule in YAML instead.
• P4A recipes, for checks MuleSoft's rulesets don't have. A recipe becomes an editable card with the form fields filled in.
• MuleSoft, every rule of MuleSoft's out-of-the-box rulesets, grouped by ruleset.

Type in the search box to filter the list. Every word you type must appear somewhere in the rule: its title, rule name, message, the part of the API it applies to, its ruleset or its severity. Rules whose title or name match come first. Use All, P4A recipes or MuleSoft to show one source, and the API type list to show only rules for that type of API. Below them, click a severity (Violation, Warning or Info) or a category, such as one of MuleSoft's rulesets, to show only those rules; click it again or Clear filters to undo it. The panel on the right shows the highlighted rule's details, and for a MuleSoft rule, its YAML.

The recipes are:

• The API title matches a pattern (you set the pattern)
• Paths are kebab-case

For other common checks, such as descriptions, versions, operation IDs, security, 2xx responses or https servers, add the matching rule from MuleSoft's rulesets.

A MuleSoft rule is added exactly as MuleSoft wrote it, as a dashed card (see Rules the form can't show). You can change its severity or remove it on the card, and click Edit YAML to change the rest. If its name is already used in your ruleset, P4A adds -2, -3 and so on. A rule that MuleSoft doesn't list under a severity is added as a warning. P4A won't add a rule whose prefixes conflict with the ones your ruleset already declares.

For anything else, pick Custom rule and choose:

• Applies to: the part of the API the rule checks, such as the API itself, a server, an endpoint, an operation, a response or a parameter.
• Property: what to check on it, such as its description, name or path.
• Check: is required, appears at most N times, must not be present, matches a pattern, is one of these values, has a length between, or is a number between.

A pattern, allowed-values or length check would pass when the property is missing, so the editor also makes the property required. Patterns must match the whole value.

The editor marks any problem on the rule it belongs to, and you can't save until they're fixed.

For checks the form can't build, such as nested or conditional constraints, pick Custom rule (YAML). Name the rule, then write its YAML in the dialog, which starts from an example you can edit: a message, the targetClass it applies to, and its checks. Click Add rule. It's added as a warning, as a dashed card you edit like any other rule the form can't show. A prefix other than the standard ones must first be declared in the YAML tab.

Rules the form can't showCopy Anchor Link

If a rule uses YAML the form doesn't support, the Rules tab shows it as a dashed card with its name, message and severity. You can change the severity or remove the rule there. P4A keeps the rest exactly as written until you change it: click Edit YAML on the card to edit that rule's YAML in a dialog. Apply changes only that rule; the rest of the ruleset stays as it is. In a read-only ruleset the button is View YAML.

Editing the YAMLCopy Anchor Link

The YAML tab shows the full ruleset.yaml. You can edit it directly. Next to it, P4A checks the file's structure as you type: the dialect header, the profile name, the severity lists, and that every listed rule is defined.

For the same check that Anypoint runs, tick Check with the Anypoint CLI validator, pick a workspace and an Anypoint connection, and click Run the CLI check. It uses the connection and counts against a daily limit.

SavingCopy Anchor Link

The editor doesn't save automatically. Click Save, or press Cmd+S (Ctrl+S on Windows and Linux). An Unsaved changes badge shows while you have edits, and the browser asks before you leave the page with them.

If another member saved the ruleset after you opened it, your save is refused and a dialog offers three choices:

• Copy my YAML copies your version to the clipboard, so you can merge it by hand.
• Reload discards your changes and loads their version.
• Overwrite saves your version over theirs.

HistoryCopy Anchor Link

The History section keeps copies of the ruleset's YAML, called snapshots:

• To take one, type a label under Take a snapshot and click Take snapshot. A snapshot copies the saved YAML, so save your changes first.
• Every deploy adds a snapshot marked Deploy, so you can see exactly what was published.
• Restore loads a snapshot into the editor. The ruleset doesn't change until you save.

A workspace ruleset keeps up to 20 snapshots. When you take another, P4A removes the oldest one that no deployment uses.

DeployingCopy Anchor Link

Click Deploy to publish the ruleset to your own Exchange through an Anypoint connection shared into its workspace. If you have unsaved changes, P4A saves them first. There's no review step. The page then jumps to Deployments, which shows each deployment's progress. See Deploying a workspace ruleset for the dialog, versions and governance profiles.

Downloading the filesCopy Anchor Link

Download files gives you ruleset.yaml and a matching exchange.json. Use them with the API Governance CLI, or commit them to a public repository if you want to submit the ruleset to the catalog.

Who can do whatCopy Anchor Link

In an archived workspace, workspace rulesets are read-only. A workspace can hold up to 50 of them.

You can't delete a workspace ruleset while one of its deployments is still in progress. If a deployment is live in Exchange, P4A asks you to confirm first. The published rulesets stay in Exchange, and P4A stops tracking them.

Moving to another workspaceCopy Anchor Link

Click Move in the editor and pick one of your other workspaces. Save your changes first; the button is disabled until you do. You must be an active member of the new workspace, and it counts toward that workspace's limit.

The ruleset keeps its history and its deployments. Members of the old workspace lose access to it, and new deploys use the new workspace's connections. Its earlier deployments stay visible to everyone who shares their connection, but anyone who isn't a member of the new workspace sees them with a Workspace label that doesn't open the ruleset. As with deleting, you can't move it while a deployment is in progress, and P4A asks you to confirm first if one is live in Exchange. If a ruleset in the new workspace already uses the same Exchange asset ID, change this one's asset ID first.

Using your AI agentCopy Anchor Link

Your own agent can do all of this through the P4A MCP server. Start the author_ruleset prompt and describe the rule. The agent writes the YAML, then:

1. saves it as a workspace ruleset with save_ruleset_draft,
2. runs the authoritative check with validate_ruleset, and
3. deploys it with deploy_ruleset_draft, after you confirm.

A workspace ruleset the agent saves opens in the editor too, so you can switch between the two. list_ruleset_drafts, get_ruleset_draft, move_ruleset_draft and delete_ruleset_draft cover the rest. See Authoring a ruleset and the MCP tools reference.