Introduction

AWS IAM policies are JSON documents, and standard JSON does not support comments. That means you cannot insert slash comments or hash comments directly into the policy body and still expect IAM to accept it. The practical solution is to keep the deployed JSON valid while putting human-readable explanation in places IAM and your team can both work with.

Why JSON Comments Fail

IAM policy parsing starts with JSON parsing. If the document is not valid JSON, IAM never gets as far as evaluating the permissions.

A valid IAM policy looks like this:

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": ["s3:GetObject"],
7      "Resource": ["arn:aws:s3:::my-bucket/*"]
8    }
9  ]
10}

If you add //, #, or block-style comments directly into that document, the file stops being valid JSON and the policy cannot be used.

Use Sid for Short In-Document Meaning

IAM does give you one field that helps readability: Sid. It is not a free-form comment system, but it is a useful short label for a statement's purpose.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Sid": "AllowCiReadBuildArtifacts",
6      "Effect": "Allow",
7      "Action": ["s3:GetObject"],
8      "Resource": ["arn:aws:s3:::company-build-artifacts/*"]
9    }
10  ]
11}

A descriptive Sid such as AllowCiReadBuildArtifacts is much more useful than values like Stmt1 or PolicyPartA.

Put Long Explanations in Infrastructure Code

If the policy is managed through Terraform, CloudFormation, CDK, Pulumi, or another infrastructure tool, put the longer explanation next to the policy definition in that source code.

1# CI jobs need read-only access to build artifacts.
2# Write and delete permissions are intentionally excluded.
3resource "aws_iam_policy" "ci_artifacts_read" {
4  name   = "ci-artifacts-read"
5  policy = jsonencode({
6    Version = "2012-10-17"
7    Statement = [{
8      Sid      = "AllowCiReadBuildArtifacts"
9      Effect   = "Allow"
10      Action   = ["s3:GetObject"]
11      Resource = ["arn:aws:s3:::company-build-artifacts/*"]
12    }]
13  })
14}

That keeps the deployed document valid while preserving the reasoning in version-controlled source.

Use Pull Requests and Policy Simulation

When inline comments are not available, review workflow becomes even more important. A good practice is to combine descriptive Sid values with:

• a pull-request explanation
• ticket or incident references
• IAM policy simulation

Example simulation command:

1aws iam simulate-custom-policy \
2  --policy-input-list file://policy.json \
3  --action-names s3:GetObject s3:PutObject \
4  --resource-arns arn:aws:s3:::company-build-artifacts/example.txt

That turns the discussion from "what does this JSON mean" into "what behavior does this policy actually allow."

Keep Policies Small Enough to Understand

Large, mixed-purpose statements are hard to explain even with good Sid values. Smaller statements with a focused purpose are easier to:

• review
• audit
• simulate
• remove later

If you find yourself wanting large comment blocks inside the policy, that is often a sign the policy should be broken into smaller, more purposeful units.

Use Metadata Outside the Policy Body

If your process truly needs rich human commentary, keep that metadata outside the JSON:

• in the repository README
• in architecture docs
• in the IaC source file
• in pull request history
• in policy naming conventions

That makes the explanation durable without making the policy invalid.

Common Pitfalls

The biggest pitfall is trying to insert comment syntax directly into IAM policy JSON. That simply makes the document invalid.

Another common issue is wasting the Sid field on meaningless labels. If you only get one short descriptive field, it should carry useful intent.

Teams also sometimes keep the policy valid but store the rationale only in someone's memory, which makes future audits and incident review much harder.

Summary

• IAM policy JSON does not support inline comments because JSON itself does not support comments.
• Use descriptive Sid values as short intent labels inside the policy.
• Put detailed explanations in Terraform, CloudFormation, CDK, or other surrounding source files.
• Use pull requests and IAM simulation to document and verify permission intent.
• Keep policies focused enough that their purpose is understandable without needing fake comments in the JSON body.