# Node output contract

**URL:** <https://discourse.nodered.org/t/node-output-contract/100795>\
**Category:** Developing Nodes\
**Created:** [18 April 2026 20:27 UTC](https://discourse.nodered.org/t/node-output-contract/100795 "2026-04-18T20:27:33Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![Sanderd17](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/sanderd17/32/106752_2.png) [@Sanderd17](https://discourse.nodered.org/u/Sanderd17)\
**Post date:** [18 April 2026 20:27 UTC](https://discourse.nodered.org/t/node-output-contract/100795/1 "2026-04-18T20:27:33Z")

</div>

We're developing some custom nodes to easily work with a certain Rest API.

I'd like the users of the nodes to easily see what data they are getting. How can I best achieve this?

I've found the "Message properties" help: [Node help style guide : Node-RED](https://nodered.org/docs/creating-nodes/help-style-guide)

But this only adds a human readable help text to the node. Is there any other way, or development ongoing, that would actually assist the user when using the nodes? I.e. have an autocomplete functionality when extracting a field in the payload.

---

<div class="post-metadata">

**Author:** ![marcus-j-davies](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/marcus-j-davies/32/103435_2.png) [@marcus-j-davies](https://discourse.nodered.org/u/marcus-j-davies)\
**Post date:** [18 April 2026 21:08 UTC](https://discourse.nodered.org/t/node-output-contract/100795/2 "2026-04-18T21:08:22Z")

</div>

Welcome to the forums @Sanderd17

The messages flowing through Node RED, are basically Javascript Objects.  
So providing you document the expected object in your User Help Material, they will know they can access any property you have documented.

example.

```auto
/* result being an example property */
const APIResult = msg.payload.result

/* User does something with APIResult */

```

It's important you ensure the bulk of your output is within the `msg.payload` property, its not a technical requirement, but the `payload` is the common expected property within the Node RED platform, and used by core nodes.

You can provide inline Help as part of your Module, that will appear in the Side Bar, and often a good approach is to document examples, that they can expect.

> [@Sanderd17](#):
>
> I'd like the users of the nodes to easily see what data they are getting. How can I best achieve this?

Lastly, users can attach any output to the `debug` node - allowing them to review the output, and understand what they are receiving, allowing them to then work with the object during runtime.

**EDIT**  
Forgetting to mention, the `debug` node, allows users to copy the path to an object/property/some other path to an object, so some slight assistance is available, but its important to not depend on this approach, and ensure documentation is available, Node RED allows for example flows to be included with a module, that users can import - so that is also helpful to make use of.

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [18 April 2026 21:36 UTC](https://discourse.nodered.org/t/node-output-contract/100795/3 "2026-04-18T21:36:52Z")

</div>

We have started some work on how nodes can provide types definitions for their properties and messages. It early stages, and focused on the base schema before thinking about what features it would unlock.

> <https://github.com/node-red/node-red/issues/5535>
>
> This is a long running topic of discussion that has never quite bridged the chas…m to getting an issue raised to start solidifying plans around it.
> 
> It is also a topic that gets interpreted in many different ways. The goal here is to have a well-defined scope and purpose. There are some short-term requirements, some long-term aspirations and a whole load of things in between. We aren't going to solve everything in one go.
> 
> The goal here is to have a mechanism for nodes to declare type information in a standard way.
> 
> This covers:
> - node configuration properties
> - inbound message properties
> - outbound message properties
> 
> There are lots of potential use-cases for the typings, and whilst I list some examples here, I want to be as clear as possible that they are for future consideration and we're not proposing to implement them at this stage. I'm listing them here to help inform \*how\* the types \*could\* be used - and that may influence choices made
> 
> - Automatic validation of flow files. Currently we can validate the basic structure of a flow, but we cannot validate a node configuration as we don't know what it should look like.
> - Automatic generation of edit dialog. For many nodes, the edit form has a direct correlation to its properties. It should be possible to generate the edit form from the type definition. Of course there are plenty of edge cases, and it only really works for simple configs, but its something to keep in mind
> - Runtime validation of flows.
> - UI tooling to help map message properties between nodes without having to use debug to examine messages
> - AI-driven flow generation
> 
> Each of these use cases has its own pros/cons and being in that list doesn't mean we'll do them. This issue is \*not\* intended to be a discussion of their individual merits, as much as you might like to comment on them.
> 
> Types cannot be mandatory as we have 5000+ existing nodes that don't have type information. But, over time, the types should bring sufficient benefit to end-users that node authors are inclined to include them.
> 
> \## Scope
> 
> - The goal for NR 5.0 will be to have a documented method for how nodes can provide type information.
> - The core Node-RED nodes should be updated to include type information.
> - No runtime/editor functional changes related to the typings
> 
> \### Format of the typings
> 
> There are two possible formats. JSONSchema, or TypeScript style definitions. My instinct is the JSONSchema route, but will need to evaluate what makes most sense. I like JSON as its a well defined blob that can be transported easily. A TypeScript file is free form text and makes me twitch.
> 
> It's conceivable that some use cases may require a bit more meta-data (eg, hints on UI generation). We may need to be a little custom - as long as we have a schema to validate the schema...
> 
> \### Location of typings
> 
> There are three different places the typings could be consumed; editor, runtime and through static analysis without running anything. This third category is an interesting lesson to learn from the Flow Library; working out meta-data about a node from an npm package is quite hard to do as it's all done in code.
> 
> My starting point for this will be to look for a type file that sits alongside the node.js/html files. Need to pick a suitable filename format that aligns with the format of the typings and other conventions.

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/totallyinformation/32/31_2.png) [@TotallyInformation](https://discourse.nodered.org/u/TotallyInformation)\
**Post date:** [19 April 2026 10:32 UTC](https://discourse.nodered.org/t/node-output-contract/100795/4 "2026-04-19T10:32:23Z")

</div>

> [@Sanderd17](#):
>
> have an autocomplete functionality when extracting a field in the payload.

Don't forget that the node's panel in the Editor is an HTML form. Have a look at what you can do with HTML inputs to see if any of those features would help (such as specifying an input type or mask).

You also have access to both HTML/CSS/JavaScript and JQuery and so it is pretty straight-forward to add interactive input helpers and enhanced tooltips. You can also have dynamic info panels in the config panel that react to inputs.

If you have multiple nodes that might need to share some validation or other code, you can use an Editor plugin to provide that.

Example of all of this in the various UIBUILDER nodes if you want to check out some code.

---

<div class="post-metadata">

**Author:** ![Sanderd17](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/sanderd17/32/106752_2.png) [@Sanderd17](https://discourse.nodered.org/u/Sanderd17)\
**Post date:** [19 April 2026 20:54 UTC](https://discourse.nodered.org/t/node-output-contract/100795/5 "2026-04-19T20:54:13Z")

</div>

> <https://github.com/node-red/node-red/issues/5535>
>
> This is a long running topic of discussion that has never quite bridged the chas…m to getting an issue raised to start solidifying plans around it.
> 
> It is also a topic that gets interpreted in many different ways. The goal here is to have a well-defined scope and purpose. There are some short-term requirements, some long-term aspirations and a whole load of things in between. We aren't going to solve everything in one go.
> 
> The goal here is to have a mechanism for nodes to declare type information in a standard way.
> 
> This covers:
> - node configuration properties
> - inbound message properties
> - outbound message properties
> 
> There are lots of potential use-cases for the typings, and whilst I list some examples here, I want to be as clear as possible that they are for future consideration and we're not proposing to implement them at this stage. I'm listing them here to help inform \*how\* the types \*could\* be used - and that may influence choices made
> 
> - Automatic validation of flow files. Currently we can validate the basic structure of a flow, but we cannot validate a node configuration as we don't know what it should look like.
> - Automatic generation of edit dialog. For many nodes, the edit form has a direct correlation to its properties. It should be possible to generate the edit form from the type definition. Of course there are plenty of edge cases, and it only really works for simple configs, but its something to keep in mind
> - Runtime validation of flows.
> - UI tooling to help map message properties between nodes without having to use debug to examine messages
> - AI-driven flow generation
> 
> Each of these use cases has its own pros/cons and being in that list doesn't mean we'll do them. This issue is \*not\* intended to be a discussion of their individual merits, as much as you might like to comment on them.
> 
> Types cannot be mandatory as we have 5000+ existing nodes that don't have type information. But, over time, the types should bring sufficient benefit to end-users that node authors are inclined to include them.
> 
> \## Scope
> 
> - The goal for NR 5.0 will be to have a documented method for how nodes can provide type information.
> - The core Node-RED nodes should be updated to include type information.
> - No runtime/editor functional changes related to the typings
> 
> \### Format of the typings
> 
> There are two possible formats. JSONSchema, or TypeScript style definitions. My instinct is the JSONSchema route, but will need to evaluate what makes most sense. I like JSON as its a well defined blob that can be transported easily. A TypeScript file is free form text and makes me twitch.
> 
> It's conceivable that some use cases may require a bit more meta-data (eg, hints on UI generation). We may need to be a little custom - as long as we have a schema to validate the schema...
> 
> \### Location of typings
> 
> There are three different places the typings could be consumed; editor, runtime and through static analysis without running anything. This third category is an interesting lesson to learn from the Flow Library; working out meta-data about a node from an npm package is quite hard to do as it's all done in code.
> 
> My starting point for this will be to look for a type file that sits alongside the node.js/html files. Need to pick a suitable filename format that aligns with the format of the typings and other conventions.

This was indeed the kind of feature I was looking for. Mildly sad to see it doesn't exist yet, but great to notice it's on the roadmap.

When it comes to the decision between TypeScript and JSON schemas, I'd like to add my 2c. For our usecase (adding nodes to work with a REST API), it doesn't matter a lot. But it shouldn't be underestimated how much more advance TypeScript is than JSON schemas.

TS is made to have very advance type algebra, where you can base return types on the input type of the function (i.e. adding or removing one property on a type, without knowing what the rest of the type looks like). This is something that different nodes in Node RED can definitely use IMO. And TS was also designed to be fully compatible with JS (allowing to have an `any` type to catch all unknown cases). So it should be possible to use TS without requiring all node authors to start using it (their nodes will simply return an `any` type).

Also with the plans of Node.js supporting TS (at least supporting type stripping) in the near future, adding TS support to custom nodes will become possible without compilation, and would only require type extraction for use when editing (or whenever type checking is supposed to happen).

I do agree that adding support for TS will be harder than support for JSON schemas. But TS also has a lot of tooling, like great AST parsers, tools to extract the type definitions from .ts files, ...

But as said, I'd be glad if this makes it into the product, whether it's based on TS or JSON schemas.

---

<div class="post-metadata">

**Author:** ![AllanOricil](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/allanoricil/32/106911_2.png) [@AllanOricil](https://discourse.nodered.org/u/AllanOricil)\
**Post date:** [20 April 2026 02:57 UTC](https://discourse.nodered.org/t/node-output-contract/100795/6 "2026-04-20T02:57:23Z")

</div>

Soon I hope to release something that will work with packages built with the NRG framework. I created a plan for wiring contracts but I had to solve the way nodes are authored first. The framework is almost done and then I can start the execution of the wiring contract. There is no need to change Node-RED core

---

<div class="post-metadata">

**Author:** ![JoW](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/jow/32/108217_2.png) [@JoW](https://discourse.nodered.org/u/JoW)\
**Post date:** [21 April 2026 06:41 UTC](https://discourse.nodered.org/t/node-output-contract/100795/7 "2026-04-21T06:41:27Z")

</div>

maybe look at how ZOD is being used in [node-red-contrib-http-plus (node) - Node-RED](https://flows.nodered.org/node/@inteli.city/node-red-contrib-http-plus) (validations and base for swagger doc )

---

<div class="post-metadata">

**Author:** ![system](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/1X/d073cd938eafa2e558d7c2cd59003b3ef4963033.png) [@system](https://discourse.nodered.org/u/system)\
**Post date:** [20 June 2026 06:42 UTC](https://discourse.nodered.org/t/node-output-contract/100795/8 "2026-06-20T06:42:20Z")

</div>

This topic was automatically closed 60 days after the last reply. New replies are no longer allowed.