Generate json schema from struct definitions #276
Conversation
|
|
||
| for _, d := range deep.Equal(a, e) { | ||
| // ignore errors for empty collections vs nil for select fields | ||
| // TODO: this is brittle, but not dangerously so. We should still find a better way to do this. |
There was a problem hiding this comment.
It's unclear to me why this is here, it'd be good to talk this through and/or add more explanation in the comment
There was a problem hiding this comment.
we have cases where the licenses are still nil slices on the package object, something that the presenter now normalizes to an empty slice instead during presentation, but technically they are not equivalent when doing comparison testing for the serialization loop (make package -> get json -> import json -> get packages -> compare packages against original packages). This ignores a select case of the described behavior for a single field.
There was a problem hiding this comment.
Okay, interesting. So this test is effectively testing several processes — normal cataloging, JSON presenters, and the new document important logic. Just so I can better understand, with regard to the document important logic, what are we verifying that wouldn't be caught with tests whose only notable function call was CatalogFromJSON? It seems like we could have a JSON document test fixture, and then assert that the returned values (e.g. distro, source metadata, catalog packages) are what we expect.
Btw, these could easily be notes for enhancement after this PR. I'm just trying to better understand what's going on in this code. And I think I'm coming to the realization that the empty slice vs. nil slice issue is more of a symptom than a root issue.
For now, I think it's fine to explain in the comment that this "exception" to the equality assertion is due to everything that's happening in the "serialization loop" (like you describe above), specifically that this test scope introduces the need to account for data changes in the JSON presenter logic.
There was a problem hiding this comment.
It seems like we could have a JSON document test fixture...
Yes. However, this would be brittle in another way.
As the shape of the JSON document changes, we'll need to update the JSON test fixture continually. We do this for the JSON presenter since the unit tests should be ensuring values are correct (which we do with a diff of the json values and depend on folks updating the snapshot with a scrutinizing eye). We already have a set of curated test cases which are guaranteed to cover all package types, which provides a greater variety of data testing coverage than what we do in the unit tests for the JSON presenters... using these cases along with the real JSON presenter output as test input casts a much wider net for being alerted to potential import problems that may arise.
the empty slice vs. nil slice issue is more of a symptom than a root issue...
Ack. I came to the same conclusion, and didn't want to go to the trouble of fixing that behavior since it technically isn't "wrong" and would take more time.
Signed-off-by: Alex Goodman <[email protected]>
1ff45e6 to
8a17bfb
Compare
|
|
||
| for _, d := range deep.Equal(a, e) { | ||
| // ignore errors for empty collections vs nil for select fields | ||
| // TODO: this is brittle, but not dangerously so. We should still find a better way to do this. |
There was a problem hiding this comment.
Okay, interesting. So this test is effectively testing several processes — normal cataloging, JSON presenters, and the new document important logic. Just so I can better understand, with regard to the document important logic, what are we verifying that wouldn't be caught with tests whose only notable function call was CatalogFromJSON? It seems like we could have a JSON document test fixture, and then assert that the returned values (e.g. distro, source metadata, catalog packages) are what we expect.
Btw, these could easily be notes for enhancement after this PR. I'm just trying to better understand what's going on in this code. And I think I'm coming to the realization that the empty slice vs. nil slice issue is more of a symptom than a root issue.
For now, I think it's fine to explain in the comment that this "exception" to the equality assertion is due to everything that's happening in the "serialization loop" (like you describe above), specifically that this test scope introduces the need to account for data changes in the JSON presenter logic.
Generate json schema from struct definitions
Today we are generating our (messy) json schema from a set of examples derived from integration test cases. This process results in a JSON schema where type semantics are lost and merged into a homogenous blob of individual field definitions (instead of a collection of definitions with a set of parameters for each type).
This PR replaces the JSON schema (and the mechanism for generating it) with one that keeps the semantics intact. Specifically, by using
github.com/alecthomas/jsonschemawe can now generate the json schema directly from our struct definitions.There is one caveat: this json schema does not include definitions for anything underneath weakly typed
interface{}fields, such aspkg.Package.Metadata. This is pretty notable, but something that can be improved on in the future (either by tweaking this automated approach, or by replacing it with a manual approach).Partially addresses #38