# ambiguous-scope

**Summary**: Ambiguous metadata scope

**Category**: Idiomatic

**Avoid**

```
package policy# METADATA# description: allow is true if the user is admin, or the requested resource is publicallow if user_is_adminallow if public_resource
```

**Prefer**

```
package policy# METADATA# description: allow is true if the user is admin, or the requested resource is public# scope: documentallow if user_is_adminallow if public_resource
```

**Or (scope `rule` implied, but _all_ incremental definitions are annotated)**

```
package policy# METADATA# description: allow is true if the user is adminallow if user_is_admin# METADATA# description: allow is true if the requested resource is publicallow if public_resource
```

**Or (scope `rule` explicit)**

```
package policy# METADATA# description: allow is true if the user is admin# scope: ruleallow if user_is_adminallow if public_resource
```

## Rationale

The default scope for metadata annotating a rule is the `rule` scope, which "[applies to the individual rule statement](https://www.openpolicyagent.org/docs/policy-language/#scope)" only. This default is sensible for a rule defined only once, but is somewhat ambiguous for a rule defined incrementally, like the `allow` rule in the examples above. Was the intention really to annotate that single definition, or the rule as whole? Most likely the latter, and that's what the `document` scope is for.

If only a single rule in a group of incremental rule definitions is annotated, it should have its `scope` set explicitly to either `document` or `rule`. If all incremental definitions are annotated, explicit `scope: rule` is not required.

## Exceptions

If a single incremental rule definition is annotated as `entrypoint: true`, this rule will allow that.

## Configuration Options

This linter rule provides the following configuration options:

```
rules:  idiomatic:    ambiguous-scope:      # one of "error", "warning", "ignore"      level: error
```

## Related Resources

*   OPA Docs: [Annotations](https://www.openpolicyagent.org/docs/policy-language/#annotations)
*   Regal Docs: [no-defined-entrypoint](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/no-defined-entrypoint)
*   GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/idiomatic/ambiguous-scope/ambiguous_scope.rego)