error envelope restructuring in v2.0.0 LTS — field renaming and location change

[nirmay]

---

Title: [Question] Rationale for error envelope restructuring in v2.0.0 LTS — field renaming and location change

Body:

In v2.0.0 LTS the NACK response envelope changed in two ways compared to v1:

1. The error object moved from message.error to the top level of the response
2. Field names changed: code → errorCode, message → errorMessage, paths → errorPaths

v1:

{
  "message": {
    "ack": { "status": "NACK" },
    "error": { "code": "Unauthorized", "message": "Signature Validation Error: ..." }
  }
}

v2.0.0 LTS:

{
  "message": { "ack": { "status": "NACK" } },
  "error": { "errorCode": "Unauthorized", "errorMessage": "Signature Validation Error: ..." }
}

We are implementing v2.0.0 LTS support in the ONIX adapter and have paused on these changes to seek clarification before shipping.

Questions:

1. What problem does moving error to the top level solve? Is there a specific interoperability issue or ambiguity with message.error in v1 that motivated this? Without a clear motivation it looks like a breaking structural change with no functional benefit.

2. Why rename fields that are already namespaced by their parent? error.code is already unambiguous. error.errorCode is redundant — the prefix adds no information since the field is already inside an object called error. What does a client gain from this renaming?

3. Is the version-gating intentional? If clients must branch on context.version just to know where and how to read an error, that significantly increases client complexity. Was this tradeoff considered?

4. Is there a migration or compatibility guide that explains what breaks in existing clients and why the benefit justifies the breakage?

We want to implement this correctly and are happy to do so once we understand the intent. If there is a design doc or discussion thread that covers the rationale, a pointer to that would also be helpful.

[beckn-docs]

@ravi-prakash-v Shouldn't this be a ticket to revert back to older format?

We should get this sorted sooner, as ongoing networks would need clarity on how this is to be implemented.

cc: @abhimail

[ravi-prakash-v]

This is a valid discussion. However I suggest moving to a structure like this

{
    "message": {
        "status": "ACK",
        "messageId": "",
        "error": {
            "code": "",
            "message": "",
            "details": {... as per https://github.com/beckn/protocol-specifications-v2/discussions/148 ... }
        }
    }
}

seems like a good middle ground. But agree on

1. A message envelope around the sync response
2. Need to revert back to scoped properties of error. Having errorCode inside error seems tautological.

However keeping a status inside just an ack property seems a bit redundant. Hence the above structure.

[nirmay]

Thanks @ravi-prakash-v Who should approve this? Not sure if we still have any answer to why was done what was done or even need to wait for it. Which is still why this is a discussion.

If we are okay to make changes, suggest we make this a ticket and make those changes.
They look good to me.

[ravi-prakash-v]

There was no deeper rationale behind this. It was just a new approach without carrying forward what was working in 1.0. I remember raising a similar issue around creating tautologies in schema. Just like error had errorCode, item had itemAttributes, provider had providerAttributes, which seemed unnecessary. However, my request to simplify naming was overruled in this issue : #29

See the issue label and final comment to the issue. I still stand by the issue on avoiding casual naming. Hoping that the design guide published here should result in better schema design going forward.

In any case, we should create an Issue proposing this change and push it out. Since a merge to main requires 3 approvers, I request @abhimail and @anandp504 to review this and approve so that we can push this along with the other changes, currently being merged to draft

[ravi-prakash-v]

Regarding Migration guide, going forward, all RFCs will have a section called Migration Notes like the one in this RFC: https://github.com/beckn/protocol-specifications-v2/blob/release-v2.0.0-lts/docs/Authentication_and_Trust.md#migration-notes

It's the section just above the Examples section.

[nirmay]

@ravi-prakash-v Request you to raise a PR for this proposed change, so we can move forward. Pls let me know the ETA so I can plan downstream changes.

cc: @abhimail @anandp504

[nirmay]

I see that we are heading to a direction to make changes to what is currently in beckn.yaml.

This is actually critical because Catalog service has already implemented this structure that is likely to change and ONIX is holding up on clarity. The thread is not moving forward, so changing it to issue to seek faster resolution to avoid confusion before newer networks start to implement.

@ravi-prakash-v @anandp504