📘 Dependencies Conventions¶

This document defines how dependencies must be documented for n8n nodes and workflows. Dependencies describe all external elements required for a node or workflow to function correctly, beyond its own implementation.

Documenting dependencies enables governance, impact analysis, security reviews, and operational continuity.

What Is a Dependency?¶

A dependency is any external system, configuration, assumption, or resource that a node or workflow requires to execute successfully.

Dependencies must be explicitly documented and must not rely on implicit knowledge.

Dependency Categories¶

Dependencies are documented under the docs/dependencies/ directory using the following standard categories.

1. Credentials¶

File: credentials.md

Describes the credentials required by the node or workflow, including: - Credential type (OAuth, API Key, Token, Certificate) - Purpose of the credential - Systems that use the credential

Secrets or sensitive values must never be documented.

2. External Systems¶

File: systems.md

Lists all external systems involved, such as: - SaaS platforms - Internal APIs - Databases - Message queues

Include the system role and integration purpose.

3. Subflows and Referenced Workflows¶

File: subflows.md

Documents dependencies on other workflows or subflows, including: - Name or identifier - Purpose - Invocation method

4. Runtime and Execution Context¶

File: runtime.md

Defines assumptions about the execution environment, including: - n8n version - Execution mode (main, queue) - Trigger type (manual, webhook, scheduled)

5. Packages and Libraries¶

File: packages.md

Documents libraries or packages assumed to be available in the execution environment, particularly for Code Nodes.

No installation steps should be included.

6. Triggers and Scheduling¶

File: triggers.md

Describes how the node or workflow is triggered, such as: - Webhooks - Cron schedules - Event-based triggers

7. Data Contracts¶

File: data-contracts.md

Defines expectations about input and output data, including: - Required fields - Optional fields - Data formats and structures

8. Configuration¶

File: configuration.md

Documents non-secret configuration values, such as: - Environment variables - Feature flags - URLs or identifiers

9. Operational Constraints¶

File: constraints.md

Describes operational limits and assumptions, including: - Rate limits - Timeouts - Expected data volume - Performance considerations

Documentation Rules¶

Only applicable dependency files should be created.
All dependencies must be explicitly documented.
Secrets must never be included.
Dependency documentation must be kept up to date with changes.

Purpose of Dependency Documentation¶

This documentation enables: - Impact analysis before changes - Security and compliance reviews - Easier onboarding of new team members - Operational troubleshooting

Dependencies are treated as first-class artifacts and are part of the solution governance.