> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winningvariant.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subjects
> Identifiers that may be used in experiments.
Winning Variant considers a subject anything that is assigned a variant within an experiment. Think of a subject as a patient in a drug trial. Traditionally, a subject is a user (known or anonymous), but can be any other *thing* that seems one thing over another, such as a mobile or IoT device.
Subjects can have various ways of being identified (such as a known customer ID or an anonymous cookie ID). We call these *Subject Types* and are completely customizable within the platform. Here are some examples of typical Subject Types:
* **Anonymous User ID**: such as a random UUID stored in a cookie in a user’s browser
* **User/Customer ID**: a persistent ID that tells you exactly who someone is. Values used here are sometimes the CRM ID (such as Salesforce ID) or primary key in your own database.
* **MAC Address**: when experiment assignments are done at the device level.
* **Customer Group**: if you wish for all users within a particular customer group/segment to experiment the same experiment variation, you can use this level of grouping.
All possible Subject Types can exist at once within the platform and are used only for the experiments that depend on them.
## YAML
### Metadata
The possible statuses for subject types are: `active` or `archived`. `parentKind` and `parentId` should be excluded.
When defining a resource in YAML, each must have a `metadata` section. The following properties within `metadata` are shared across all resource types:
| Key | Data Type | Description |
| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. Case insensitive and consist of alphanumeric characters, '-', '\_' or '.’ For example: `home-page-test`. IDs will be stored and displayed in UPPERCASE. |
| `name` | `string` | Name of the resource. |
| `description` | `string` | Description of the resource. |
| `resourceVersion` | `int` | Modification version for a given resource. Incremented each time the resource is updated. This will be shown when retreiving a resource, but is ignored if provided as part of a resource update. |
| `status` | [`ResourceStatus`](#resourcestatus) | The status of the resource. |
| `parentKind` | `lab` | The kind of resouce this one belongs to. Only applies to experiments, in which case the value is `lab`. Exclude for non experiments. |
| `parentId` | `string` | The ID of the resources parent. Only applies to experiments and the ID of its parent lab. Exclude for non experiments.
If an experiment does not specified a `parentID`, it defaults to `DEFAULT`. |
#### `ResourceStatus`
Possible statuses include:
| Status | Description | Resources |
| ----------------- | ---------------------------------------------------------------- | ---------- |
| `draft` | The experiment exists, but is not ready to go live. | Experiment |
| `active` | The experiment is live and making/tracking/returned assignments. | All |
| `winner_declared` | A winner has been declared. | Experiment |
| `ended` | The experiment has ended. No assignments are made/returned. | Experiment |
| `archived` | The experiment has ended and is archived from view. | All |
### Spec
The `spec` for a Subject Type includes the following:
| Key | Data Type | Description |
| ------------ | ------------------------- | --------------------------------------------------------------------------------- |
| `matchType` | [`MatchType`](#matchtype) | The type of subject and how to match identifiers. See below. |
| `matchRegex` | `string` | If Match Type is CUSTOM, this specifies the Regex to use to validate identifiers. |
#### `MatchType`
Built-in Subject Type match types include:
| Match Type | Description | Regex Used |
| ------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `UUID` | a standard UUID of any version | `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$` |
| `MAC_ID` | A computer MAC address | `^([0-9A-Fa-f]{2}[:]){5}([0-9A-Fa-f]{2})$` |
| `KSUID` | Segment [KSUID](https://github.com/segmentio/ksuid) | `^[0-9a-zA-Z]{27}$` |
| `IOS_INSTALLATION_ID` | iOS Installation ID | `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$` |
| `ANDROID_INSTALLATION_ID` | Android Installation ID | `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$` |
| `AUTH0_ID` | ID for [Auth0](https://auth0.com/) user accounts. | `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89abAB][0-9a-f]{3}-[0-9a-f]{12}$` |
| `SEGMENT_ID` | [Segment](https://segment.com/) user IDs | `^[0-9a-f]{32}$` |
| `CUSTOM` | Custom regular expression validation. | Specified by `match_regex` |
### Examples
```yaml UUID Type theme={null}
schemaVersion: 1
kind: subjecttype
metadata:
id: customer_id
status: active
name: Customer ID
description: Internal customer ID for a user.
spec:
matchType: uuid
```
```yaml Custom theme={null}
schemaVersion: 1
kind: subjecttype
metadata:
id: employee_id
status: active
name: Dunder Mifflin employee ID
description: Internal identifier used to identify Dunder Mifflin employees.
spec:
matchType: custom
matchRegex: "^[0-9]{6}$"
```