Your JSON is valid and your invoice is wrong
Imagine a perfectly reasonable backend refactor. client.name becomes customer.legalName . The new shape is clearer. The JSON parses. The application tests are green. Then someone opens an invoice. Beautiful margins. Correct logo. No customer. The document has successfully generated an invoice addressed to absolutely nobody. This is an illustrative failure in a loosely checked integration, but the…
A JSON-to-PDF API is being developed called Bitavu, which converts JSON data into PDF documents. The refactor from client.name to customer.legalName in the backend seems reasonable, as the JSON parses and the application tests pass. However, when generating an invoice, the customer field is missing, resulting in an invoice addressed to nobody.
This situation highlights that valid JSON alone doesn't guarantee the correctness of a document. The integration between incoming data and the saved document template needs to be more robust. A simple check for valid JSON doesn't provide enough information about the document's accuracy.
To improve the situation, a guard function can be implemented to check for required fields like a client name. If the field is missing or empty, an error can be thrown. This approach provides a more specific integration change to review before sending an invoice.
However, even with a guard function, there can be cases where the input contains correct data types but still maps incorrectly to the intended fields. For example, if both billing and shipping names are present, it's unclear which one should be used for the invoice's Bill to field. This issue cannot be resolved by a structural validator, as it can only check for the existence of a string at a declared path.
To address this problem, it's essential to treat field mappings like code changes and review them carefully. Before adopting a mapping, ask whether it represents the intended business entity. Use synthetic examples with different combinations of data to test the mappings thoroughly.
Bitavu reports schema mismatches with a 422 SCHEMA_DRIFT status code, allowing developers to review the transformation and potentially save a mapping for targeted use in specific template revisions. However, even with this mechanism, a well-defined template contract and a person who understands the meaning of the fields are crucial for ensuring the document's correctness. Ultimately, a green check for valid JSON is not enough to guarantee a correct document.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
