Discrepancy between the VDV 463 specification and the message validation schema

[Guilhem1976]

Hello,
We’ve identified a discrepancy between the VDV 463 specification and the message validation schema currently maintained in this repository.
According to the VDV 463 specification, the payload of an error message is defined as a string. However, the schema used for message validation expects the payload to be a JSON object. This inconsistency could lead to confusion or implementation issues.
To resolve this, we propose updating the VDV 463 specification so that the payload of an error message is also defined as a JSON object. Additionally, we suggest introducing a dedicated schema to validate the structure of error message payloads.
A simple and consistent structure for the error payload could be:
{
"errorMessage": "Text description of the error."
}

[BenjaminKowatschVector]

Aufgaben:

• Prüfen der Spezifikation und JSON-Schema
• Anpassung der Spezifikation und/oder JSON-Schema

Aufgabe wird bearbeitet von Johannes Dyck: @JDY-39

[JDY-39]

Thank you.

Specifically, the following elements of the specification are at odds with each other:

1. Section 4.1, table (which defines the message structure): "Payload: JsonObject".
2. JsonSchema, MessageStructure.json: the payload (seventh item) is specified to be a JsonObject ("type": "object").
3. Section 4.1, paragraph after the table, point 3: "The error message shall contain as a payload a string that can provide clues to the error at hand."

1 and 2 contradict 3. The proposed solution - have an error message contain a JsonObject as payload that contains a string field "errorMessage" - looks sensible. I will

• create an additional ErrorMessage.json file that describes said payload object of an error message
• prepare a change to the aforementioned paragraph in Section 4.1 (after the table), point 3,
• and prepare a new section after 4.3 that explains the payload of an error message.

I will list the suggested changes to the specification here and create a pull request for the schema file once they are ready.

[JDY-39]

The new Json schema file ErrorResponse.json (not ErrorMessage.json as originally planned) is part of the pull request linked to this issue.

The suggested changes to the specification are as follows:

New text in paragraph in Section 4.1 (after the table), point 3:

... Die Fehlernachricht wird als Error.err bezeichnet und soll als Payload ein JsonObject des Typs ErrorResponse enthalten (siehe unten), das Hinweise auf den vorliegenden Fehler geben gibt. Im Sinne der technischen Bestätigung von Nachrichten gilt die ursprüngliche Nachricht durch das Senden einer solchen Fehlernachricht als bestätigt.

English (note that the final translation of the final German document might differ):

... The error message is referred to as Error.err and shall contain as payload a JsonObject of type ErrorResponse (see below), which provides information concerning the error at hand. For the purposes of technical confirmation of messages, the original message is considered confirmed by sending such an error message.

New subsections 4.2.4 and 4.3.4:

4.2.4/4.3.4 Error.err
Als Antwort auf eine Request-Nachricht mit unbekannter MessageAction oder syntaktischen Fehlern soll das LMS/sollen die Vorsysteme eine Error-Nachricht (err) senden. Deren Payload ist ein JsonObject des Typs ErrorResponse mit folgendem Inhalt:

Name | Datentyp | Kard. | Beschreibung
errorMessage | String | 1..1 | Fehlernachricht

English (note that the final translation of the final German document might differ):

4.2.4/4.3.4 Error.err
As a response to request messages with unknown MessageAction of syntax errors, a system shall send an error message (err). Its payload is a JsonObject of type ErrorResponse with the following content:

Name | Data type | Card. | Description
errorMessage | String | 1..1 | Error message