Understanding `additionalProperties: false` in Archify JSON Schemas

"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, the strict enforcement appears at line 6, immediately restricting the root object to only defined workflow attributes:

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

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

{
  "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: Primary workflow schema with top-level "additionalProperties": false at line 6
• archify/schemas/common.schema.json: Shared definitions for reusable components like nodes and edges
• archify/schemas/sequence.schema.json: Sequence diagram schema following the same strict-object pattern
• archify/schemas/lifecycle.schema.json: Lifecycle diagram schema with strict property enforcement
• 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, 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 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 references nested schemas from 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 and related files without requiring custom validation code.

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