author-governance-ruleset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Governance Ruleset Author

API Governance 规则集编写者

Write valid Anypoint API Governance rulesets (Validation Profile 1.0 YAML) using the governance CLI tools for model discovery, validation, and simplification.

编写有效的 Anypoint API Governance 规则集（Validation Profile 1.0 YAML），并使用 Governance CLI 工具完成模型发现、验证和简化。

Overview

概述

A governance ruleset is a YAML file that starts with

#%Validation Profile 1.0

and declares validation rules against a domain model (API specs, API instances, MCP servers, etc.). Each rule targets a class, constrains its properties, and is assigned a severity (violation, warning, info).

This skill uses the

anypoint-cli-v4 governance:ruleset

CLI commands to discover the model, validate rulesets, and simplify output. Do NOT guess class names, property names, or constraint compatibility — always query the CLI.

Governance 规则集是一个以

#%Validation Profile 1.0

开头的 YAML 文件，用于针对领域模型（API specs、API instances、MCP servers 等）声明验证规则。每条规则都有一个目标 class，约束其 properties，并指定严重级别（violation、warning、info）。

此 skill 使用

anypoint-cli-v4 governance:ruleset

CLI 命令发现模型、验证规则集并简化输出。不要猜测 class 名称、property 名称或约束兼容性——始终应查询 CLI。

Prerequisite: Ensure the Governance Plugin Version

前置条件：确保 Governance Plugin 版本

Before running any governance CLI commands, force-install the latest governance plugin so the model, constraints, and validation logic match this skill. Version 1.0.20 or greater is required:

bash

anypoint-cli-v4 plugins:install mulesoft-anypoint-cli-governance-plugin@latest

Run this every time the skill starts, even if the plugin appears to already be installed —

@latest

guarantees a compatible version (1.0.20 or newer). Only proceed to the steps below once this completes successfully.

运行任何 Governance CLI 命令前，强制安装最新 Governance plugin，确保模型、约束和验证逻辑与此 skill 匹配。要求版本为 1.0.20 或更高：

bash

anypoint-cli-v4 plugins:install mulesoft-anypoint-cli-governance-plugin@latest

每次启动此 skill 时都应运行此命令，即使该 plugin 看起来已经安装——

@latest

可确保使用兼容版本（1.0.20 或更高）。仅在此命令成功完成后继续执行后续步骤。

Step 1: Understand the Intent

第 1 步：理解意图

Parse the user request. Identify:

What class/node is being targeted (e.g., Operation, WebAPI, APIInstance, MCPServer)
What property is being constrained (e.g., description, version, policies)
What condition must hold (e.g., must exist, must match a pattern, must have at least one)

If the user uses domain language (e.g., "consumerUrl", "endpointUrl", "rate-limit policy"), resolve it:

bash

anypoint-cli-v4 governance:ruleset:resolve <term>

Aliases are author-time helpers ONLY — they must NEVER appear in the ruleset YAML. Use the canonical targetClass + path returned by the resolve command.

解析用户请求。确定：

目标 class/node（例如 Operation、WebAPI、APIInstance、MCPServer）
要约束的 property（例如 description、version、policies）
必须满足的条件（例如必须存在、必须匹配某个模式、必须至少包含一个）

如果用户使用领域语言（例如“consumerUrl”、“endpointUrl”、“rate-limit policy”），则进行解析：

bash

anypoint-cli-v4 governance:ruleset:resolve <term>

Aliases 仅是编写阶段的辅助工具——绝不能出现在规则集 YAML 中。使用 resolve 命令返回的规范 targetClass + path。

Step 2: Pick the Domain

第 2 步：选择领域

List available domains and match the user intent:

bash

anypoint-cli-v4 governance:ruleset:domains

Critical rule: A single ruleset must target only ONE specKind. Never combine

api-spec

and

mcp

targets in the same ruleset. Domains without a specKind mix freely.

列出可用领域并匹配用户意图：

bash

anypoint-cli-v4 governance:ruleset:domains

关键规则： 单个规则集只能针对一种 specKind。绝不能在同一规则集中组合

api-spec

和

mcp

目标。不涉及 specKind 的领域可以自由组合。

Step 3: Discover the Model

第 3 步：发现模型

List the targetable classes for the chosen domain:

bash

anypoint-cli-v4 governance:ruleset:classes --domain <domain-name>

Then list properties and their types for the specific class:

bash

anypoint-cli-v4 governance:ruleset:properties <prefix.ClassName>

The property type (scalar, node, scalarArray, nodeArray) determines which constraints are valid.

列出所选领域中可作为目标的 classes：

bash

anypoint-cli-v4 governance:ruleset:classes --domain <domain-name>

然后列出特定 class 的 properties 及其类型：

bash

anypoint-cli-v4 governance:ruleset:properties <prefix.ClassName>

Property 类型（scalar、node、scalarArray、nodeArray）决定哪些约束有效。

Step 4: Choose Constraints

第 4 步：选择约束

Query valid constraints for the property type:

bash

anypoint-cli-v4 governance:ruleset:constraints --type <propertyType>

Where

<propertyType>

is one of:

scalar

node

scalarArray

nodeArray

Common mistakes to avoid:

NEVER use
```
pattern
```
or
```
in
```
on a nodeArray or node property
Use
```
atLeast
```
/
```
atMost
```
on nodeArray to check "at least one item matches X"
Use
```
containsSome
```
on scalarArray to check "at least one value is X"
Use
```
in
```
on scalarArray to restrict ALL values to an allowed set
Property paths using
```
/
```
traverse nested nodes; the LAST property determines valid constraints

查询适用于 property 类型的有效约束：

bash

anypoint-cli-v4 governance:ruleset:constraints --type <propertyType>

其中

<propertyType>

为以下值之一：

scalar

、

node

、

scalarArray

、

nodeArray

。

需要避免的常见错误：

绝不要对 nodeArray 或 node property 使用
```
pattern
```
或
```
in
```
对 nodeArray 使用
```
atLeast
```
/
```
atMost
```
，以检查“至少一个 item 与 X 匹配”
对 scalarArray 使用
```
containsSome
```
，以检查“至少一个 value 等于 X”
对 scalarArray 使用
```
in
```
，将所有 values 限制在允许的集合内
使用
```
/
```
的 property paths 用于遍历嵌套 nodes；最后一个 property 决定有效的约束

Step 5: Write the Ruleset

第 5 步：编写规则集

Write valid Validation Profile 1.0 YAML to a file:

yaml

#%Validation Profile 1.0
profile: <profile-name>
prefixes:                    # Only needed for non-default namespaces
  management: http://anypoint.com/vocabs/management#
validations:
  <rule-name>:
    targetClass: <prefix.ClassName>
    message: <human-readable error message>
    propertyConstraints:
      <prefix.propertyName>:
        <constraint>: <value>
violation:                   # MUST assign every rule to a severity
  - <rule-name>
warning:
  - <other-rule>
info:
  - <another-rule>

Default prefixes (do NOT redeclare these):

apiContract

core

shacl

shapes

raml-shapes

doc

meta

security

data

xsd

rdfs

rdf

sourcemaps

Non-default prefixes (MUST declare in

prefixes:

block):

management: http://anypoint.com/vocabs/management#

mulesoft: http://anypoint.com/vocabs/management#mulesoft.com/

```
gcl: http://anypoint.com/vocabs/gcl#
```
```
api: http://anypoint.com/vocabs/api#
```

catalog: http://anypoint.com/vocabs/digital-repository#

```
mcp: http://anypoint.com/vocabs/mcp#
```

apiExt: http://a.ml/vocabularies/api-extension#

将有效的 Validation Profile 1.0 YAML 写入文件：

yaml

#%Validation Profile 1.0
profile: <profile-name>
prefixes:                    # Only needed for non-default namespaces
  management: http://anypoint.com/vocabs/management#
validations:
  <rule-name>:
    targetClass: <prefix.ClassName>
    message: <human-readable error message>
    propertyConstraints:
      <prefix.propertyName>:
        <constraint>: <value>
violation:                   # MUST assign every rule to a severity
  - <rule-name>
warning:
  - <other-rule>
info:
  - <another-rule>

默认 prefixes（不要重新声明）：

apiContract

、

core

、

shacl

、

shapes

、

raml-shapes

、

doc

、

meta

、

security

、

data

、

xsd

、

rdfs

、

rdf

、

sourcemaps

非默认 prefixes（必须在

prefixes:

块中声明）：

management: http://anypoint.com/vocabs/management#

mulesoft: http://anypoint.com/vocabs/management#mulesoft.com/

```
gcl: http://anypoint.com/vocabs/gcl#
```
```
api: http://anypoint.com/vocabs/api#
```

catalog: http://anypoint.com/vocabs/digital-repository#

```
mcp: http://anypoint.com/vocabs/mcp#
```

apiExt: http://a.ml/vocabularies/api-extension#

Step 6: Validate the Ruleset

第 6 步：验证规则集

After writing or modifying a ruleset, validate it with the CLI:

bash

anypoint-cli-v4 governance:ruleset:validate-authoring <path-to-ruleset.yaml>

This checks: YAML syntax, JSON schema conformance, targetClass validity, property path correctness, constraint-type compatibility, and severity assignments.

If validation returns errors, fix them and re-validate. Do NOT present a ruleset to the user until it passes validation with zero errors.

编写或修改规则集后，使用 CLI 进行验证：

bash

anypoint-cli-v4 governance:ruleset:validate-authoring <path-to-ruleset.yaml>

此命令将检查：YAML 语法、JSON Schema 一致性、targetClass 有效性、property path 正确性、约束类型兼容性以及严重级别分配。

如果验证返回错误，请修复错误并重新验证。在规则集通过验证且错误数为零之前，不要将其呈现给用户。

Step 7: Simplify

第 7 步：简化

Once validation passes, simplify the ruleset:

bash

anypoint-cli-v4 governance:ruleset:simplify <path-to-ruleset.yaml>

This flattens nested property paths and removes redundant logical wrappers. If changes are made, write the simplified output back to the file and validate again.

验证通过后，简化规则集：

bash

anypoint-cli-v4 governance:ruleset:simplify <path-to-ruleset.yaml>

此操作会扁平化嵌套 property paths，并移除冗余的逻辑包装器。如果发生更改，请将简化后的输出写回文件，并再次进行验证。

Step 8: Present the Result

第 8 步：呈现结果

Show the final validated and simplified ruleset to the user. Briefly explain:

What it checks
Which constraints were chosen and why
The severity assignments

向用户展示最终经过验证和简化的规则集。简要说明：

此规则集的检查内容
所选择的约束及其原因
严重级别的分配方式

Rules

规则

ALWAYS start with
```
#%Validation Profile 1.0
```
on line 1
ALWAYS assign every validation to a severity level (violation, warning, or info)
NEVER use an alias in the ruleset YAML — always use canonical targetClass + property path
NEVER combine api-spec and mcp targets in the same ruleset
NEVER guess property names — always run
```
governance:ruleset:properties <class>
```
to look them up
NEVER guess constraint compatibility — always run
```
governance:ruleset:constraints --type <type>
```
ALWAYS validate with
```
governance:ruleset:validate-authoring
```
after every write or modification
ALWAYS simplify with
```
governance:ruleset:simplify
```
after validation passes
Property paths use
```
/
```
(space-slash-space) to separate segments
Alternate paths use
```
|
```
(space-pipe-space) between alternatives wrapped in
```
( )
```
For conditional rules, use
```
if:
```
/
```
then:
```
at the validation level
For logical combinations, use
```
and:
```
,
```
or:
```
,
```
not:
```
, or
```
xone:
```
at the validation level
Rego (
```
rego:
```
) is a last resort for cross-resource checks — prefer declarative constraints
Message templates can reference property values:
```
"{{ prefix.property }}"
```
When modifying an existing ruleset, apply the change then re-validate
If the user asks about supported domains, run
```
governance:ruleset:domains
```
— never claim something is unsupported without checking

始终在第 1 行以
```
#%Validation Profile 1.0
```
开头
始终为每项验证分配严重级别（violation、warning 或 info）
绝不要在规则集 YAML 中使用 alias——始终使用规范 targetClass + property path
绝不要在同一规则集中组合 api-spec 和 mcp 目标
绝不要猜测 property 名称——始终运行
```
governance:ruleset:properties <class>
```
进行查询
绝不要猜测约束兼容性——始终运行
```
governance:ruleset:constraints --type <type>
```
每次写入或修改后，始终使用
```
governance:ruleset:validate-authoring
```
进行验证
验证通过后，始终使用
```
governance:ruleset:simplify
```
进行简化
Property paths 使用
```
/
```
（空格-斜杠-空格）分隔各段
Alternate paths 使用
```
|
```
（空格-竖线-空格）分隔 alternatives，并使用
```
( )
```
包裹
对于条件规则，在 validation 层级使用
```
if:
```
/
```
then:
```
对于逻辑组合，在 validation 层级使用
```
and:
```
、
```
or:
```
、
```
not:
```
或
```
xone:
```
Rego（
```
rego:
```
）是执行跨资源检查时的最后手段——优先使用声明式约束
Message templates 可以引用 property values：
```
"{{ prefix.property }}"
```
修改现有规则集时，应用更改后重新进行验证
如果用户询问支持的 domains，请运行
```
governance:ruleset:domains
```
——未经检查，绝不要声称某项功能不受支持