validating-json-data

Files (5)

• LICENSE
• SKILL.md
• draft-comparison.md · references/
• error-codes.md · references/
• options.md · references/

SKILL.md (first lines)

# Validating JSON Data with z-schema

z-schema validates JSON data against JSON Schema (draft-04, draft-06, draft-07, draft-2019-09, draft-2020-12). Default draft: **draft-2020-12**.

## Quick start

```typescript
import ZSchema from 'z-schema';

const validator = ZSchema.create();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'integer', minimum: 0 },
  },
  required: ['name'],
};

// Throws on invalid data
validator.validate({ name: 'Alice', age: 30 }, schema);
```

Install: `npm install z-schema`

## Choosing a validation mode

z-schema has four modes based on two toggles: `async` and `safe`. Pick the one that fits the use case.

| Mode        | Factory call                                  | Returns                          | Use when                                 |
| ----------- | --------------------------------------------- | -------------------------------- | ---------------------------------------- |
| Sync throw  | `ZSchema.create()`                            | `true` or throws `ValidateError` | Default — simple scripts and middleware  |
| Sync safe   | `ZSchema.create({ safe: true })`              | `{ valid, err? }`                | Need to inspect errors without try/catch |
| Async throw | `ZSchema.create({ async: true })`             | `Promise<true>` or rejects       | Using async format validators            |
| Async safe  | `ZSchema.create({ async: true, safe: true })` | `Promise<{ valid, err? }>`       | Async + non-throwing                     |

### Sync throw (default)

```typescript
import ZSchema from 'z-schema';

const validator = ZSchema.create();

try {
  validator.validate(data, schema);
} catch (err) {
  // err is ValidateError
  console.log(err.details); // SchemaErrorDetail[]
}
```

### Sync safe

```typescript
const validator = ZSchema.create({ safe: true });

const result = validator.validate(data, schema);
if (!result.valid) {
  console.log(result.err?.details);
}
```

Or call `.validateSafe()` on a regular (throwing) validator for the same result shape:

```typescript
const validator = ZSchema.create();
const { valid, err } = validator.validateSafe(data, schema);
```

### Async throw

Required when using async format validators.

```typescript
const validator = ZSchema.create({ async: true });

try {
  await validator.validate(data, schema);
} catch (err) {
  console.log(err.details);
}
```

### Async safe

```typescript
const validator = ZSchema.create({ async: true, safe: true });

const { valid, err } = await validator.validate(data, schema);
```

## Inspecting errors

`ValidateError` has `.details` — an array of `SchemaErrorDetail`:

```typescript
interface SchemaErrorDetail {
  message: string; // "Expected type string but found type number"
  code: string; // "INVALID_TYPE"
  params: (string | number | Array<string | number>)[];
  path: string | Array<string | number>; // "#/age" or ["age"]
  keyword?: string; // "type", "required", "minLength", etc.
  inner?: SchemaErrorDetail[]; // sub-errors from anyOf/oneOf/not
  schemaPath?: Array<string | number>;
  schemaId?: string;
}
```

### Example: walking nested errors

Combinators (`anyOf`, `oneOf`, `not`) produce nested `inner` errors:

```typescript
const { valid, err } = validator.validateSafe(data, schema);
if (!valid && err) {
  for (const detail of err.details) {
    console.log(`${detail.path}: [${detail.code}] ${detail.message}`);
    if (detail.inner) {

From Kilo-Org/kilo-marketplace, Apache-2.0.

More from Kilo-Org/kilo-marketplace