Validating a Policy

Function

This API is used to validate a policy and return a list of findings.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
AccessAnalyzer::validatePolicy	Read	-	-	-	-

URI

POST /v5/policies/validate

**Table 1** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	Integer	Maximum number of results on a page Minimum: 1 Maximum: 200 Default: 100
marker	No	String	Page marker Minimum: 4 Maximum: 400

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Language	No	String	Language of the returned message. The default value is 'zh-cn'. zh-cn: Chinese en-us: English Default: zh-cn

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
policy_document	Yes	String	JSON policy document.
policy_type	Yes	String	Type of the policy to be validated. identity_policy: identity policy resource_policy: resource policy service_control_policy: service control policy resource_control_policy: resource control policy network_control_policy: network control policy
validate_policy_resource_type	No	String	The type of resource to attach to your resource policy. iam:agency: IAM agency

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
findings	Array of ValidatePolicyFinding objects	Actionable recommendation that can be used to improve the policy.
page_info	PageInfo object	Information on the page

**Table 5** ValidatePolicyFinding
Parameter	Type	Description
finding_details	String	A localized message that explains the finding and provides guidance on how to address it
finding_type	String	Impact level. security_warning: There are security risks, which may be caused by overly permissive access. error: There are errors that prevent the policy from functioning, such as syntax errors or invalid parameters. If an error occurs, the policy cannot be created. warning: There are warnings that prevent the policy from functioning, such as a mismatch between a parameter type and a value. The policy can still be created even if there is a warning. suggestion: There are suggestions for the policy to achieve expected results. For example, suggestions are given when there are empty arrays or empty objects.
issue_code	String	Provides an identifier of the issue associated with the validation check findings.
learn_more_link	String	Links to related documents associated with the validation check findings.
locations	Array of Location objects	List of locations that are related to the validation check findings in the policy document.

**Table 6** Location
Parameter	Type	Description
path	Array of PathElement objects	A path in a policy, represented as a sequence of path elements
span	Span object	Span of the cursor in a policy, consisting of a start position (inclusive) and end position (exclusive)

**Table 7** PathElement
Parameter	Type	Description
index	Integer	Index in a JSON array, starting from 0
key	String	Key in a JSON object
substring	Substring object	Substring of a literal string in a JSON object
value	String	Value associated with a given key in a JSON object

**Table 8** Substring
Parameter	Type	Description
start	Integer	Start index of the substring, starting from 0. The value 0 indicates the first character.
length	Integer	Length of the substring

**Table 9** Span
Parameter	Type	Description
start	Position object	Position in a policy
end	Position object	Position in a policy

**Table 10** Position
Parameter	Type	Description
line	Integer	Line of the position, starting from 1
column	Integer	Column of the position, starting from 0.
offset	Integer	Offset within the policy that corresponds to the position, starting from 0.

**Table 11** PageInfo
Parameter	Type	Description
current_count	Integer	Number of items on the current page
next_marker	String	If present, it indicates that the available output is more than the output contained in the current response. Use this value in the marker request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this operation until the next_marker response returns null.

Example Requests

Requesting the validation of a policy and returning a list of findings

POST https://{hostname}/v5/policies/validate

{
  "policy_document" : "",
  "policy_type" : "identity_policy"
}

Example Responses

Status code: 200

{
  "findings" : [ {
    "finding_details" : "Fix the JSON syntax error in row 1 and column 0 of index 0.",
    "finding_type" : "error",
    "issue_code" : "JSON_SYNTAX_ERROR",
    "learn_more_link" : "https://{endpoint}/section0",
    "locations" : [ {
      "path" : [ ],
      "span" : {
        "start" : {
          "line" : 1,
          "column" : 0,
          "offset" : 0
        },
        "end" : {
          "line" : 1,
          "column" : 1,
          "offset" : 1
        }
      }
    } ]
  } ],
  "page_info" : {
    "current_count" : 1,
    "next_marker" : null
  }
}