# What Archify Does with Unknown Fields in JSON Schemas

> Archify rejects unknown fields in JSON schemas by using strict validation with additionalProperties: false. Learn how it prevents errors by not ignoring extra properties.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-30

---

**Archify rejects unknown fields by enforcing strict JSON Schema validation with `additionalProperties: false` at every level, causing validation errors instead of silently ignoring extra properties.**

Archify is an open-source diagramming tool that uses a strict JSON intermediate representation (IR) to define workflows and diagrams. Unlike permissive parsers that ignore unexpected keys, the `tt-a1i/archify` codebase implements rigid schema validation to ensure data integrity. When working with unknown fields in Archify schemas, the system immediately fails validation rather than accepting or discarding the extra data.

## Strict Schema Design with `additionalProperties: false`

According to the [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) documentation, every schema in the repository explicitly sets **`additionalProperties: false`** at every level. This configuration is the core mechanism that prevents unknown fields from entering the system.

The schema definitions in `archify/schemas/*.schema.json` files define exactly which fields are permitted for each diagram type. Because these schemas forbid additional properties, any JSON document containing keys not explicitly defined in the corresponding schema will trigger a validation error and be rejected.

## Runtime Validation Implementation

The validation pipeline relies on two critical components to enforce these constraints at runtime.

### Validator Module (`renderers/shared/validator.mjs`)

The **`renderers/shared/validator.mjs`** module exports the `getValidator()` function, which loads pre-compiled AJV validators and executes them against incoming documents. When you call `getValidator("workflow")` or any diagram type, the returned function immediately checks the input against the strict schema.

If the input contains unknown fields, the validator returns an object with `valid: false` and a detailed errors array explaining which additional properties were found.

### Validator Generation (`scripts/generate-validators.mjs`)

To ensure the runtime validators stay synchronized with the schema definitions, **`scripts/generate-validators.mjs`** generates standalone AJV validators from the source JSON schemas. This build step compiles the `additionalProperties: false` constraints into optimized validation code, ensuring that the strict behavior is hardcoded into the validation logic used by the runtime.

## Validation Failure Examples

When unknown fields are present, Archify rejects the document through both CLI and programmatic interfaces.

### Command-Line Validation

Running `archify validate` against a file containing unexpected properties produces an immediate error:

```bash

# Example: a workflow JSON with an unexpected field "foo"

cat > bad-workflow.json <<'EOF'
{
  "schema_version": "1",
  "diagram_type": "workflow",
  "meta": { "title": "Demo" },
  "lanes": [],
  "foo": "unexpected"
}
EOF

# Running Archify's validator will reject the file

archify validate bad-workflow.json

# → Error: data.bad-workflow.json should NOT have additional properties

```

### Programmatic Validation

When using the validator programmatically, unknown fields cause the validation result to fail:

```javascript
// Using the programmatic validator (renderers/shared/validator.mjs)
import { getValidator } from "./renderers/shared/validator.mjs";

const validator = getValidator("workflow");
const result = validator({ ...validWorkflow, extra: 123 });

if (!result.valid) {
  console.error("Schema validation failed:", result.errors);
}

```

In this example, the `extra` property triggers a schema validation error because it is not defined in the workflow schema.

## Summary

- Archify implements **strict JSON Schema validation** by setting `additionalProperties: false` at every schema level.
- The **`archify/schemas/*.schema.json`** files explicitly define permitted fields, rejecting any unknown keys.
- Runtime enforcement occurs through **`renderers/shared/validator.mjs`**, which uses AJV validators generated by **`scripts/generate-validators.mjs`**.
- Both CLI and programmatic interfaces return explicit errors when encountering unexpected fields, ensuring data integrity across the pipeline.

## Frequently Asked Questions

### Does Archify ignore extra fields in JSON documents?

No. Archify does not ignore or strip unknown fields. According to the source code in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), the schemas explicitly reject documents containing fields not defined in the schema, returning validation errors instead.

### What error message appears when unknown fields are present?

The validator returns a JSON Schema error indicating which additional properties were found. For example, the error message typically states that the data "should NOT have additional properties" and identifies the specific unknown key that violated the schema.

### Can I configure Archify to allow additional properties?

No. The strict `additionalProperties: false` setting is hardcoded throughout the schema definitions in `archify/schemas/*.schema.json` and compiled into the validators by `scripts/generate-validators.mjs`. There is no runtime configuration to disable this behavior.

### Which validator library does Archify use?

Archify uses **AJV (Another JSON Schema Validator)** to compile and execute schema validations. The `scripts/generate-validators.mjs` script generates standalone AJV validators, which `renderers/shared/validator.mjs` loads and executes at runtime to enforce the strict schema constraints.