5 ms·

I haven't used JSON Schema (knowingly, at least) in my professional software career. I wonder why that is. There are things that seem to supersede it, namely ty

I haven't used JSON Schema (knowingly, at least) in my professional software career. I wonder why that is. There are things that seem to supersede it, namely type systems. GraphQL types with compiled clients wouldn't have a need for this (I don't think?). Neither would Golang generated clients from GraphQL specs, nor gRPC/protobufs. JSON storage / data passing within applications is covered by Typescript. For libraries that build/offer specific JSON outputs (maybe like an online editor that dumps out a JSON file on export), I would also expect that product would come with a client library with Typescript types that would give type safe access to the JSON data. Maybe JSON schema is useful for RESTful resources to provide a payload definition of responses? And I guess consumers could then generate client definitions from the JSON schema? It seems weird to do that at runtime, so I'm guessing it would also be a compile step to generate clients from JSON schema? Or is there an intentional runtime use case? Are there popular APIs/libraries/etc that use JSON Schema? I don't see a "used by" section on this site which could help folks understand where this sits in the modern software development industry.

endtime 4y ago
I've used JSON Schema for specifying YAML config schemas.
spion 4y ago
Used by: - OpenAPI/Swagger (1), which is the industry standard for REST API. Used by Kubernetes among others for resource descriptions - OpenRPC (json-rpc standard) - Most YAML based configuration files. GraphQL doesn't quite supersede JSONSchema because it doesn't deal with validation. (Something like Cue (https://cuelang.org/ https://cuelang.org/) might) Type systems are not typically cross-language, which is where JSONSchema tends to be used a lot. There are indeed a lot of openapi-based client generators. This one, for example, has been around for quite some time: https://github.com/OpenAPITools/openapi-generator https://github.com/OpenAPITools/openapi-generator (1) Kinda. OpenAPI schema and JSONSchema are largely intersecting sets but there are bits in both that aren't present in the other.
sclarisse 4y ago
I had a similar experience evaluating the state of the ecosystem and finding it not ideal. The schema format is great and schemas are great ways to validate your input / make your programs easier to reason about — but with the state of the ecosystem, it’s hard to actually make use of that validation in any but the most trivial ways. The problem with using it directly was that the validators did not produce very usable output. At one point I found myself using it to validate big tables of AirTable-hosted data that were sent into a system as JSON blobs. Identifying the error in a field, and displaying that error to a user so they could correct it, was quite possible, but was a hack in reverse engineering a specific validator system and parsing and mapping its descriptions about where the error was. This was at its worst when you had to have a subschema that was oneOf a few different things: communicating back what was wrong was incredibly painful, as there was basically no metadata coming back that could point you at the problem, just “this object has to be one of a few things, but wasn’t.” In my case I was able to add a second pass of validation if that error came back, validating a specific subschema depending on what type of thingy had been submitted exactly, then mapping that back to the original input fields, before translating those into hyperlinks where the operator could take action. It was further compounded by a library that referenced any shared sub-schemas by loading the URI. I had to write my own system to load them up at application boot instead, and lock down the load-over-network capability for sanity’s and safety’s sake. I didn’t see things that were much better when I attempted to work with it in Ruby, either. The best way to use JSON Schema in a Python API project, in the end, seemed to be to use FastAPI to output the OpenAPI schema and check that in as an artifact (and test it being up to date in the unit tests) so that diffs in the API were obvious at code review.
- sclarisse 4y ago
  Postscript — a surprise good part of schemas was validating all the data our code produced before sending it out. The code would return 500 rather than going out of spec. It made things easier to find and fix.
edflsafoiewq 4y ago
glTF is a 3D model format. It's a JSON file with optional binary data. JSON Schema is used to define the JSON part. The properties reference in the spec is autogenerated from the schemas: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#properties-reference https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#pr...
quietbritishjim 4y ago
Aside from your passing mention of Go, it sounds like your working life is almost exclusively in Typescript. "A client library with Typescript types" is not a substitute for a schema that can be used in multiple languages. (I have the opposite working life to you: I use lots of languages but none are based on JS. So I don't feel qualified to say this, but I don't see how a mish mash of hand written client libraries is a substitute even if you do only work in Typescript. What if I write my own JSON data at the application level? Do I have to write my own mini Typescript library to encode and decode it? It's going to be less concise than specifying the format in a schema.)

endtime 4y ago

I've used JSON Schema for specifying YAML config schemas.

spion 4y ago

Used by: - OpenAPI/Swagger (1), which is the industry standard for REST API. Used by Kubernetes among others for resource descriptions - OpenRPC (json-rpc standard) - Most YAML based configuration files. GraphQL doesn't quite supersede JSONSchema because it doesn't deal with validation. (Something like Cue (https://cuelang.org/ https://cuelang.org/) might) Type systems are not typically cross-language, which is where JSONSchema tends to be used a lot. There are indeed a lot of openapi-based client generators. This one, for example, has been around for quite some time: https://github.com/OpenAPITools/openapi-generator https://github.com/OpenAPITools/openapi-generator (1) Kinda. OpenAPI schema and JSONSchema are largely intersecting sets but there are bits in both that aren't present in the other.

sclarisse 4y ago

I had a similar experience evaluating the state of the ecosystem and finding it not ideal. The schema format is great and schemas are great ways to validate your input / make your programs easier to reason about — but with the state of the ecosystem, it’s hard to actually make use of that validation in any but the most trivial ways. The problem with using it directly was that the validators did not produce very usable output. At one point I found myself using it to validate big tables of AirTable-hosted data that were sent into a system as JSON blobs. Identifying the error in a field, and displaying that error to a user so they could correct it, was quite possible, but was a hack in reverse engineering a specific validator system and parsing and mapping its descriptions about where the error was. This was at its worst when you had to have a subschema that was oneOf a few different things: communicating back what was wrong was incredibly painful, as there was basically no metadata coming back that could point you at the problem, just “this object has to be one of a few things, but wasn’t.” In my case I was able to add a second pass of validation if that error came back, validating a specific subschema depending on what type of thingy had been submitted exactly, then mapping that back to the original input fields, before translating those into hyperlinks where the operator could take action. It was further compounded by a library that referenced any shared sub-schemas by loading the URI. I had to write my own system to load them up at application boot instead, and lock down the load-over-network capability for sanity’s and safety’s sake. I didn’t see things that were much better when I attempted to work with it in Ruby, either. The best way to use JSON Schema in a Python API project, in the end, seemed to be to use FastAPI to output the OpenAPI schema and check that in as an artifact (and test it being up to date in the unit tests) so that diffs in the API were obvious at code review.

sclarisse 4y ago
Postscript — a surprise good part of schemas was validating all the data our code produced before sending it out. The code would return 500 rather than going out of spec. It made things easier to find and fix.

edflsafoiewq 4y ago

glTF is a 3D model format. It's a JSON file with optional binary data. JSON Schema is used to define the JSON part. The properties reference in the spec is autogenerated from the schemas: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#properties-reference https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#pr...

quietbritishjim 4y ago

Aside from your passing mention of Go, it sounds like your working life is almost exclusively in Typescript. "A client library with Typescript types" is not a substitute for a schema that can be used in multiple languages. (I have the opposite working life to you: I use lots of languages but none are based on JS. So I don't feel qualified to say this, but I don't see how a mish mash of hand written client libraries is a substitute even if you do only work in Typescript. What if I write my own JSON data at the application level? Do I have to write my own mini Typescript library to encode and decode it? It's going to be less concise than specifying the format in a schema.)