# What Are the Possible Schema Validation Errors in Archify?

> Understand Archify's schema validation errors like missing_required, type_mismatch, enum_violation, and pattern_mismatch. Ensure your JSON diagram files adhere to strict schema constraints for seamless validation.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-14

---

**Archify validates JSON diagram files against strict JSON Schema definitions and returns structured error codes—including `missing_required`, `type_mismatch`, `enum_violation`, and `pattern_mismatch`—when input violates schema constraints defined in the repository.**

The `tt-a1i/archify` CLI validates workflow, sequence, lifecycle, dataflow, and architecture diagrams against JSON Schema definitions stored in `archify/schemas/`. When you execute `archify validate`, any schema validation errors are reported as a structured JSON payload containing specific error codes, JSON paths, and human-readable messages. Understanding these nine validation categories helps you debug diagram definitions without manual inspection.

## Categories of Schema Validation Errors

Archify’s validation engine checks input against schemas such as [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), and [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json). Violations fall into distinct JSON Schema categories.

### Missing Required Properties

Triggered when a property listed in a schema’s `"required"` array is absent from the input. In [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), lines 7 and 25 declare required fields for workflow diagrams. Omitting any of these fields produces a `missing_required` error.

### Type Mismatches

Occurs when a field’s value does not match the declared `"type"` constraint. The schema explicitly defines types such as `"type": "string"` for `id` fields and `"type": "array"` for `nodes`. Supplying a number where a string is expected triggers a `type_mismatch` error.

### Enum Violations

Raised when a value is not one of the allowed literals specified in an `"enum"` array. For example, the `type` property of a node in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) is restricted to specific values such as `"frontend"`, `"backend"`, or `"service"`. Any value outside this set results in an `enum_violation` error.

### Pattern Mismatch Errors

String fields frequently enforce regular-expression constraints via the `"pattern"` keyword. Identifier fields often require patterns such as `^[a-z0-9-]+$`. Strings containing uppercase letters or underscores fail validation with a `pattern_mismatch` code.

### Format Errors

Triggered when a string does not conform to a recognized `"format"` such as `uri` or `date-time`. The `url` property in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) uses `"format": "uri"` to ensure valid URLs.

### Additional Property Restrictions

Most sub-schemas set `"additionalProperties": false` to prevent extraneous keys. Including undefined properties in node definitions or root objects produces an `additional_property` error.

### Array Length Constraints

Arrays must satisfy `"minItems"` and `"maxItems"` limits. Workflow stages typically require at least one node (`"minItems": 1`). Arrays falling below or exceeding these thresholds generate array length validation errors.

### Reference Resolution Failures

Schemas reuse definitions via `$ref` pointers. If a reference points to a non-existent definition or the referenced schema cannot be loaded from `archify/schemas/`, the validator returns a resolution error.

### Composite Schema Failures

Complex validation using `anyOf`, `oneOf`, or `allOf` keywords requires data to satisfy combined conditions. Edge definitions allowing one of several shape specifications fail with composite errors when none of the sub-schemas match.

## Error Response Structure

When validation fails, Archify emits a JSON object with a consistent structure. The `ok` field is `false`, and the `checks` array contains every violation found.

```json
{
  "ok": false,
  "checks": [
    {
      "code": "missing_required",
      "path": "/nodes/2",
      "message": "Required property \"id\" is missing."
    },
    {
      "code": "type_mismatch",
      "path": "/edges/5/from",
      "message": "Expected string but got number."
    }
  ]
}

```

Each check includes:
- **code**: The validation category identifier (e.g., `enum_violation`, `pattern_mismatch`).
- **path**: JSON Pointer to the exact location in the input file.
- **message**: Human-readable description of the constraint violation.

## Common Validation Error Examples

### Missing Required Field

Validating a workflow diagram with a node lacking an `id` field:

```bash
archify validate workflow examples/checkout-platform-delta.receipt.json --json

```

Result:

```json
{
  "ok": false,
  "checks": [
    {
      "code": "missing_required",
      "path": "/nodes/0",
      "message": "Required property \"id\" is missing."
    }
  ]
}

```

### Invalid Enum Value

Validating a diagram containing an unrecognized node type:

```bash
archify validate workflow examples/bad-workflow.json --json

```

Result:

```json
{
  "ok": false,
  "checks": [
    {
      "code": "enum_violation",
      "path": "/nodes/3/type",
      "message": "Value \"unknown\" is not allowed. Expected one of [\"frontend\",\"backend\",\"service\"]."
    }
  ]
}

```

### Successful Validation

A passing validation returns an empty checks array:

```bash
archify validate workflow examples/checkout-platform-delta.receipt.json --json

```

Result:

```json
{
  "ok": true,
  "checks": []
}

```

## Key Schema Source Files

The following files in `archify/schemas/` define the constraints that generate validation errors:

- **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)**: Defines required fields, types, enums, and patterns for workflow diagrams.
- **[`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)**: Schema for sequence diagrams including required nodes, edges, and timing constraints.
- **[`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)**: Schema for lifecycle diagrams covering stages and transitions.
- **[`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)**: Schema for data-flow diagrams specifying sources, sinks, and transforms.
- **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)**: Top-level schema wrapping all diagram types and adding meta-information constraints.
- **`archify/bin/archify.mjs`**: CLI entry point that loads the appropriate schema and prints the JSON error report.

## Summary

- **Archify** validates diagrams against JSON Schemas in `archify/schemas/` and reports structured errors.
- **Nine validation categories** include missing required fields, type mismatches, enum violations, pattern failures, format errors, additional properties, array length violations, reference resolution failures, and composite schema failures.
- **Error codes** such as `missing_required` and `type_mismatch` map directly to JSON Schema keywords.
- **CLI output** provides machine-readable JSON with `ok`, `checks`, `code`, `path`, and `message` fields for every violation.
- **Schema files** like [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) and [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) contain the specific constraints that trigger validation errors.

## Frequently Asked Questions

### What does the `missing_required` error code mean in Archify?

The `missing_required` error indicates that a property listed in the schema’s `"required"` array is absent from the input JSON. According to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), fields like `id` and `type` are mandatory for nodes; omitting them triggers this specific schema validation error with a path pointing to the parent object.

### How does Archify validate enum values?

Archify checks string values against `"enum"` arrays defined in the schema. If a field like `node.type` contains a value not listed in the allowed set (e.g., `"unknown"` instead of `"frontend"`, `"backend"`, or `"service"`), the validator returns an `enum_violation` error code specifying the expected values.

### Can I add extra properties to diagram nodes in Archify?

No. Most node definitions in schemas such as [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) and [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) explicitly set `"additionalProperties": false`. Adding undefined keys to a node object results in an `additional_property` schema validation error, preventing extraneous data from entering the diagram definition.

### Where are the JSON Schema definitions located in the Archify repository?

The schema definitions reside in the `archify/schemas/` directory. Key files include [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json), [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json), and [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json). The CLI entry point at `archify/bin/archify.mjs` loads these files to perform validation against your input diagrams.