# Understanding `additionalProperties: false` in Archify JSON Schemas

> Learn how additionalProperties false in Archify JSON schemas enforces strict validation by disallowing undefined properties, ensuring data integrity.

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

---

**`"additionalProperties": false` in Archify schemas strictly forbids any object properties not explicitly defined in the schema, causing validation to fail when extra keys are present.**

In the `tt-a1i/archify` repository, this JSON Schema keyword enforces rigid structure across all diagram definitions. The codebase uses it to ensure workflow, sequence, and dataflow diagrams contain only known, version-controlled attributes—preventing typos, accidental extensions, and breaking changes from silently corrupting your diagrams.

## What `additionalProperties: false` Means in JSON Schema

The `"additionalProperties"` keyword controls whether objects may contain keys beyond those declared in the `"properties"` object. When set to `false`, the schema operates in **strict mode**: any key not explicitly listed under `"properties"` triggers a validation error.

Standard validators like `ajv`, `jsonschema`, or Python's `jsonschema` will report errors such as *"should NOT have additional properties"* when encountering unexpected fields. This behavior is automatic—no custom validation logic is required in your application code.

## How Archify Implements Strict Schema Validation

Archify applies `"additionalProperties": false` at multiple levels to guarantee deterministic data structures.

### Top-Level Workflow Schema Constraints

In [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), the strict enforcement appears at line 6, immediately restricting the root object to only defined workflow attributes:

```json
{
  "additionalProperties": false,
  "properties": {
    "schema_version": { "type": "integer" },
    "diagram_type": { "type": "string" },
    "meta": { "$ref": "#/definitions/meta" },
    "lanes": { "type": "array" },
    "nodes": { "type": "array" },
    "edges": { "type": "array" }
  },
  "required": ["schema_version", "diagram_type", "meta", "lanes", "nodes", "edges"]
}

```

Any attempt to add a custom field like `"custom_id"` or `"author_notes"` at the root level will fail validation immediately.

### Nested Object Validation

The restriction cascades into nested structures. Within the same workflow schema:

- **`meta` objects** (line 26): Only predefined metadata fields are permitted
- **`lanes` arrays** (line 11): Each lane object cannot contain extra attributes beyond `id` and `label`
- **Node and edge definitions**: Located in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), these shared components also declare `"additionalProperties": false` to ensure consistency across diagram types

This hierarchical strictness means a typo like `"lable"` instead of `"label"` in a lane object will be caught during validation rather than rendering incorrectly.

## Why Archify Enforces Strict Property Validation

The repository maintains strict schemas for three architectural reasons:

- **Data Integrity**: Guarantees that diagram files contain only supported attributes, preventing accidental or malicious schema pollution that could break rendering engines
- **Deterministic Rendering**: The diagram renderer can rely on fixed object shapes, eliminating defensive coding against unknown fields and simplifying layout calculations
- **Forward Compatibility**: When new schema versions introduce breaking changes, unknown fields are explicitly rejected rather than silently ignored, forcing users to migrate data intentionally rather than accumulating technical debt

## Validation Examples and Error Handling

Consider how the validator treats compliant versus non-compliant documents.

### Valid Workflow Document

This snippet passes validation because every key exists in the schema definition:

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Sample Workflow"
  },
  "lanes": [
    { "id": "frontend", "label": "Frontend" }
  ],
  "nodes": [
    {
      "id": "login",
      "lane": "frontend",
      "col": 0,
      "type": "frontend",
      "label": "Login Page"
    }
  ],
  "edges": [
    { "from": "login", "to": "backend" }
  ]
}

```

### Invalid Workflow Document

Adding `extraInfo` to the `meta` object violates the strict constraints:

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Sample Workflow",
    "extraInfo": "not allowed"
  },
  "lanes": [
    { "id": "frontend", "label": "Frontend" }
  ],
  "nodes": [],
  "edges": []
}

```

Validation tools will report: *"meta should NOT have additional properties"*, specifically flagging the `extraInfo` key as the violation.

## Schema Files and Locations

Archify maintains strict validation across multiple diagram types through these source files:

- [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json): Primary workflow schema with top-level `"additionalProperties": false` at line 6
- [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json): Shared definitions for reusable components like nodes and edges
- [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json): Sequence diagram schema following the same strict-object pattern
- [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json): Lifecycle diagram schema with strict property enforcement
- [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json): Dataflow diagram schema maintaining identical constraints

These files form the validation backbone of the repository, ensuring every diagram conforms exactly to expected structures before processing.

## Summary

- **`additionalProperties: false`** rejects any object keys not explicitly defined in the schema properties
- Archify applies this restriction at both root and nested levels in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), and other schema files
- Strict validation guarantees data integrity, deterministic rendering, and explicit breaking-change detection
- Validators like `ajv` automatically enforce these constraints, reporting *"should NOT have additional properties"* for violations
- Extra fields in `meta`, `lanes`, `nodes`, or `edges` objects will cause validation failures

## Frequently Asked Questions

### What happens if I add an extra field to an Archify workflow?

The validator will reject the document with an error message indicating which object contains additional properties. For example, adding an `author` field to a `meta` object in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) will produce *"meta should NOT have additional properties"* and the diagram will fail to load until the extra field is removed.

### Does `additionalProperties: false` affect nested objects?

Yes. Archify applies strict validation recursively. When [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) references nested schemas from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), those definitions also contain `"additionalProperties": false`. This means a node cannot have undefined attributes even if the parent workflow object is valid.

### Can I override strict validation in Archify schemas?

No, the published schemas in `tt-a1i/archify` are designed to be immutable contracts. If you need custom fields, you must fork the repository and modify the schema definitions to explicitly list your custom properties under the `"properties"` object, or remove the `"additionalProperties": false` constraint—though this breaks compatibility with standard Archify tooling.

### Which validation libraries work with Archify's JSON schemas?

Any JSON Schema Draft 7+ compliant validator works, including `ajv` (JavaScript), `jsonschema` (Python), and `json_schemer` (Ruby). These libraries automatically recognize the `"additionalProperties": false` keyword and enforce the strict constraints defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and related files without requiring custom validation code.