P4A DocumentationAuthoring a ruleset
Write an API Governance ruleset with your own AI agent and the P4A MCP server, validate it as you go, and submit it for review.
Overview
P4A doesn't run an AI model. Your own agent (Claude Code, Cursor, or any MCP client connected to the P4A MCP server) writes the ruleset, and P4A gives it the dialect rules and a validator so the result is correct. The loop is:
- Ask the agent to use the
author_rulesetprompt and describe the rule in plain English. - The agent writes a draft and calls
validate_ruleset. - It fixes whatever the validator reports and repeats until the result is
valid: true. - You commit the file to a public repository.
- The agent submits it with
submit_ruleset, and it goes to review. See Submitting a ruleset.
Once it's approved, you can publish it to Exchange.
Before you start
- Connect your agent to P4A. See Connecting to the MCP server.
- Have a public repository ready for the ruleset file.
- For the final, authoritative check you also need a registered Anypoint connection. See Connecting your Anypoint ORG.
Step 1: describe the rule
Start the author_ruleset prompt and put your rule in the optional rule argument. The prompt gives your agent the Validation Profile dialect, the three severities, rule and constraint examples, and the common pitfalls, so you don't have to explain the format. A good request names the thing being checked, the condition, and how serious a miss is:
Every operation needs a description, and every API needs a title. A missing title blocks conformance. A missing description is only a warning.
The agent produces a profile like this:
#%Validation Profile 1.0
profile: API basics
description: Minimum documentation rules for REST APIs.
violation:
- api-has-title
warning:
- operations-have-descriptions
validations:
api-has-title:
message: The API must have a title.
targetClass: apiContract.WebAPI
propertyConstraints:
core.name:
minCount: 1
operations-have-descriptions:
message: Every operation should have a description.
targetClass: apiContract.Operation
propertyConstraints:
core.description:
minCount: 1Severity decides the outcome. A rule under violation makes an API non-conformant, warning is worth fixing but doesn't block, and info is advice only.
Step 2: start from an existing ruleset (optional)
If you want to adapt an existing rule, ask the agent to call fork_mulesoft_ruleset with a MuleSoft ruleset's slug, or fork_ruleset with a community ruleset's id. You can find both on the Rulesets page or with search_rulesets. In the portal, Customize this ruleset on a ruleset's page shows the same files. The tool returns:
- the ruleset's Validation Profile YAML
- a suggested
exchange.jsonwith a new asset ID, a(custom)name, and version1.0.0 - the files to commit to your own repository
- the next steps
P4A doesn't create the repository. You copy the files into your own and edit them from there. Your fork needs its own asset ID, because you can't publish over the original. See Creating Custom Rulesets by Modifying Published Rulesets.
Step 3: validate until it passes
validate_ruleset takes the YAML and returns valid, a list of errors with a 1-based line where it can tell, the profile name, and the rule names with counts per severity. The same check is available over REST as POST /api/rulesets/validate, and in the portal as Validate a ruleset on the Rulesets page, where you paste the YAML.
There are two levels:
| Quick check | Authoritative check | |
|---|---|---|
| How to ask | The default (authoritative: false) | authoritative: true, plus connectionId and workspaceId |
| What it does | Checks the file's structure: dialect header, profile name, severity lists, and that every listed rule is defined | Runs the same validator Anypoint uses, with your connection |
| Speed | Instant | Waits up to about 30 seconds |
| Limits | None beyond normal API limits | Counts against a daily limit, and is unavailable while deployments are paused |
If the authoritative check is still running when the wait ends, the result is pending: true with a jobId. Call validate_ruleset again with only that jobId (no YAML) to fetch the result.
A ruleset that fails the authoritative check isn't an error in P4A. You get valid: false and the validator's messages, so your agent can fix the rule and try again.
The quick check looks at the profile's structure. It doesn't run your rules against a real API. Use the authoritative check, or test locally with the API Governance CLI, before you rely on a rule. See Validating and Publishing Custom Rulesets.
Step 4: commit and submit
Commit the file as ruleset.yaml in a public repository, with the exchange.json if you have one, and ask the agent to call submit_ruleset with the repository URL. P4A re-checks the repository before accepting the submission, then it follows the normal review path. The submission guide lists every check and how to fix a failure.
Tips for better rules
- Keep one concern per rule, and give each a clear
message. The message is what an API author sees when the rule fails. - Start a new rule as a
warningand promote it toviolationonce teams have had time to fix their APIs. - Validate after every change. Small drafts are easier for the agent to repair than a large one.