3 ms·

There are things you cannot accept. What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your

There are things you cannot accept. What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your DB column, etc ? Having this as part of your interface definition, along with generated representations of the possible data in the language your choice[0] and automatic (so you can't forget it) validation that rejects invalid input with HTTP 400 bad request instead of 500 internal server error when the DB constraint fails (or even worse, you persist invalid data and something breaks later) is definitively useful. That said, OpenAPI fails at this somewhat as the people writing the spec don't consider the (de)serialization and validation libraries. Thus, OpenAPI keeps adding features/constraints that are not supported by the libraries and are thus cannot be automatically validated or even produce nonsense output on generation (e.g. in Java you might end up with raw Map or even Object fields) [0] https://openapi.tools/#sdk https://openapi.tools/#sdk

reaperducer 5y ago
What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your DB column, etc ? Isn't that all just basic data validation and sanitation that we all do anyway? And wouldn't it still have to be done, even if the JSON came with all the schemabloat? I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Maybe it'll be OK for systems that don't get unusual data. But mine are always ingesting strange things, and the only person who knows what's truly valid and what's not is me, not a third party. That's my responsibility as the programmer of the system. I looked through the web page, and it's probably great for someone. Somewhere. But I'd like to see that SKU example that was presented fully fleshed out with real-world type data. It seems OK if your data only consists of "productID," "productName," and "productTags." But in real life, SKUs are often incredibly complex, and this just seems to invite disaster by making complex systems even more complex. So much so that they require even more complex tools to manage them.
- ClumsyPilot 5y ago
  "That's just passing the responsibility on to a third party, which feels lazy and dangerous to me." You trust the memory manager, the SSL library and countless others to do their jobs, data validation is no different. Whether a particular library is up to scratch, is, ofcourse, debatable. Any library worth it's salt, like asp.net, allows you to define custon data type, like SKU, with whatever validation your heart desires.
- 66fm472tjy7 5y ago
  I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Do you also distrust that third parties can implement HTTP, generate SQL, enforce the constraints in your DDL, do arithmetic operations, etc. correctly ? Of course there is still a lot of semantic validation you have to do manually (e.g. for an order: does the referenced product exist, is the seller allowed to sell it, at this time, for this price, for this currency, taxes, do the line prices add up to the order price, contingents, etc., etc.). Expressing these constraints in your interface definition is just another declarative validation layer like your implementation language's type system, database schema/constraints, generic validation libraries[0]. Also, as the server author you are usually also the author of the interface definition containing all these constraints. [0] E.g. https://beanvalidation.org https://beanvalidation.org . The OpenAPI to Java generator will express constraints using BV annotations. BV also integrates with the Hibernate ORM to validate data before you send it to the DB, or you can manually annotate your DTOs/domain model and programmatically trigger the validation at any time, so you only have to know one set of annotations and rely on a single library for validation in any layer of your application.
- dolmen 5y ago
  >> What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your DB column, etc ? > Isn't that all just basic data validation and sanitation that we all do anyway? And wouldn't it still have to be done, even if the JSON came with all the schemabloat? The point of JSON Schema (and schemas for serialization format in general) is to have a machine readable description of the data constraints that both a writer of the data and a reader of that data can use to automate both validation and documentation rendering. > I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Do you trust the compiler/runtime of your programming language? JSON Schema can allow to use a JSON Schema definition for translation into validation code. That may not fit all crazy validation rules, but at least that allow to automate one validation layer from a specification.
jonathanlydall 5y ago
I feel exactly the same. I also want to add that consumers with an appropriate framework can automatically generate a response body explaining where in the payload that errors were encountered and what those errors are. This allows API consumers to understand what is going wrong far more easily that a 500 being returned. ASP.NET for example can do exactly this with validation on incoming payloads. If the payload is invalid, then either way there will be an error, but it's nice to be able to give more helpful errors.
- dolmen 5y ago
  Input validation errors should be reported using HTTP code 400.

reaperducer 5y ago

What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your DB column, etc ? Isn't that all just basic data validation and sanitation that we all do anyway? And wouldn't it still have to be done, even if the JSON came with all the schemabloat? I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Maybe it'll be OK for systems that don't get unusual data. But mine are always ingesting strange things, and the only person who knows what's truly valid and what's not is me, not a third party. That's my responsibility as the programmer of the system. I looked through the web page, and it's probably great for someone. Somewhere. But I'd like to see that SKU example that was presented fully fleshed out with real-world type data. It seems OK if your data only consists of "productID," "productName," and "productTags." But in real life, SKUs are often incredibly complex, and this just seems to invite disaster by making complex systems even more complex. So much so that they require even more complex tools to manage them.

ClumsyPilot 5y ago
"That's just passing the responsibility on to a third party, which feels lazy and dangerous to me." You trust the memory manager, the SSL library and countless others to do their jobs, data validation is no different. Whether a particular library is up to scratch, is, ofcourse, debatable. Any library worth it's salt, like asp.net, allows you to define custon data type, like SKU, with whatever validation your heart desires.
66fm472tjy7 5y ago
I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Do you also distrust that third parties can implement HTTP, generate SQL, enforce the constraints in your DDL, do arithmetic operations, etc. correctly ? Of course there is still a lot of semantic validation you have to do manually (e.g. for an order: does the referenced product exist, is the seller allowed to sell it, at this time, for this price, for this currency, taxes, do the line prices add up to the order price, contingents, etc., etc.). Expressing these constraints in your interface definition is just another declarative validation layer like your implementation language's type system, database schema/constraints, generic validation libraries[0]. Also, as the server author you are usually also the author of the interface definition containing all these constraints. [0] E.g. https://beanvalidation.org https://beanvalidation.org . The OpenAPI to Java generator will express constraints using BV annotations. BV also integrates with the Hibernate ORM to validate data before you send it to the DB, or you can manually annotate your DTOs/domain model and programmatically trigger the validation at any time, so you only have to know one set of annotations and rely on a single library for validation in any layer of your application.
dolmen 5y ago
>> What do you do if an order has a negative quantity, if you get a string instead of a number, if a value does not fit in your DB column, etc ? > Isn't that all just basic data validation and sanitation that we all do anyway? And wouldn't it still have to be done, even if the JSON came with all the schemabloat? The point of JSON Schema (and schemas for serialization format in general) is to have a machine readable description of the data constraints that both a writer of the data and a reader of that data can use to automate both validation and documentation rendering. > I don't think I'm suddenly going to accept that the data presented to my function is valid and fit for purposes just because it goes through someone's JSON schema library. That's just passing the responsibility on to a third party, which feels lazy and dangerous to me. Do you trust the compiler/runtime of your programming language? JSON Schema can allow to use a JSON Schema definition for translation into validation code. That may not fit all crazy validation rules, but at least that allow to automate one validation layer from a specification.

jonathanlydall 5y ago

I feel exactly the same. I also want to add that consumers with an appropriate framework can automatically generate a response body explaining where in the payload that errors were encountered and what those errors are. This allows API consumers to understand what is going wrong far more easily that a 500 being returned. ASP.NET for example can do exactly this with validation on incoming payloads. If the payload is invalid, then either way there will be an error, but it's nice to be able to give more helpful errors.

dolmen 5y ago
Input validation errors should be reported using HTTP code 400.