# Requirements

Workflow rules and app HTTP handlers can declare a `requirements` object that identifies the custom fields, field values, and system-wide entities that their code expects to find. For a component that is used in a project, YouTrack validates these dependencies against that project. At runtime, YouTrack exposes resolved fields and entities as aliases in the component context.

This mechanism is not available to widgets, utility modules, or custom MCP tools. It is also separate from required app settings declared in `settings.json`.

## Supported Components

| Component | Support | Details |
| --- | --- | --- |
| [Workflow rule](Workflow-Rules.html) | Supported | Declare `requirements` in the rule object passed to the rule constructor. This also applies to workflow rules included in an app package. |
| [App HTTP handler](apps-reference-http-handlers.html) | Supported | Declare `requirements` in the object assigned to `exports.httpHandler`. The requirements apply to every endpoint in the handler. |
| Custom MCP tool | Not supported | The object assigned to `exports.aiTool` does not process a `requirements` property. |
| Utility module | Not supported | A utility module is imported by another backend component and uses values passed to it by the caller. |
| Widget | Not supported | Widget code runs in the browser and accesses YouTrack through the [Host API](apps-host-api.html). |

## Requirement Categories

| Category | Purpose | Examples |
| --- | --- | --- |
| Project-wide | Identifies custom fields that must be attached to the project associated with the component, including required field values and cardinality. | Priority field with a Major value, or a multi-value Assignee field. |
| System-wide | Identifies entities that must exist in YouTrack independently of a specific project. | Users, groups, projects, issues, tags, saved searches, and issue link types. |

### Validation

For a component that is used in a project, YouTrack validates its requirements against that project. If a required field, value, or entity cannot be resolved, YouTrack reports a problem for the component and does not make it available in that project until the problem is fixed.

A global HTTP handler does not have a project context. It can use system-wide requirements to expose entity aliases, but project-wide requirements can provide field aliases only when the handler invocation has a corresponding project context.

> **Note:**
> Declaring a requirement does not grant additional permissions. Access to the resolved entity and its properties remains subject to the permissions of the execution context.

### Context Aliases

Every entry in a `requirements` object has an alias. By default, the alias is also used as the name of the required field, value, or entity. Set the `name` property when the actual name is different.

* A system-wide entity is available as `ctx.<alias>`.

* A custom field is available as `ctx.<field-alias>` when the context contains a project.

* When the context contains an issue, a required field value is available as `ctx.<field-alias>.<value-alias>`, and the issue field value can also be accessed through `ctx.issue.fields.<field-alias>` or the actual field name.

## Examples

### Workflow Rule Example

The following on-change rule requires the Priority and Assignee fields, the Major priority value, and a user with the `qa.lead` login. The rule uses aliases from the requirements to update an issue.

```JAVASCRIPT
const entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.rule = entities.Issue.onChange({
  title: 'Escalate reopened issues',
  guard: (ctx) => ctx.issue.becomesUnresolved,
  action: (ctx) => {
    ctx.issue.fields.Priority = ctx.Priority.Major;
    ctx.issue.fields.Assignee = ctx.QALead;
  },
  requirements: {
    Priority: {
      type: entities.EnumField.fieldType,
      Major: {}
    },
    Assignee: {
      type: entities.User.fieldType
    },
    QALead: {
      type: entities.User,
      login: 'qa.lead'
    }
  }
});
```

### HTTP Handler Example

The following issue-scoped handler declares a project field and a system-wide user requirement. Because an issue-scoped invocation has both issue and project context, the handler can use the field and value aliases as well as the user alias.

```JAVASCRIPT
const entities = require('@jetbrains/youtrack-scripting-api/entities');

exports.httpHandler = {
  endpoints: [
    {
      method: 'GET',
      path: 'required-values',
      scope: 'issue',
      handle: (ctx) => {
        ctx.response.json({
          priority: ctx.Priority.Major.name,
          qaLead: ctx.QALead.login
        });
      }
    }
  ],
  requirements: {
    Priority: {
      type: entities.EnumField.fieldType,
      Major: {}
    },
    QALead: {
      type: entities.User,
      login: 'qa.lead'
    }
  }
};
```

## Requirement Properties

| Property | Required | Description |
| --- | --- | --- |
| `type` | Yes | The field type or entity constructor used to resolve and validate the requirement. |
| `name` | No | The actual name of the field, field value, or named entity. When omitted, YouTrack uses the requirement alias as the name. Users, issues, and issue link types use their type-specific identifying properties instead. |
| `multi` | No | For a custom field requirement, set to `true` when the field must store multiple values. The default is `false`. |

### Custom Field Types

| Custom field type | `type` value |
| --- | --- |
| Build | `entities.Build.fieldType` |
| Enum | `entities.EnumField.fieldType` |
| Group | `entities.UserGroup.fieldType` |
| Owned field | `entities.OwnedField.fieldType` |
| State | `entities.State.fieldType` |
| User | `entities.User.fieldType` |
| Version | `entities.ProjectVersion.fieldType` |
| Date | `entities.Field.dateType` |
| Date and time | `entities.Field.dateTimeType` |
| Float | `entities.Field.floatType` |
| Integer | `entities.Field.integerType` |
| String | `entities.Field.stringType` |
| Text | `entities.Field.textType` |
| Period | `entities.Field.periodType` |

### System-wide Entity Types

| Entity | `type` value | Identifying property |
| --- | --- | --- |
| User | `entities.User` | `login` |
| User group | `entities.UserGroup` | `name` |
| Project | `entities.Project` | `name` |
| Issue | `entities.Issue` | `id` |
| Tag | `entities.IssueTag` | `name` |
| Saved search | `entities.SavedQuery` | `name` |
| Issue link type | `entities.IssueLinkPrototype` | `inward` or `outward` |

Project teams are represented as user groups. To require a project team, use `entities.UserGroup` and set `name` to the project team name.

### Custom Field Value Aliases

For an enum, state, owned, version, build, user, or group field requirement, each additional property represents a required value from the field's value set. The property key is the value alias. Add `name` when the actual value name is different from the alias.

```JAVASCRIPT
requirements: {
  P: {
    type: entities.EnumField.fieldType,
    name: 'Priority',
    M: {name: 'Major'},
    Normal: {}
  }
}
```

This example exposes the field as `ctx.P`, the Major value as `ctx.P.M`, and the Normal value as `ctx.P.Normal`.