6 ms·

I might be exceptionally dense, but it's hard for me to see practical applications for something like this. In the end, if you implement this in your applicati

by akie 5y ago

I might be exceptionally dense, but it's hard for me to see practical applications for something like this. In the end, if you implement this in your application, you will have a mechanism to say "this input document is invalid". AND THEN WHAT? Your only option is to discard it. I'd rather live by the old maxim "be liberal in what you accept, and strict in what you produce". But perhaps I'm overlooking an important use case here, in which I'd happily stand corrected.

sorokod 5y ago
liberal or not you can express your expectation in a well defined manner. As to "then what" its up to you, i'd go with some 4XX ( or other technology specific error) that implies that no processing has occured. All arguments for and against schemas in databases translate well to this case.
66fm472tjy7 5y ago
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.
Vinnl 5y ago
I'm relatively often manually editing `package.json` files in npm projects - it's useful if my editor can highlight when I make a typo.
- spookthesunset 5y ago
  Ah yeah, that was one of the nice things about XML documents that had a well managed XSD backing it up. Visual Studio code completion worked on your XML files! XAML, for example, would suck if it didn't have a bunch of XSD mumbo jumbo backing it up.
yarcob 5y ago
Let's say you have some code that takes some JSON as input, and then iterates over the elements of some array in that JSON. Since JSON is schemaless, you need to check whether the array you want to iterate over is actually and array, and for each item you have to check if it has the correct type. Each time you access any data in the JSON you need to validate if it has the correct type, or you will end up with runtime errors. All that validation takes a lot of effort and makes your code hard to read. If you verify that the JSON input matches the expected schema at the very beginning, you can skip all the validation and error handling later, since you already know that is valid. This would make it a lot safer to handle external input. Then the next step would be if language & tooling also supported JSON schema, so that the way you access JSON documents in code also doesn't violate the schema. This would help prevent bugs from programmer errors.
vbezhenar 5y ago
Why do you need to be liberal in what you accept, regarding to API? It just invites for subtle bugs. It makes sense for user-generated input, like phone numbers or addresses. But for software? You're encouraging buggy incomplete software that'll bite you or your client one way or another with that liberal approach. API must be absolutely strict and unambiguous. It helps everyone in the end. Or you'll end up with parseInt abomination. And for strict API you need strict validation. Probably better than schema can provide, but schema is a good start with declarative description and proven battle-tested libraries. After request was validated by the schema, you can be sure in some facts, like which properties are not null, which values are numbers and so on. This already helps to eliminate lots of unnecessary code.
- akie 5y ago
  > This already helps to eliminate lots of unnecessary code. Well, I think you just moved the validation code to another place. Instead of putting it in your app, where (in my opinion) it belongs, you are putting it in a hard-to-read and difficult to understand external JSON file. I'm not sure how that's an improvement.
  - IggleSniggle 5y ago
    It’s an improvement because it’s a public contract that can be enforced both client(s) and server(s), and a relatively standardized interface format that is parseable by all manner of tooling. Otherwise, it’s just in your code, where it’s potentially not just “hard-to-read”, but impossible to read for anybody but the authors. That said, I’m partial to other solutions like protobuf, but what can you do.
  - pibi 5y ago
    It's really not that hard-to-read or to-write. I have instructed dozens of young developers on that with almost no-supervision and no-issue. It's really pretty straightforward. Also, I can replicate my validations at many levels down the stack: from the client to API-GW to the database model. All with a single definition.
  - Too 5y ago
paulddraper 5y ago
On the contrary, the error message immediately states exactly how the data is malformed. Instead of just failing somewhere deep inside the app (even perhaps deferred to later) with "cannot read property of undefined... stack trace"
spookthesunset 5y ago
I made an argument like yours and kinda talked myself out of it. Validation while in production makes no sense, I agree. But automated testing… I bet you can catch some unintentional changes to your JSON output while testing. Not all of them, but some. Maybe even enough to justify keeping the schema current.
xg15 5y ago
I mean, I think there are use-cases where a schema would bring real improvement: - Error messages: A validator doesn't just have to tell you that a document is invalid, it can also tell you why it is invalid and what you have to do to fix it. - Better editors or viewers: If e.g. an IDE knows that your JSON is "really" a record or a graph or a table, it could show some specialized UI and make it easier to view or edit those documents. - Smarter auto-formatting: A schema-aware pretty-printer could format JSON in a way that's better readable than just putting every field on one line. - Documentation generation: e.g. Swagger does this well: You pass it a schema file and it generates a polished HTML documentation, complete with examples and interactive web client. - Code generation: You could auto-generate parsers, serialisers or data structures that are specialized for a particular schema. This would probably be most useful for low-level languages or other languages where working with generic JSON is inconvenient. - More efficient storage: A data store that "knows" that all documents conform to a particular schema could optomize by storing/querying only the schema's data structures and not a generic JSON DOM. (Though to be fair, it's not clear how large the performance improvements from this would be, especially compared to a DB that learns similar information from the usage patterns and data that is actually stored) That's a lot of "could"s though. So far, I haven't seen a lot of those use-cases realized. What also frequently baffles me is that use-cases almost seem like an afterthought in schema design. Most specs and blog posts (like this one) read as if a schema doesn't really need any justification and actual uses are just a nice bonus. Instead of an overengeneered spec, I'd prefer an actual software suite which realizes some of the above use-cases - and then brings a well-designed schema language with it. I believe Swagger/OpenAPI started this way, which might be how they gained traction at all. But judging from the OP, they seem to be taken over by the astronauts again...
kazoomonger 5y ago
When using tooling that accepts YAML (or JSON) configuration, I always want something to say "this is what you can write that will have an effect". As a specific example, when I'm writing a snapcraft.yaml, I want to be able to view a schema to see what all I can put in there. What's important is that the schema is actually used by snapcraft itself for validation, otherwise it's no better than the rest of the snapcraft documentation, which is pretty meh. Schemas are also easy to digest for other tooling, so e.g. my editor can automatically highlight when I make a mistake, without having to specifically write a plugin for each tool that accepts JSON/YAML

by akie 5y ago

sorokod 5y ago

liberal or not you can express your expectation in a well defined manner. As to "then what" its up to you, i'd go with some 4XX ( or other technology specific error) that implies that no processing has occured. All arguments for and against schemas in databases translate well to this case.

66fm472tjy7 5y ago

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.

Vinnl 5y ago

I'm relatively often manually editing `package.json` files in npm projects - it's useful if my editor can highlight when I make a typo.

spookthesunset 5y ago
Ah yeah, that was one of the nice things about XML documents that had a well managed XSD backing it up. Visual Studio code completion worked on your XML files! XAML, for example, would suck if it didn't have a bunch of XSD mumbo jumbo backing it up.

yarcob 5y ago

Let's say you have some code that takes some JSON as input, and then iterates over the elements of some array in that JSON. Since JSON is schemaless, you need to check whether the array you want to iterate over is actually and array, and for each item you have to check if it has the correct type. Each time you access any data in the JSON you need to validate if it has the correct type, or you will end up with runtime errors. All that validation takes a lot of effort and makes your code hard to read. If you verify that the JSON input matches the expected schema at the very beginning, you can skip all the validation and error handling later, since you already know that is valid. This would make it a lot safer to handle external input. Then the next step would be if language & tooling also supported JSON schema, so that the way you access JSON documents in code also doesn't violate the schema. This would help prevent bugs from programmer errors.

vbezhenar 5y ago

Why do you need to be liberal in what you accept, regarding to API? It just invites for subtle bugs. It makes sense for user-generated input, like phone numbers or addresses. But for software? You're encouraging buggy incomplete software that'll bite you or your client one way or another with that liberal approach. API must be absolutely strict and unambiguous. It helps everyone in the end. Or you'll end up with parseInt abomination. And for strict API you need strict validation. Probably better than schema can provide, but schema is a good start with declarative description and proven battle-tested libraries. After request was validated by the schema, you can be sure in some facts, like which properties are not null, which values are numbers and so on. This already helps to eliminate lots of unnecessary code.

akie 5y ago
> This already helps to eliminate lots of unnecessary code. Well, I think you just moved the validation code to another place. Instead of putting it in your app, where (in my opinion) it belongs, you are putting it in a hard-to-read and difficult to understand external JSON file. I'm not sure how that's an improvement.
- IggleSniggle 5y ago
  It’s an improvement because it’s a public contract that can be enforced both client(s) and server(s), and a relatively standardized interface format that is parseable by all manner of tooling. Otherwise, it’s just in your code, where it’s potentially not just “hard-to-read”, but impossible to read for anybody but the authors. That said, I’m partial to other solutions like protobuf, but what can you do.
- pibi 5y ago
  It's really not that hard-to-read or to-write. I have instructed dozens of young developers on that with almost no-supervision and no-issue. It's really pretty straightforward. Also, I can replicate my validations at many levels down the stack: from the client to API-GW to the database model. All with a single definition.
- Too 5y ago

paulddraper 5y ago

On the contrary, the error message immediately states exactly how the data is malformed. Instead of just failing somewhere deep inside the app (even perhaps deferred to later) with "cannot read property of undefined... stack trace"

spookthesunset 5y ago

I made an argument like yours and kinda talked myself out of it. Validation while in production makes no sense, I agree. But automated testing… I bet you can catch some unintentional changes to your JSON output while testing. Not all of them, but some. Maybe even enough to justify keeping the schema current.

xg15 5y ago

I mean, I think there are use-cases where a schema would bring real improvement: - Error messages: A validator doesn't just have to tell you that a document is invalid, it can also tell you why it is invalid and what you have to do to fix it. - Better editors or viewers: If e.g. an IDE knows that your JSON is "really" a record or a graph or a table, it could show some specialized UI and make it easier to view or edit those documents. - Smarter auto-formatting: A schema-aware pretty-printer could format JSON in a way that's better readable than just putting every field on one line. - Documentation generation: e.g. Swagger does this well: You pass it a schema file and it generates a polished HTML documentation, complete with examples and interactive web client. - Code generation: You could auto-generate parsers, serialisers or data structures that are specialized for a particular schema. This would probably be most useful for low-level languages or other languages where working with generic JSON is inconvenient. - More efficient storage: A data store that "knows" that all documents conform to a particular schema could optomize by storing/querying only the schema's data structures and not a generic JSON DOM. (Though to be fair, it's not clear how large the performance improvements from this would be, especially compared to a DB that learns similar information from the usage patterns and data that is actually stored) That's a lot of "could"s though. So far, I haven't seen a lot of those use-cases realized. What also frequently baffles me is that use-cases almost seem like an afterthought in schema design. Most specs and blog posts (like this one) read as if a schema doesn't really need any justification and actual uses are just a nice bonus. Instead of an overengeneered spec, I'd prefer an actual software suite which realizes some of the above use-cases - and then brings a well-designed schema language with it. I believe Swagger/OpenAPI started this way, which might be how they gained traction at all. But judging from the OP, they seem to be taken over by the astronauts again...

kazoomonger 5y ago

When using tooling that accepts YAML (or JSON) configuration, I always want something to say "this is what you can write that will have an effect". As a specific example, when I'm writing a snapcraft.yaml, I want to be able to view a schema to see what all I can put in there. What's important is that the schema is actually used by snapcraft itself for validation, otherwise it's no better than the rest of the snapcraft documentation, which is pretty meh. Schemas are also easy to digest for other tooling, so e.g. my editor can automatically highlight when I make a mistake, without having to specifically write a plugin for each tool that accepts JSON/YAML