> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dry-run validation

> Validate supported writes against current scope and state without persistence or documented side effects.

Supported write operations accept:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
dryRun=true
```

## Supported operations

| Operation                   | Dry-run result                                       | Suppressed effect                         |
| --------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Create employee             | Projected employee                                   | Account creation and password setup email |
| Update employee             | Projected employee                                   | Stored employee update                    |
| Decide order                | Projected order                                      | Decision and notifications                |
| Create incident             | Projected incident                                   | Incident creation                         |
| Update incident             | Projected incident                                   | Stored incident update                    |
| Upload incident attachments | Validation result / projected resource as documented | File storage                              |
| Create division             | Projected division                                   | Division creation                         |
| Update division             | Projected division                                   | Stored division update                    |

## Request sequence

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Client
    participant API as JobHandy API
    Client->>API: Write request with dryRun=true
    API->>API: Authenticate and enforce scope
    API->>API: Validate schema, references, and current state
    API-->>Client: Projected resource or error
    Client->>Client: Review projection
    Client->>API: Same write without dryRun
    API->>API: Revalidate current state
    API-->>Client: Persisted resource or current error
```

## Guarantees and non-guarantees

A successful dry run confirms that the request passed validation at that moment. It does not:

* reserve an identifier, resource, name, or position
* lock the resource
* create an idempotency record
* guarantee the subsequent write will succeed
* create a separate test environment
* suppress reads of current production data

Another process can change the resource or uniqueness constraints between the dry run and the write. Handle `409` and `422` again on the real request.

## Preview identifiers

A create dry run can return a preview ID. Do not store it as the real resource ID and do not reference it in later requests. Persist only the identifier returned by the successful non-dry-run create response.

## Safe usage pattern

<Steps>
  <Step title="Build the final request">
    Use the same headers and body intended for the real write.
  </Step>

  <Step title="Validate with dryRun=true">
    Inspect both the projected resource and any validation error.
  </Step>

  <Step title="Apply without delay">
    Send the final write after the projection is accepted.
  </Step>

  <Step title="Reconcile the response">
    Store the real resource ID, state, and `X-Request-ID`.
  </Step>
</Steps>