What Are the Possible Schema Validation Errors in Archify?

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, sequence.schema.json, and 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, 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 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 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.

{
  "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:

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

Result:

{
  "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:

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

Result:

{
  "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:

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

Result:

{
  "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: Defines required fields, types, enums, and patterns for workflow diagrams.
• archify/schemas/sequence.schema.json: Schema for sequence diagrams including required nodes, edges, and timing constraints.
• archify/schemas/lifecycle.schema.json: Schema for lifecycle diagrams covering stages and transitions.
• archify/schemas/dataflow.schema.json: Schema for data-flow diagrams specifying sources, sinks, and transforms.
• 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 and 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, 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 and 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, sequence.schema.json, lifecycle.schema.json, dataflow.schema.json, and architecture.schema.json. The CLI entry point at archify/bin/archify.mjs loads these files to perform validation against your input diagrams.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}