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

# Validation functions

> Understand the public validation functions and sizing calculations.

Miramarket exposes validation behavior through three public concepts: shape checking, semantic validation, and fee-aware sizing.

This page describes behavior without requiring internal implementation details.

## Shape check

Use the shape check when input may not be a strategy object yet.

It verifies that the top-level value is an object and that required top-level fields have the expected primitive shape.

### Input

Any unknown value.

### Success

The value can be treated as strategy JSON for deeper validation.

### Failure

The shape check throws a domain error with a message that starts with `Strategy shape:`.

Common messages include:

| Message                                                          | Meaning                                                         |
| ---------------------------------------------------------------- | --------------------------------------------------------------- |
| `Strategy shape: expected an object.`                            | The input is not an object.                                     |
| `Strategy shape: nodes must be an array.`                        | `nodes` is missing or not an array.                             |
| `Strategy shape: edges must be an array.`                        | `edges` is missing or not an array.                             |
| `Strategy shape: decision_groups must be an array.`              | `decision_groups` is missing or not an array.                   |
| `Strategy shape: initial_principal_usd must be a finite number.` | `initial_principal_usd` is missing, non-numeric, or not finite. |

## Semantic validation

Use semantic validation after shape checking.

Semantic validation returns an array of error strings. An empty array means the strategy passed public validation.

### Input

A strategy JSON object.

### Options

| Option              | Meaning                                          |
| ------------------- | ------------------------------------------------ |
| `skipFeeAwareCheck` | When `true`, skip the fee-aware principal check. |

The fee-aware check is also skipped when strategy JSON has `is_demo: true`.

### Output

```json theme={null}
[]
```

or:

```json theme={null}
[
  "root_node_id does not reference an existing node.",
  "Decision group entry_group split allocation is 90, expected 100."
]
```

## Fee-aware sizing

Fee-aware sizing estimates the minimum `initial_principal_usd` needed for every reachable leaf market action.

It accounts for:

* Allocation splits.
* Action depth.
* Conservative fee assumptions.
* Minimum dollar order size.
* Minimum share order size.
* Current price when provided.
* A fallback price when no current price is provided.

### Result fields

| Field                     | Meaning                                                  |
| ------------------------- | -------------------------------------------------------- |
| `requiredPrincipalUsd`    | Minimum required starting principal.                     |
| `worstLeafId`             | `node_id` of the limiting leaf action.                   |
| `worstLeafLabel`          | Label used in the validation message.                    |
| `worstLeafRawMinUsd`      | Raw minimum order size for that leaf before fee scaling. |
| `worstLeafPrice`          | Price used in the calculation.                           |
| `worstLeafPriceIsDefault` | Whether the fallback price was used.                     |

If no reachable market leaf requires sizing, the result is `null`.

## Public constants

| Name                   |  Value | Meaning                                             |
| ---------------------- | -----: | --------------------------------------------------- |
| `CLOB_MIN_USD`         |    `1` | Minimum order size in USD.                          |
| `CLOB_MIN_SHARES`      |    `5` | Minimum shares per order.                           |
| `DEFAULT_LEAF_PRICE`   | `0.50` | Fallback price used when `current_price` is absent. |
| `MAX_TRADING_FEE_RATE` | `0.06` | Conservative fee rate used for design-time sizing.  |

## Recommended validation flow

1. Parse JSON.
2. Run the shape check.
3. Run semantic validation.
4. If errors are returned, show every error to the user or agent.
5. Treat an empty error array as valid.

## Agent guidance

When generating or repairing strategy JSON:

* Do not suppress semantic errors.
* Preserve exact field names from the JSON format.
* If fee-aware sizing fails, increase `initial_principal_usd` instead of removing market actions.
* Use `is_demo: true` only when the strategy is explicitly a demo.