feat: Binary data merge and expressions simplification #23270

michael-radency · 2025-12-16T10:00:17Z

Summary

This PR introduces a new combined binary data mode for n8n workflows that changes how binary data is accessed and where it is included in items. Instead of storing binary data separately from the item's JSON data under a binary key, the combined mode automatically includes binary entries directly within the item's JSON data under a _files property, simplifying expressions for data access. Binary entries can be included at any level of nesting in the item's JSON data and can also be placed inside arrays. Items will be displayed in the UI in Schema and Table views with options to preview and download binary items.

1. New Binary Data Mode

New Binary Mode Setting

Added BINARY_IN_JSON_PROPERTY = '_files' constant
New workflow setting: binaryMode: 'separate' | 'combined'
When binaryMode: 'combined', binary data is automatically converted to be accessible via $json._files instead of $binary

2. UI/UX Improvements

Binary Data Viewer Components

BinaryDataViewModal.vue: Modal for previewing binary files (images, videos, PDFs, JSON, HTML, markdown, text)
BinaryEntryDataTable.vue: Table row component for displaying binary file metadata with download and preview actions
VirtualSchemaItem.vue: Enhanced schema view to recognize and display binary data embedded in JSON

Workflow Settings

New execution logic selector with 3 modes:
- v0 (legacy): Original execution order
- v1 (recommended): Sequential branch execution
- v2 (experimental): Sequential with combined binary mode enabled
Selecting v2 sets binaryMode: 'combined', which enables simplified expressions and inclusion of binaries into JSON

3. Expression Simplification

Workflow Data Proxy (packages/workflow/src/workflow-data-proxy.ts)

$item now behaves like $json and $data in combined mode, returning the JSON portion of items directly
$input.item, $input.first(), $input.last(), and $input.all() return JSON data directly in combined mode
$('nodeName').first(), $('nodeName').last(), $('nodeName').all(), and $('nodeName').pairedItem() return JSON data in combined mode
New optional fullItem parameter for $('nodeName', fullItem) to force returning full item structure even in combined mode
Maintains backward compatibility: separate mode returns full item structures as before

Code Node Autocomplete

New type declarations for combined mode: n8n-once-for-all-items-combined.d.ts, n8n-once-for-each-item-combined.d.ts
Autocomplete now omits the .json suggestion for item data access in combined mode
Suppresses await warnings, as it was falsely warning that await could not be used inside Code nodes

4. Backend Changes

Binary Data Conversion

Updated execution logic to process binaries based on the workflow's binaryMode setting
Added helper function convertBinaryData that moves binaries to the JSON _files property, automatically converting base64 data to entries based on filesystem mode

Helper Functions

Enhanced getBinaryDataBuffer() to work with both modes
assertBinaryData() now support binary data access by path from both binary and json properties

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/NODE-3854/add-binarydata-component-for-binaries-included-in-json-schema-view

Review / Merge checklist

PR title and summary are descriptive. (conventions)
Docs updated or follow-up ticket created.
Tests included.
PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)

…add-binarydata-component-for-binaries-included-in-json-schema-view

node-3854-add-binarydata-component-for-binaries-included-in-json-schema-view

…add-binarydata-component-for-binaries-included-in-json-schema-view

… on default filesystem, binary data access by property fixes

…add-binarydata-component-for-binaries-included-in-json-schema-view

…add-binarydata-merge

…8n-io/n8n into node-3854-add-binarydata-merge

…add-binarydata-merge

dlavrenuek

That's a great and huge piece of work @michael-radency 💪 ! Thank you for implementing the bg improvements!

Adding my review so far, will continue tomorrow.

dlavrenuek · 2026-01-08T09:34:56Z

.../src/execution-engine/node-execution-context/utils/__tests__/binary-helper-functions.test.ts

+			).rejects.toThrow('Provided parameter is not a string or binary data object.');
+		});
+
+		it('should throw error when path is undefined in combined mode', async () => {


The test name is a bit misleading because path is 'data.file' and also defined, but the value is undefined. May be something like?

Suggested change

it('should throw error when path is undefined in combined mode', async () => {

it('should throw error when path resolves to undefined in combined mode', async () => {

dlavrenuek · 2026-01-08T09:58:02Z

.../src/execution-engine/node-execution-context/utils/__tests__/binary-helper-functions.test.ts

+	it('should detect ASCII encoding', () => {
+		const asciiBuffer = Buffer.from('Simple ASCII text 123');
+		const encoding = detectBinaryEncoding(asciiBuffer);
+		expect(encoding).toBeDefined();
+		// ASCII is often detected as UTF-8, ASCII, or similar encodings
+		expect(['UTF-8', 'ASCII', 'ascii', 'windows-1252', 'ISO-8859-1']).toContain(encoding);
+	});


Optional suggestion: The test file is saved in utf8, so all text inside is also utf8. Ascii can be enforced the same way it is done in other tests with different encodings but there is also an easy way to just use Buffer.from().toString('ascii'). The used chardet library uses only uppercase for the charset. Also the readme does not state that it supports ascii, it obviously does support it as ASCII. Does the following also work on your machine?

Suggested change

it('should detect ASCII encoding', () => {

const asciiBuffer = Buffer.from('Simple ASCII text 123');

const encoding = detectBinaryEncoding(asciiBuffer);

expect(encoding).toBeDefined();

// ASCII is often detected as UTF-8, ASCII, or similar encodings

expect(['UTF-8', 'ASCII', 'ascii', 'windows-1252', 'ISO-8859-1']).toContain(encoding);

});

it('should detect ASCII encoding', () => {

const asciiBuffer = Buffer.from(Buffer.from('Simple ASCII text 123').toString('ascii'));

const encoding = detectBinaryEncoding(asciiBuffer);

expect(encoding).toBeDefined();

expect(encoding).toBe("ASCII");

});

dlavrenuek · 2026-01-08T10:00:07Z

.../src/execution-engine/node-execution-context/utils/__tests__/binary-helper-functions.test.ts

 		});
 	});
+
+	describe('getBinaryDataBuffer with combined binary mode', () => {


Nice test coverage 🏅

dlavrenuek · 2026-01-08T10:10:22Z

packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts

-			},
-		);
-	}
+	if (binaryMode === 'separate' || binaryMode === undefined) {


With this PR we will have two modes: "separate" and "combined". This condition suggests that "separate" is the default behavior if unset or specificly defined as "separate", otherwise it will be handled as "conbined". This is confusing in my opinion especially if the available modes are extended in the future.

The bahaviour should be more clear when the condition is reversed as

if (binaryMode === BINARY_MODE_COMBINED) {..} else {...}

or if used with switch instead of if:

switch (binaryMode) { case BINARY_MODE_COMBINED: { ... } case "separate": default: { ... } }

What do you think?

dlavrenuek · 2026-01-08T10:13:37Z

packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts

+	} else {
+		const itemData = inputData.main[inputIndex]![itemIndex].json;
+		const binaryData = get(itemData, parameterData);
+		if (binaryData === undefined || !isBinaryValue(binaryData)) {


isBinaryValue already checks internally if the passed value is an object, so we can safely remove the check if it's undefined

dlavrenuek · 2026-01-08T16:25:46Z

packages/frontend/editor-ui/src/features/ndv/runData/components/BinaryEntryDataTable.vue

+			title: 'Error downloading file',
+			message: 'File could not be downloaded',


We should add these text to localization

dlavrenuek · 2026-01-08T16:47:36Z

packages/frontend/editor-ui/src/features/ndv/runData/components/BinaryEntryDataTable.vue

+const isDownloadHovered = ref(false);
+
+const downloadIconColor = computed(() => (isDownloadHovered.value ? 'primary' : 'text-base'));
+


This is a lot of complexity for a hover effect. We should simply use the CSS hover instead of using vue state+rendering logic.

Suggested change

const isDownloadHovered = ref(false);

const downloadIconColor = computed(() => (isDownloadHovered.value ? 'primary' : 'text-base'));

dlavrenuek · 2026-01-08T16:48:28Z

packages/frontend/editor-ui/src/features/ndv/runData/components/BinaryEntryDataTable.vue

+		<div
+			:class="$style.download"
+			@click="downloadBinaryData"
+			@mouseenter="isDownloadHovered = true"
+			@mouseleave="isDownloadHovered = false"
+		>
+			<N8nIcon icon="download" size="large" :color="downloadIconColor" />
+		</div>


color and hover color can be defined in the css class. Also I suggest using either a button or a link here to make it accessible

Suggested change

<div

:class="$style.download"

@click="downloadBinaryData"

@mouseenter="isDownloadHovered = true"

@mouseleave="isDownloadHovered = false"

>

<N8nIcon icon="download" size="large" :color="downloadIconColor" />

</div>

<a :class="$style.download" @click="downloadBinaryData">

<N8nIcon icon="download" size="large" />

</a>

dlavrenuek · 2026-01-08T16:50:12Z

packages/frontend/editor-ui/src/features/ndv/runData/components/BinaryEntryDataTable.vue

+	cursor: pointer;
+	flex-shrink: 0;
+	opacity: 0;
+	transition: opacity 0.2s ease-in-out;


If this is a button or link, cursor is not needed. To keep the colors as you had them following will work:

Suggested change

cursor: pointer;

flex-shrink: 0;

opacity: 0;

transition: opacity 0.2s ease-in-out;

flex-shrink: 0;

opacity: 0;

transition: all 0.2s ease-in-out;

color: var(--color-text-base);

&:hover {

color: var(--color--primary--shade-1);

}

It would be even better to use a separate component "icon button" if such one exists

dlavrenuek · 2026-01-08T16:50:35Z

packages/frontend/editor-ui/src/features/ndv/runData/components/RunDataBinary.vue

@@ -1,16 +1,35 @@
 <script setup lang="ts">


TODO: continue review here

michael-radency added 30 commits November 10, 2025 16:50

setup

dd9df75

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

b12c853

…add-binarydata-component-for-binaries-included-in-json-schema-view

schema binary, download binary

2673bee

close binaries by default

233d0de

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

8215097

…add-binarydata-component-for-binaries-included-in-json-schema-view

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

882df43

…add-binarydata-component-for-binaries-included-in-json-schema-view

binary entry data table draft

4332a75

Merge branch 'master' of https://github.com/n8n-io/n8n into

a8f6dd0

node-3854-add-binarydata-component-for-binaries-included-in-json-schema-view

styles update

dd2b251

binary data view modal

6876688

binary data preview improvements

b945d82

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

e89ef26

…add-binarydata-component-for-binaries-included-in-json-schema-view

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

91ca70c

…add-binarydata-component-for-binaries-included-in-json-schema-view

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

6de2463

…add-binarydata-component-for-binaries-included-in-json-schema-view

workflow setting and convert util

9ce1b40

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

a23243c

…add-binarydata-component-for-binaries-included-in-json-schema-view

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

2d3c71d

…add-binarydata-component-for-binaries-included-in-json-schema-view

settings update, restriction on executing workflow with separate mode…

673476a

… on default filesystem, binary data access by property fixes

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

0ff57ca

…add-binarydata-component-for-binaries-included-in-json-schema-view

review updates

e149c3d

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

20dbba3

…add-binarydata-component-for-binaries-included-in-json-schema-view

import fix

45064bf

tests fix

5084512

fe test fix

744f07b

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

7dc0d26

…add-binarydata-component-for-binaries-included-in-json-schema-view

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

6045150

…add-binarydata-component-for-binaries-included-in-json-schema-view

fix test

8d3238d

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

00e021b

…add-binarydata-component-for-binaries-included-in-json-schema-view

tests

605a00a

import order fix

d73827f

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

897eb18

…add-binarydata-merge

github-actions bot deployed to preview January 5, 2026 10:49 View deployment

This comment has been minimized.

Sign in to view

update tooltips, move to i18, tests fix

951625a

github-actions bot deployed to preview January 5, 2026 11:17 View deployment

binaryDataAccessTooltip helper update

66f065e

github-actions bot deployed to preview January 5, 2026 11:41 View deployment

michael-radency added 2 commits January 5, 2026 14:21

i18n updates

1b4a4e5

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

b928262

…add-binarydata-merge

github-actions bot deployed to preview January 5, 2026 12:23 View deployment

michael-radency added 2 commits January 5, 2026 14:39

tests fix

0fe38cd

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

d69ba1b

…add-binarydata-merge

github-actions bot deployed to preview January 5, 2026 12:41 View deployment

michael-radency and others added 3 commits January 5, 2026 14:50

Merge branch 'master' into node-3854-add-binarydata-merge

2ab4f8c

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

ae46442

…add-binarydata-merge

Merge branch 'node-3854-add-binarydata-merge' of https://github.com/n…

513c0ef

…8n-io/n8n into node-3854-add-binarydata-merge

github-actions bot deployed to preview January 5, 2026 12:53 View deployment

ShireenMissi requested a review from dlavrenuek January 5, 2026 15:02

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

a19b786

…add-binarydata-merge

github-actions bot deployed to preview January 7, 2026 06:40 View deployment

This comment has been minimized.

Sign in to view

michael-radency added 5 commits January 7, 2026 09:28

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

9f60f18

…add-binarydata-merge

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

15bf57d

…add-binarydata-merge

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

6b2b589

…add-binarydata-merge

addressing feedback

c8ccede

Merge branch 'master' of https://github.com/n8n-io/n8n into node-3854-…

0c9b1a7

…add-binarydata-merge

github-actions bot deployed to preview January 8, 2026 07:26 View deployment

tests fix

b8a4be5

github-actions bot deployed to preview January 8, 2026 08:02 View deployment

dlavrenuek requested changes Jan 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Binary data merge and expressions simplification #23270

feat: Binary data merge and expressions simplification #23270

michael-radency commented Dec 16, 2025 •

edited

Loading

Uh oh!

This comment has been minimized.

This comment has been minimized.

dlavrenuek left a comment

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

dlavrenuek Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	it('should throw error when path is undefined in combined mode', async () => {
	it('should throw error when path resolves to undefined in combined mode', async () => {

		title: 'Error downloading file',
		message: 'File could not be downloaded',

		const isDownloadHovered = ref(false);

		const downloadIconColor = computed(() => (isDownloadHovered.value ? 'primary' : 'text-base'));

feat: Binary data merge and expressions simplification #23270

Are you sure you want to change the base?

feat: Binary data merge and expressions simplification #23270

Conversation

michael-radency commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

1. New Binary Data Mode

2. UI/UX Improvements

3. Expression Simplification

4. Backend Changes

Related Linear tickets, Github issues, and Community forum posts

Review / Merge checklist

Uh oh!

This comment has been minimized.

This comment has been minimized.

dlavrenuek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

michael-radency commented Dec 16, 2025 •

edited

Loading