Improve doc for normalizeUplink() to clarify mandatory schema validation and purpose

[colinsurprenant]

Summary

The intent of the normalizeUplink fonction and its mandatory output schema validation could be better explained.

Why do we need this ?

As a relatively new user of the platform without much insights on the actual motivation for a normalized payload, it is not immediately clear that 1- the output of the normalizeUplink function must follow the normalized payload schema and 2- the motivation for this is :

Having a known data model/format will allow building integrations/apps using data coming from The Things Stack without caring about what device it's providing that data, the units used…just caring about the capabilities/sensors that it has.

Per TheThingsNetwork/lorawan-devices/issues/395

I lost some time trying to figure out why my implementation of normalizeUplink wasn't working to eventually understand this was related to the schema validation. I opened a discussion thread to try and better understand the rationale for the mandatory schema validation not knowing about the goal for building integrations that can be agnostic to specific device/units used etc.

What is already there? What do you see now?

This is the current introduction in the docs :

Normalized Payload

The uplink decoder can return any data structure. This provides full flexibility: a decoder can return any measurement in any unit as well as any additional information.

However, developers building applications that combine data from various device types may find it difficult to work with different data structures.

This is what the normalization step is for: the decoded payload gets normalized to a data structure that is common for all device types. Normalized payload is complementary to decoded payload: some measurements or some information may not fit in the normalized payload data structure. Therefore, some application may use normalized payload while others use decoded payload carrying device specific information.

The normalizer function takes the output from the decoder function and returns an output object:

How do you propose to document this?

Here's a proposal:

Normalized Payload

The uplink decoder decodeUplink function provides flexibility to return any data structure. This means that a decoder can output measurements in any unit or include additional, device-specific information tailored to your use case.

However, when building applications that combine data from various device types, working with diverse and inconsistent data structures can be challenging. To address this, the normalization step ensures that decoded payloads are transformed into a standardized format defined by the Normalized Payload Schema.

This normalization enables developers to build integrations and applications that are agnostic to the specific devices or units being used, focusing instead on the capabilities and sensors that the devices provide. By adhering to the schema, integrations can work seamlessly with data from multiple sources without needing to adjust for device-specific variations.

Key Points:

• The output of the normalizeUplink function must follow the Normalized Payload Schema.
• The purpose of the schema is to ensure compatibility with integrations and applications that rely on standardized formats for consistent processing.
• While the normalized payload is complementary to the decoded payload, some information or measurements may not fit within the normalized schema. For such cases, applications can directly use the decoded payload to handle device-specific information that extends beyond the normalized schema.

The normalizer function normalizeUplink takes the output from the decoder function and transforms it into a standardized output object based on the schema.

Can you do this yourself and submit a Pull Request?

Yes, I’m happy to do so if this suggestion is deemed reasonable.