---
title: "Config Item @decorators"
description: A reference page of available env-spec decorators for items
---
import Decorator from '@/components/decorator-doc-entry.astro'
import docsImg from '@/assets/docs/multiple-docs-intellisense.png'

Decorators in a comment block _directly_ preceding a config item will be attached to that item.
Multiple decorators can be specified on the same line.
A comment block is broken by either an empty line or a divider (`# ---` is optional, but often used for clarity).

```env-spec
# @required @sensitive @type=string(startsWith=sk-)
# @docsUrl=https://docs.servicex.com/api-keys
SERVICE_X_API_KEY=
```

More details of the minutiae of decorator handling can be found in the [@env-spec reference](/env-spec/reference/#comments-and-decorators).

## Built-in item decorators

These are the item decorators built into Varlock. [Plugins](/guides/plugins/) can extend the DSL with additional decorators.

<div class="reference-docs">
<div>
### `@required`
**Value type:** `boolean`

Sets whether an item is _required_ - meaning validation will fail if the value resolves to `undefined` or an empty string.

Default behavior for all items within the same file can be toggled using the [`@defaultRequired` root decorator](/reference/root-decorators/#defaultrequired).

💡 Use the [`forEnv()` function](/reference/functions/#forenv) to set required based on the current environment.

```env-spec
# @defaultRequired=false
# ---
# @required # same as @required=true
REQUIRED_ITEM=

# @required=forEnv(prod)
REQUIRED_FOR_PROD_ITEM=

# @required=eq($OTHER, foo)
REQUIRED_IF_OTHER_IS_FOO=
```
</div>

<div>
### `@optional`
**Value type:** `boolean`

Opposite of [`@required`](#required). Equivalent to writing `@required=false`.

```env-spec
# @defaultRequired=true
# ---
# @optional
OPTIONAL_ITEM=
```
</div>

<div>
### `@sensitive`
**Value type:** `boolean`

Sets whether the item should be considered _sensitive_ - meaning it cannot be exposed to the public. The value will be always be redacted in CLI output, and client integrations can take further action to prevent leaks.

Default behavior for all items can be set using the [`@defaultSensitive` root decorator](/reference/root-decorators/#defaultsensitive)

📖 See the [secrets management guide](/guides/secrets/) for best practices on handling sensitive values, and how to use plugins to fetch them from secret management platforms.

```env-spec
# @sensitive
SERVICE_X_PRIVATE_KEY=
# @sensitive=false
SERVICE_X_CLIENT_ID=
```
</div>

<div>
### `@public`
**Value type:** `boolean`

Opposite of [`@sensitive`](#sensitive). Equivalent to writing `@sensitive=false`.

```env-spec
# @defaultSensitive=true
# ---
# @public
PUBLIC_API_URL=https://api.example.com
```
</div>

<div>
### `@type`
**Value type:** [`data type`](/reference/data-types) (name only or function call)

Sets the data type of the item - which affects validation, coercion, and generated types.
Note that some data types take additional arguments. See [data types reference](/reference/data-types) for more details.

If not specified, a data type will be inferred when possible, or default to `string` otherwise.

```env-spec
# @type=url # name only
SOME_URL=

# @type=string(startsWith=abc) # function call with options
EXAMPLE_WITH_TYPE_OPTIONS=

INFER_NUMBER=123 # data type of `number` will be inferred from the value
```
</div>

<div>
### `@example`
**Value type:** `string`

Provides an example value for the item. This lets you avoid setting placeholder values that are not meant to be used.

```env-spec
# @example="sk-abc123"
SECRET_KEY=
```
</div>

<div>
### `@docs()`
**Arg types:** `[ url: string ] | [ description: string, url: string ]`

URL of documentation related to the item. Will be included in [generated types](/reference/root-decorators/#generatetypes). _Can be called multiple times._

```env-spec
# @docs(https://xyz.com/docs/api-keys)
# @docs("Authentication guide", https://xyz.com/docs/auth-guide)
XYZ_API_KEY=
```

<img src={docsImg.src} alt="example of docs() in generated types" style="max-width:280px"/>_example of `docs()` info in generated types / IntelliSense_
</div>

<div>
### `@docsUrl` (deprecated) ||docsurl||
**Value type:** `string`

URL of documentation related to the item.

Use [`@docs()`](#docs) instead, which supports multiple docs entries with optional descriptions.

`@docsUrl=https://example.com` -> `@docs(https://example.com)`
</div>

<div>
### `@icon`
**Value type:** `string`

Attaches an icon identifier to the item, using iconify ids `collection-name:icon-name`. This icon will be included in autogenerated types.

See https://icones.js.org/ to browse available icons.

Useful for generated docs and UI surfaces that show schema metadata.

```env-spec
# @icon=mdi:key
SERVICE_X_API_KEY=
```
</div>

<div>
### `@auditIgnore`
**Value type:** `boolean`

Suppresses "unused in schema" warnings from [`varlock audit`](/reference/cli-commands/#audit) for this item. Useful for items that are only consumed by external tools and won't appear in your application code.

```env-spec
# @auditIgnore
# used by CI tooling, not referenced in code
CI_DEPLOY_TOKEN=
```
</div>
</div>
