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

> Discover how Archify enforces strict JSON schema validation. Learn about its auto-repair feature for unexpected additional properties by removing them.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 6‑7):

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

```

This pattern repeats across all diagram types. The [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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:

```javascript
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):

```javascript
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:

```javascript
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:

```json
{
  "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):

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

```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.