Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite JSON schema conversion #274

Merged
merged 1 commit into from
Feb 14, 2020
Merged

Rewrite JSON schema conversion #274

merged 1 commit into from
Feb 14, 2020

Conversation

mtdowling
Copy link
Member

This commit significantly cleans up the JSON schema conversion and
automatically inlines primitive references rather than inlining them
through a mapper.

The previous JSON schema implementation code had several issues:

  1. It did not do a good job at handling shape ID conflicts when using
    namespace stripping. We had to add some pretty bad hacks to achieve
    this. For examplem, it had implicit state that was tricky to handle
    (like temporarily setting a ref strategy based on a converted shape
    index).
  2. It didn't detect errors early in the process, resulting in strange
    errors when you try to use the schema.
  3. It exposed too much public API (for example RefStrategy should not be
    public). Ideally with this trimmed down API surface area, we won't
    need another breaking change.
  4. JSON schema names by default should not include a namespace.
  5. Simple shapes by default should always be inlined. Things like list
    and set shapes aren't that important for generating good JSON
    schema or OpenAPI schemas. By inlining them, we also ensure that
    any member documentation attached to members that target list or
    set shapes isn't lost since that documentation comes from either
    the member or the targeted shape. This also reduces the possibility
    for naming conflicts when dropping the namespace from the Smithy
    shape ID and converting it to JSON Schema.
  6. We were dropping member traits in some scenarios like
    documentation, pattern, range, length. This is now fixed.

Because converting shape IDs to JSON pointers can now result in a nested
JSON pointer, the ability to select schemas from a SchemaDocument using a
JSON pointer has been implemented.

Finally, the Smithy document shape is actually meant to be a simple type,
but it was correctly subclassing SimpleShape, resulting in JSON schema
conversions not working correctly (document types were creating distinct
named shapes, whereas they are intended to be inlined).

Issue #, if available:

Description of changes:

Note: this will fail due to OpenAPI not being updated yet. That'll follow soon.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@mtdowling mtdowling requested a review from kstich February 12, 2020 22:02
This commit significantly cleans up the JSON schema conversion and
automatically inlines primitive references rather than inlining them
through a mapper.

The previous JSON schema implementation code had several issues:

1. It did not do a good job at handling shape ID conflicts when using
   namespace stripping. We had to add some pretty bad hacks to achieve
   this. For examplem, it had implicit state that was tricky to handle
   (like temporarily setting a ref strategy based on a converted shape
   index).
2. It didn't detect errors early in the process, resulting in strange
   errors when you try to use the schema.
3. It exposed too much public API (for example RefStrategy should not be
   public). Ideally with this trimmed down API surface area, we won't
   need another breaking change.
4. JSON schema names by default should not include a namespace.
5. Simple shapes by default should always be inlined. Things like list
   and set shapes aren't that important for generating good JSON
   schema or OpenAPI schemas. By inlining them, we also ensure that
   any member documentation attached to members that target list or
   set shapes isn't lost since that documentation comes from either
   the member or the targeted shape. This also reduces the possibility
   for naming conflicts when dropping the namespace from the Smithy
   shape ID and converting it to JSON Schema.
6. We were dropping member traits in some scenarios like
   documentation, pattern, range, length. This is now fixed.

Because converting shape IDs to JSON pointers can now result in a nested
JSON pointer, the ability to select schemas from a SchemaDocument using a
JSON pointer has been implemented.

Further, the Smithy document shape is actually meant to be a simple type,
but it was correctly subclassing SimpleShape, resulting in JSON schema
conversions not working correctly (document types were creating distinct
named shapes, whereas they are intended to be inlined).

Finally, this commit fixes a bug where JSON schema extensions weren't
being injected.
@mtdowling mtdowling requested a review from kstich February 14, 2020 21:04
@mtdowling mtdowling merged commit d9ec629 into 0.10 Feb 14, 2020
@mtdowling mtdowling deleted the rewrite-jsonschema branch February 15, 2020 19:32
@kstich kstich mentioned this pull request Apr 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants