How Archify Handles Additional Properties in JSON Schemas: Strict Validation and Auto-Repair

Archify treats any additional property as a hard validation error, immediately rejecting undefined fields and offering a single automated fix: remove the unexpected property.

Archify enforces strict JSON schema validation for every diagram type to guarantee deterministic rendering. When users supply properties not defined in the schema, the validator detects the violation, generates a precise diagnostic, and returns a machine-readable receipt that tools can use to auto-correct the input. This article explains the complete flow from schema definition through automated repair, based on the tt-a1i/archify source code.

How Additional Properties Are Blocked in Schema Definitions

Every Archify schema explicitly disables extra keys at the object level. The additionalProperties: false directive appears throughout the schema files, ensuring no undefined fields slip through.

In archify/schemas/workflow.schema.json (lines 6‑7):

{
  "type": "object",
  "additionalProperties": false,
  "properties": { ... }
}

This pattern repeats across all diagram types. The sequence.schema.json and other schema files in archify/schemas/ apply the same constraint, creating a uniformly strict validation surface.

The Validation Pipeline: Detection to Diagnostic

When validation runs, Archify's validator.mjs module transforms raw AJV errors into structured diagnostics with actionable fixes.

Step 1: Running the Validator

The validateSchema function (lines 38‑44 in archify/renderers/shared/validator.mjs) executes the pre-compiled AJV validator for the diagram type:

export function validateSchema(diagramType, json) {
  const validator = validators[diagramType];
  if (!validator(json)) {
    // Build diagnostics from validator.errors
  }
}

Step 2: Mapping Errors to Fixes

For each additionalProperties violation, Archify looks up the fix in a supportedFixes map (lines 56‑58):

const supportedFixes = {
  additionalProperties: (error) =>
    `remove unsupported property "${error.params.additionalProperty}"`,
  // ... other error types
};

This guarantees that every extra property error receives exactly one remediation: deletion.

Step 3: Throwing Structured Diagnostics

The throwDiagnosticError function (lines 80‑84) formats the error for both humans and machines:

function throwDiagnosticError(diagnostic) {
  const message = formatHumanReadable(diagnostic);
  const error = new Error(message);
  error.receipt = diagnostic; // Machine-readable structure
  throw error;
}

The receipt includes the code schema/additionalProperties, the subject's location and identity, the offending property name, and the supported fix array.

Example: Violation, Detection, and Repair

Consider a workflow diagram with an undefined colour field on a node:

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": { "title": "Demo" },
  "lanes": [{ "id": "dev", "label": "Dev" }],
  "nodes": [
    { "id": "api", "label": "API", "colour": "red" }
  ],
  "edges": []
}

Running validation produces a diagnostic matching the test case in archify/test/repair-receipt.test.mjs (lines 72‑79):

{
  "code": "schema/additionalProperties",
  "subject": {
    "diagramType": "workflow",
    "path": "/nodes/0",
    "identity": "api"
  },
  "evidence": {
    "keyword": "additionalProperties",
    "additionalProperty": "colour"
  },
  "supportedFixes": ["remove unsupported property \"colour\""]
}

Applying the fix yields valid JSON:

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": { "title": "Demo" },
  "lanes": [{ "id": "dev", "label": "Dev" }],
  "nodes": [
    { "id": "api", "label": "API" }
  ],
  "edges": []
}

Re-validation now passes, and rendering proceeds deterministically.

Key Source Files for Additional Properties Handling

File	Purpose
archify/schemas/*.schema.json	Schema definitions with additionalProperties: false
archify/renderers/shared/validator.mjs	Core validation, fix generation, diagnostic formatting
archify/test/repair-receipt.test.mjs	Unit tests demonstrating receipt structure and auto-repair
archify/test/degraded.test.mjs	CLI error message verification

Summary

• Strict schemas — Every object in Archify's JSON schemas sets additionalProperties: false
• Immediate detection — AJV validators catch extra properties during validateSchema()
• Precise diagnostics — Errors include path, identity, and the offending property name
• Single fix option — The supportedFixes map always suggests removing the unsupported property
• Machine-readable receipts — Structured output enables automated correction by agents and CI tools

Frequently Asked Questions

What happens if I submit a JSON file with an extra property to Archify?

Archify rejects the file with a schema/additionalProperties error. The diagnostic includes the exact path to the violation, the identity of the offending object, and a suggested fix to remove the extra property. You must remove the undefined field before the diagram can render.

Can I configure Archify to allow additional properties?

No. The additionalProperties: false setting is hardcoded across all schema files in archify/schemas/. This design choice ensures schema compliance and deterministic rendering pipelines with no variation between environments.

How do I programmatically fix additional property errors?

Parse the error receipt's supportedFixes array, which contains a command like remove unsupported property "fieldName". Implement this deletion in your automation, then re-run validation. The test suite in repair-receipt.test.mjs demonstrates this workflow end-to-end.

Does Archify support partial validation or warnings for extra properties?

No. Archify treats additional properties as hard errors, not warnings. The validator immediately throws a DiagnosticError through throwDiagnosticError, halting processing until the schema violation is resolved.

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