What Archify Does with Unknown Fields in JSON Schemas

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

# 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:

// 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, 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.

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