For a format designed to be human readable, JSON not supporting comments is a major let down. And not supporting trailing comma.
The Last Breaking Change
11–20 of 66 posts
Re: The Last Breaking Change
#12Do it like OpenAPI does. Separate structure from properties and type. And if you want a fixed value your type is a value. That way you don't mix the JSONSchema's schema is separate from the thing you're describing.
Does OpenAPI support union types yet?
More importantly, if it does, does Swagger support the OpenAPI version that does?
Re: The Last Breaking Change
#13For a format designed to be human readable, JSON not supporting comments is a major let down. And not supporting trailing comma.
You have the superset JSON5 https://json5.org/ but it’s quite rare compared to JSON.
Re: The Last Breaking Change
#14Instead of making a brutal narrow spec that snubs ease of use & extensibility, just to create a "last breaking change" forever spec, the spec should definitely just keep dropping new major versions when it needs to change. This is an ugly & rough conceitedness propsed here: no one can do anythint, because we reserve the right to do anything, and we dont want to have to drop a new major version to do it. Craven attitu…
Are you saying that exact and precise specifications are bad? Can you elaborate, because i always thought that the opposite is bad.
Re: The Last Breaking Change
#15Can anyone mention some interesting projects/use-case for JSON Schema? I have terrible WSDL flashbacks from a past project, where the abstraction layer was always either too high (something simpler was better) or too low (and written documentation was better).
Here is one: OpenMetadata uses it extensively to help you catalog the various types of (software-related) entities you have in your organization. Each entity (tables, alerts, api endpoints..) has been given a set of fields that you can populate (https://docs.open-metadata.org/main-concepts/metadata-standa...). The schema language used for this is JSON Schema.
Re: The Last Breaking Change
#16Can anyone mention some interesting projects/use-case for JSON Schema? I have terrible WSDL flashbacks from a past project, where the abstraction layer was always either too high (something simpler was better) or too low (and written documentation was better).
It's much the same as an XML schema, or K8s CRDs that have a schema embedded into the definition - schema are very useful for ensuring your data structure is valid.
You can use the schema to validate that data is structured correctly, then apply business rule validations afterwards.
And most importantly, people creating data you're ingesting have a thorough schema to validate against.
The JSON Schema documentation was rather terrible for a long time, but has significantly improved. Now the fun part is making sure that the version of JSON Schema you're using is supported by the library you're using.
But JSON Schema is far better than OpenAPI because the latter is mostly focused on API description, which adds a lot of noise when you're trying to simply describe a data structure.
And OpenAPI is also hampered by the tight binding to Swagger. For a long time OpenAPI disallowed union types because it caused issues with Swagger's codegen.
I think that latest versions of OpenAPI allow union types, but I don't think Swagger supports those versions yet. At least they didn't the last time I looked.
Re: The Last Breaking Change
#17Instead of making a brutal narrow spec that snubs ease of use & extensibility, just to create a "last breaking change" forever spec, the spec should definitely just keep dropping new major versions when it needs to change. This is an ugly & rough conceitedness propsed here: no one can do anythint, because we reserve the right to do anything, and we dont want to have to drop a new major version to do it. Craven attitu…
Are you saying that exact and precise specifications are bad? Can you elaborate, because i always thought that the opposite is bad.
[deleted]
Re: The Last Breaking Change
#18Instead of making a brutal narrow spec that snubs ease of use & extensibility, just to create a "last breaking change" forever spec, the spec should definitely just keep dropping new major versions when it needs to change. This is an ugly & rough conceitedness propsed here: no one can do anythint, because we reserve the right to do anything, and we dont want to have to drop a new major version to do it. Craven attitu…
> brutal
> ugly & rough conceitedness
> Craven attitude
> mean & awful
Why do you phrase it in such emotive terms?
Re: The Last Breaking Change
#19Instead of making a brutal narrow spec that snubs ease of use & extensibility, just to create a "last breaking change" forever spec, the spec should definitely just keep dropping new major versions when it needs to change. This is an ugly & rough conceitedness propsed here: no one can do anythint, because we reserve the right to do anything, and we dont want to have to drop a new major version to do it. Craven attitu…
> brutal > ugly & rough conceitedness > Craven attitude > mean & awful Why do you phrase it in such emotive terms?
It's a terrible & self-interested & small-minded design philosophy making awful trade-offs. It's an actively dangerous way of building, to the exclusion of allowing possibility, and for false gain ("no new major versions but it will totally change maybe & no one else has freedom").
I use strong terms because this breaks so many internet ethos, logos, & pathos. Picking the narrowest path should be warded & hazarded against in strong terms. This reaction is emotional because it's terrible terrible choices.
Postel's Law[1] has come under fire from some pretty conservative-minded viewsets (and frankly I'be rarely been persuaded by the angst against permit-if-you-can), but this is a next level assault on loose-coupling, a stark new frontier in reserving almost all possibility for yourself. My description while strong is accurate in many ways: this is brutally narrow. This is an extremeist perspective that json schema is embarking towards, snubbing basic protocol design & rejecting a non-harmful extensibility that cost them nothing (besides needing to tick a major version to make a major change).
Re: The Last Breaking Change
#20Do it like OpenAPI does. Separate structure from properties and type. And if you want a fixed value your type is a value. That way you don't mix the JSONSchema's schema is separate from the thing you're describing.
Does OpenAPI support union types yet? More importantly, if it does, does Swagger support the OpenAPI version that does?
We have union types defined in fastapi/pydantic and they do show up in the api explorer. Tagged unions don't work but I think that's more to do with us/python than openapi.