14 ms·

Ask HN: Do you use JSON Schema? Help us shape its future stability guarantees

• jackconsidine 4y ago
  Started using it for my site. Have a hard time navigating the docs and understanding the best types of schema for different purposes. Is there a great guide that anyone knows of?
  • avmich 4y ago
    This one is good - https://json-schema.org/understanding-json-schema/index.html https://json-schema.org/understanding-json-schema/index.html . I also found this site useful - https://cswr.github.io/JsonSchema/spec/grammar/ https://cswr.github.io/JsonSchema/spec/grammar/ .
    • relequestual 4y ago
      Watch out for that second link. Not everything there is accurate. If you or anyone has suggestions to improve the docs (first link), filing issues or PRs are more than welcome!
      • avmich 4y ago
        > Watch out for that second link. Not everything there is accurate. Can you elaborate please? I particularly like their well formedness concept.
        • relequestual 4y ago
          Part of the problem is they wrote that site and its content for a specific version of JSON Schema. The `items` keyword no longer takes an array form value in the latest version of the specification, while their documentation shows that it does. I seem to recall other issues, but can't find them now. We may have raised issues which were resolved, but I don't recall the specifics.
• MithrilTuxedo 4y ago
  I have been trying to get anyone to use it since I discovered FasterXML/Jackson could generate it. I have not worked for an organization with public APIs. Not a single one of the APIs I work on is completely stable. Figuring out what our APIs do requires techniques from archeology, anthropology, and sociology.
  • avmich 4y ago
    I'm not sure, but I suspect the JSON Schema is better used on the problem formulation stage, not on reverse engineering stage. It's still rather simple tool, it can easily be confused and hide the intent - at the same time if you record your API syntax in form of JSON Schema, you at least have reasons for each JSON Schema feature you put into the spec.
• yieldcrv 4y ago
  just commentary on JSON Scheme itself: I mainly seem to have no leapfrogged the need for this There was a time when the JSON parsers across different platforms were so finicky that schemas seemed like a solution, but the parsers got better at not breaking on unexpected data types or JSON structures I'm also usually able to do system design to return a smaller subset of data, with consistent data types Or someone else's JSON or JSON output has its own documentation that already tells what something is and how it should be parsed
  • treve 4y ago
    Validating JSON parsers is not really what JSON schema solves.
    • yieldcrv 4y ago
      we agree on that, one of the examples of using JSON schema is regarding the range of values of a key
• alfalfasprout 4y ago
  Here's my gripe with jsonschema... In most cases where I want to do some validation on JSON I find that I usually have a class/struct/object that represents the payload and I want to unpack JSON into it (or dump that class to JSON). Ultimately, there are already nice tools to do this (eg; marshmallow on the python side). So unless I'm crossing language boundaries writing a separate jsonschema and using that is more work and I have to keep it up to date. And in the cases where I want to cross language boundaries at this point there's less and less of a compelling case to go with JSON and not eg; flatbuffers/protobuf/thrift/capnproto since you're writing a schema anyways.
  • avmich 4y ago
    Wonder in which language class members can have such JSON Schema requirements as "an integer which is a multiple of integer X" or "string which matches regexp R". Also not sure which other schema system is better than JSON Schema across many different features.
    • saghm 4y ago
      They're saying that the tool doesn't fit their priorities for their use case. I suspect you might be trying to say that their use case isn't what the tool is designed for, but you've phrased it in a way that comes across as condescending for not knowing what the tool even does. I'm not sure if you're trying to convince them that the tool would in fact be superior for their use case or if you're unhappy with them for giving this feedback in a context that you think isn't appropriate, but in either case I think it would be more effective to just state your point directly instead of passive-aggressively.
      • avmich 4y ago
        Ok, direct statement. I've tried some alternatives to JSON Schema, e.g. Protobuf. Left with some disappointment towards those alternatives. JSON Schema so far looks pretty good to me in comparison - overall, not for some specific cases, which are frankly rare.
    • 4y ago
• homero 4y ago
  It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging
  • avmich 4y ago
    To me, saying that JSON - not JSON Schema - needs comments is like saying an array - the good old "int[3] foo = { 5, 6, 7 };" - needs comments. I'm sure there are ways to 1) use it profitably without comments and 2) add comments in non-invasive way if really needed.
    • wewtyflakes 4y ago
      Isn't that a great example of something that would benefit from comments; a generically named int array with no context? Regarding the ability to add comments to JSON, it can be done in a cumbersome manner, such as adding a field to an object called "comment", but it is a hack since this wont work for arrays anyway.
      • avmich 4y ago
        The point is that JSON is a data structure, comment is rather unnatural there. It can be added to JSON though, just like an array could be wrapped in an object with a "comment" field. Usually array name serves as a crude comment. Literate programming isn't very popular.
        • wewtyflakes 4y ago
          This does not help if you are integrating against someone else's API.
        • dragonwriter 4y ago
          > The point is that JSON is a data structure JSON is not a data structure. JSON is a data language. A computer program is a data structure and doesn't need comments, a programming language is a format for a human to read, write, and interact with automated tooling, whoss content is a program, but for the human uses, comments are important. Similarly for data languages.
• ysleepy 4y ago
  Soon we'll have JSLT. JSON Query, JSON Pointer, JSON signatures etc are already there. And I say that as a conscious XML user. We are going in circles. At least XML has comments.
  • taeric 4y ago
    I legit saw a team asking for a tool that does JSON -> JSON transformations at work. The XSLT for JSON vibes were almost too strong.
    • avmich 4y ago
      That's jq. At least useful for a lot of transformations.
      • taeric 4y ago
        A little different, but yeah. (If I'm not mistaken, xslt had a bit more of a defined language and way more formalism.) That said, there are plenty of examples. JSONPath, JQ, Jolt... I am not claiming that this is not useful. Just amused to see the wheel go around.
        • avmich 4y ago
          Oh, it absolutely goes around in this industry. For a simple, most frequently used subset of jq a more modest, non-Turing-complete language of transforming strings could be created, so that for many useful cases one just need to provide such a string. Strictly for JSON -> JSON.
      • silon42 4y ago
        yes, jq is XSLT (and more) for JSON
        • taeric 4y ago
          and more?
• avmich 4y ago
  Regarding explicit guarantees, I'd consider a "forward-compatible" way such that when - and if - a breaking change needs to be introduced, it's possible to automatically convert old JSON schemas into the new one. JSON Schema version which would select which processing to choose could be an option, but not sure if there couldn't be better. As is often the case, good domain knowledge can help to choose which features are "real" and can stand and which are more doubtful and have a higher chance to fall out of favor later.
  • relequestual 4y ago
    A project exists which does this, and the team even support its development: https://github.com/sourcemeta/alterschema https://github.com/sourcemeta/alterschema Personally, I'd like to see it become officially supported. We have work to do!
• petilon 4y ago
  Is this the right place to complain about lack of a native Date datatype in JSON? Also lack of inheritance support. (For example I want a way to specify that my json object should be deserialized as Dog not as Animal.)
  • pitaj 4y ago
    No, it's not the right place.
    • avmich 4y ago
      Correct, so let's maintain the tradition. After all we don't usually have precise enough topics, so we can deviate a little and use the opportunity. Date type reminds about some network-specific types which used to be in older version of JSON Schema (like IPv4 address?). Today we can use a string with regexp for an approximation. Do we have a mechanism in JSON Schema to define, mmm, dialects?.. Deserialization of a number as an integer, not a double, could be a similar problem. We can agree that we (try to) deserialize to most abstract class (?) or to use external explicit indicators of the class.
  • ysleepy 4y ago
    Lets invent JAYSON :D (dog){ "ears": [(ear){"side": "right"}, (ear){"side": "left"}] {% this is a comment %} } Now we only have to invent attributes, and we can sell this XML skin to the enterprise JSON users. (This is only half sarcasm) EDIT: Even Better, make comments a subtree by having a special type tag, like #. this way, (#,dog){...} can stay in the tree, but is ignored.
  • jamesappledev 4y ago
    I think JSON allows both of your use cases, you'll just have to define your own deserialization. We've used { "__type": "DOG" } as metadata flags in GraphQL and JSON API's for a long time. I rarely see an API return anything other than an ISO8601 UTC datetime string anymore other than Xero's horrific .NET(?) string " /Date(1326480130277+1300)/"
  • com2kid 4y ago
• thebricklayr 4y ago
  Just last week, I added the ability to export Umami[1] recipes as Recipe JSON Schema[2]. Writing the code for it was quite pleasant thanks to schema-dts[3]. [1] https://www.umami.recipes https://www.umami.recipes [2] https://schema.org/Recipe https://schema.org/Recipe [3] https://github.com/google/schema-dts https://github.com/google/schema-dts
• throwawaymaths 4y ago
  I use JSONschema, it's honestly great the way it is [0]. So I guess the guarantee I want is "don't change anything"? Ha. [0] my biggest gripe is it's not well defined what to do with multipleOf when the number isn't an exact integer.
  • nextaccountic 4y ago
    Your [0] might be a change that can be made in a backwards compatible manner.. as long as current implementations don't diverge on what they do when the number is not an integer (whether they error or do something)
    • throwawaymaths 4y ago
      I think you would have to build in a "integerMultipleOf" filter and slow-deprecate "multipleOf" To be more specific, since I wasn't in GP... It's not clear what you should do when for example you want to see if 0.3f is a "multiple of" 0.1f (due to the whole 0.30000000000004 thing)
      • 8n4vidtmkvmk 4y ago
        That sounds like a limitation of the implementation. Decimal types exist. If the implementation wants to account for some floating point errors I think that's fine too. If they want to codify it though, maybe add an epsilon param so the user can specify how close they want it to be.
        • throwawaymaths 4y ago
          Decimal types don't exist in JSON. If you need decimals, you definitely should encode them as strings. As JSONschema exists to document JSON, it should be agnostic to that. You can if you wish, provide format information in the format field, which is not prescriptive.
          • planede 4y ago
• user3939382 4y ago
  This gives you a pretty good feel for where it’s at: https://json-schema.org/blog/posts/future-of-json-schema https://json-schema.org/blog/posts/future-of-json-schema I’m invested in it. I’m using it to provide implementation-specific validation of requests to/from a third party API. I wish there was a good macOS editor or IDEA plugin for it with autocomplete etc. The static generators from examples are obscure, ugly, minimal, and can’t account for variations. It isn’t pleasant to write, it’s tedious and slow. Nevertheless I’d rather write API validation this way, in a document, than in code.
  • Godel_unicode 4y ago
    Have you looked at vscode? It supposedly supports json schema (https://code.visualstudio.com/docs/languages/json https://code.visualstudio.com/docs/languages/json) and I’ve been thinking about trying it out.
  • BuckyBeaver 4y ago
    What are you trying to do in regard to your API? I just developed an extensive API definition using OpenAPI, which (as of version 3.1) is compliant with JSON Schema. I used Stoplight Studio on Mac OS, although it still doesn't fully support OAS 3.1 two years after it became the current OpenAPI standard. The support from tools and generators is terrible; there's still no apparent toolchain that supports version 3.1 from definition through code generation. Ass-dragging on 3.1 support aside, the code-generation tools out there are, in my experience, trash anyway. It's a massive hodgepodge of Java-based tools with incomplete and redundant documentation repositories all over the place, and widely varying output quality... when the tools work at all. I appreciate people giving their time to open source, but on the other hand I wasted so much time trying to make the broken tools work that I could have written my own code generator from scratch (which is what I ended up deciding to do after weeks of dicking around with OpenAPI Generator). Anyway, I was just wondering how you're using JSON Schema for API work (since you didn't mention OpenAPI).
    • throwawaymaths 4y ago
      It's kind of insane how stoplight and swagger/smartbear still don't support OpenAPI 3.1 Half tempted to just start building out OA3.1 stuff to replace those services
• daviddever23box 4y ago
  Just used it last week for some extensions to existing schema.
• com2kid 4y ago
  JSON Schema is awesome. I wish Typescript had better support for it though, having to do stuff in Zod and JSON Scheme sucks. I have a system I built that compiles TS types to JSON schema, which then validates data coming into my endpoints, this way I am typesafe at compile time (Typescript API) but if someone hits my REST endpoint w/o using my library, I still get runtime goodness. The number of different ways that JSON schema can be programmatically generated and therefore expressed is a bit high, different tools generate very different JSON Schemas. Also the error messages JSON schema gives back are kind of trash, then again the JSON Schema on one of our endpoints is over 200KB in size.
  • eropple 4y ago
    FWIW, I've had good success with Typebox over Zod for exactly this stuff. You don't need to compile out types, you just...have them.
    • franky47 4y ago
      Ditto. It took me a while (coming from C++) to get that types are not the ideal source of truth in TypeScript, due to their disappearance at runtime. Having a runtime parser (which can consequently express things impossible with TypeScript types alone, like "a positive integer" rather than being satisfied with any instance of `number`) from which types are inferred, is a needed mindset shift made easy with Zod. I use JSON Schemas for request validation and response serialisation (eg: [1]) in Fastify, derived from Zod parsers via zod-to-json-schema [2]. Some of Zod's runtime validation does not translate to JSON Schema (typically transforms), so YMMV. But this gives a good runtime glue with the static typing of request handlers. [1] https://github.com/SocialGouv/e2esdk/blob/beta/packages/server/src/routes/info.ts https://github.com/SocialGouv/e2esdk/blob/beta/packages/serv... [2] https://github.com/StefanTerdell/zod-to-json-schema https://github.com/StefanTerdell/zod-to-json-schema
      • eropple 4y ago
        Maybe I was unclear - my post was a criticism of Zod because it involves a bunch of duct tape that I'm not sure makes sense. Typebox just creates JSON Schema objects at runtime and projects them into the type system with `Static<T>`. In so doing, you simultaneously create schema and types and the process of doing so is pleasant--you can just hand a TObject to Fastify as a validator object and you're done. Plus, with a Typebox type provider, it infers down to your handler. JSON Schema is the lingua franca; to me, working in it, rather than converting to it, is a much easier proposition.
• nextaccountic 4y ago
  I'm not currently using it, but I'm strongly considering validating json in postgres with https://github.com/supabase/pg_jsonschema https://github.com/supabase/pg_jsonschema - which uses the https://docs.rs/jsonschema/latest/jsonschema/ https://docs.rs/jsonschema/latest/jsonschema/ Rust crate So I'm not sure if my feedback is valid but, I sure hope that the jsonschema crate follows the spec! Otherwise I'll never use jsonschema but instead something-not-exactly-jsonschema. In other words.. you better not break anything.
  • oliverrice 4y ago
    the jsonschema crate is spec compliant and has full implementations for the required parts of drafts 4,6, and 7 pg_jsonschema matches that support with the caveat that it doesn't support loading documents over http since that would be risky behavior inside a database disclaimer: I'm the author of the pg_jsonschema
• systems_glitch 4y ago
  I do use it, and it's a nice additional layer in forcing APIs to a) remain consistent and b) increase security. I think the only public program I'm using it in is my dynamic DNS widget: https://github.com/chapmajs/dynamic_dns https://github.com/chapmajs/dynamic_dns My main interest in using JSON Schema in the above project was security related: this service sits on the public Internet, by nature I cannot restrict the sources that connect to it (road warrior type systems couldn't send DNS updates!). Having a strict schema is another layer of sanitization on what one nowadays must assume is a malicious source.
• AdieuToLogic 4y ago
  > Do you use JSON Schema? At one point I did, but then discovered RAML[0] and it subsumed the value of what JSON Schema provides as well as being easier to work with than OpenAPI[1]. Also, generating JSON Schema from RAML definitions has proven to be a fairly straightforward process. The usual caveats apply... Your mileage may vary, my experiences do not speak for any others, my opinion does not detract from the value of JSON Schema, etc. 0 - https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/ https://github.com/raml-org/raml-spec/blob/master/versions/r... 1 - https://swagger.io/specification/ https://swagger.io/specification/
  • benatkin 4y ago
    I took a look at RAML and it also seems OK but not great like Swagger and JSON Schema. It isn't that I think I can come up with a better one, it's that I can see why such tools often aren't adopted and API docs are often published in non-machine-readable formats. What I didn't like was that it doesn't infer something is an object and instead you have "type:object" repeated a lot. Also properties rather than props.
• drdaeman 4y ago
  Would love an standardized ability to specify some human-readable annotation for a validation rule and then an ability to easily see this in the DETAILED or VERBOSE validation format. I.e. rather than a cryptic note that something doesn't match a `pattern: "\\S"` (best your typical library would do) I wanna say "must contain at least one non-whitespace character". And I want this standardized, so any conformant library I pick would be able to do this for me, providing a consistent experience whenever it's UI-side "on-the-fly" pre-validation or processing a submission. Unless I missed it, I think while some libraries can do this, it's not exactly standardized thing. And maybe schema URIs weren't exactly the best idea. Not a fan how many libraries make me register a schema with some a fake URL instead of just feeding them the schema document and simply not caring where it came from at all. But since it's already there - OK, fine, it's a minor nuisance. Otherwise, it just works. P.S. I have no idea about the relation to OpenAPI/Swagger/RESTful APIs/whatever. I use vanilla JSON Schema as a convenient "cross-platform" DSL for JSON-serializable data structure validation, and I think it does excellent job at this. Would love to see it staying in that scope.
• yusufnb 4y ago
  I considered using it some time back for API payload validations. I found it bit too verbose for my use case then. I ended up writing my own lighter version and it worked pretty well. I later open sourced it here - https://github.com/sleeksky-dev/alt-schema https://github.com/sleeksky-dev/alt-schema .
  • captainmarble 4y ago
    I use OpenAPI and JSON Schema at work, but for persobal project ended up with my own alternative too. It's too verbose to be fun. https://github.com/alkun-org/open-kun/tree/main/bayan https://github.com/alkun-org/open-kun/tree/main/bayan
• osigurdson 4y ago
  Are there any good libraries for translating data from one json schema to another (i.e. data upgrade)? I'm not worried about a particular language, I'd just like to see what is available.
• macrael 4y ago
  I've been storing some document data in my app in a protobuf in part because I thought protobuf's support for an evolving schema would help with this data aging gracefully over time. But protobufs in js are worse than I thought they would be so I'm considering trying the same strategy out with JSON Schema instead. Any reason why that wouldn't work? JSON is so much easier to work with in js than protos.
• stevebmark 4y ago
  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.
• karmelapple 4y ago
  We use JSON Schema, and we have had nary a problem with storing a bunch of JSON documents in a variety of no-SQL databases for many years now (knock on wood because yikes that a bold sentence to write). Making sure there aren't major breakages from one version to the next sure would be nice, yes. We hit some snags as we attempted to upgrade from I believe 4 to 7, especially because we'd have to deploy native apps into the wild to use the newer version, and getting native mobile apps deployed everywhere quickly is an exercise in futility. So being able to be confident that draft X will work with draft X+1 would be pretty excellent.
  • relequestual 4y ago
    The OP actually created a tool that allows you to upgrade your schemas between versions of JSON Schema. It's pretty neat, and has had the eyes of those who write the spec. https://github.com/sourcemeta/alterschema https://github.com/sourcemeta/alterschema
• sshine 4y ago
  I reviewed JSON Schema libraries for Haskell: https://github.com/sshine/library-recommendations/blob/main/recommendations/haskell-json-schema.md https://github.com/sshine/library-recommendations/blob/main/... My current impression is that JSON Schema is nicer in theory than in practice.
  • relequestual 4y ago
    Thanks for sharing. This is useful commentary to see. We try to be helpful to maintainers. If any have questions, the JSON Schema server has an implementers channel! We would like to be able to support implementers financially, but we need other companies to add their support in order to do that. And for that, we need to better communicate our value proposition. We're working on it!
• jcims 4y ago
  Many of the orgs I've encountered through the years focus on mechanisms to implement and share APIs by way of method signatures. Is it possible to build an ecosystem around data schemas?
• d3fun 4y ago
  [dead]
• RandomWorker 4y ago
  Allow for single quotes when they are the only quotes to define a key or value. Similar to python strings. This would be huge for me.
• harsha_ch 4y ago
  We at OpenMetadata(https://open-metadata.org https://open-metadata.org) use JsonSchema extensively to define the metadata standards. JsonSchema is one of the reasons we are able to ship and get the project to what it is today in quick time. More about it here https://www.youtube.com/watch?v=ZrVTZwmTR3k https://www.youtube.com/watch?v=ZrVTZwmTR3k
• anon223345 4y ago
  Schema.org
• Taywee 4y ago
  I use JSON schema to generate JSON-editing forms via json-editor: https://github.com/json-editor/json-editor https://github.com/json-editor/json-editor Then I can use the same schema in the backend to validate the data, both sent in via the form and directly with the application/json content-type. It's a pretty smooth flow, and reduces a lot of redundancy.
• seer 4y ago
  I use it extensively in prod. Well the superset that is OpenApi. It enables contract first development where any change to the api is done in the schema fist, and then implemented by the clients/server. Since we have tooling[0] that validates requests and responses at runtime, the clients can be absolutely sure of what they receive (we through 500 if the server attempts to respond with an undocumented respond) And the server is also sure about the shape of the requests. This allows us to validate everything at compile time too, generating typescript types for both client and server. And since we have similar tooling regarding our data stores (typescript types for sql queries) most of the time if there is a bug, the code would simply not compile - pretty nifty! [0] - https://github.com/ovotech/laminar https://github.com/ovotech/laminar
  • mderazon 4y ago
    How do you keep the openapi spec file updated over time ? Our problem is usually making sure changes to the api get reflected and updated in the open api spec file.
• ephaeton 4y ago
  I use json schema to communicate the potential shape of JSON input and output to co-workers who have to produce or consume said JSON, and use it to validate incoming requests via valijson. It's somewhat clunky. Stability guarantees? Well, it's all namespaced anyways, isn't it.
  • relequestual 4y ago
    Could you elaborate where you see the namespacing?
• nly 4y ago
  We just use protobufs JSON serialisation. It's a lot easier.
  • jviotti 4y ago
    I'm working on JSON BinPack (https://www.jsonbinpack.org https://www.jsonbinpack.org) for precisely these use cases. It is a WIP, but hopefully will be ready soon.
• IanCal 4y ago
  I feel like this is missing an important bit of context, at least it's not obviously part of this discussion though I expect it's known somewhere. Keeping things compatible is essentially always preferable. Making breaking changes is in isolation a bad thing but can be worth it for what you get out of it. Is there a wishlist of "if only we could break compatibility, we'd do X/Y/Z"? > The specifications that have been published to date provide no stability guarantees, but we will be adding explicit guarantees with the next publication. However, it seems disingenuous to promise "no breaking changes" while including breaking changes. Not really, this seems pretty par for the course of any project hitting a 1.0 release - announcing that things are now stable. Perhaps that's a better framing, you wouldn't release something saying no breaking changes while containing breaking changes, but releasing something that has breaking changes as a stable thing makes a lot of sense.
• dathinab 4y ago
  it would be nice if you did provide a guid of things tool implements get commonly wrong like you would expect that people realize "additionalProperties" are additional to "properties" but pretty much any doc or code gen tooling I have used has some problems with getting that right (various problem not always the same)
• ChrisMarshallNY 4y ago
  > Do you use JSON Schema? No, but I don’t do much backend stuff, anymore. I’m totally anal about Quality, so I want to do things like jsonSchema. I used to deliberately publish APIs in both JSON and XML, so that I could use XML Schema to validate the data, but JSON, to actually use it. XML Schema is a huge PItA. I don’t like auto-generated Schema (see “anal,” above), so I tend to hand-tune (or write code to dynamically generate) my Schema. The main reason I don’t use jsonSchema, is that I don’t have a real use for it, these days. I mostly have internal APIs (proprietary backends), so there’s no need. I do have one backend that I recently wrote, that is public, and I may consider adding a published schema to it.
  • bambax 4y ago
    > XML Schema is a huge PItA Yes. In the past I used to use Schematron; it's quite fun and extremely straightforward, although it's better described as a set of rules / tests than a tool to describe the structure of a document. https://en.wikipedia.org/wiki/Schematron https://en.wikipedia.org/wiki/Schematron A Schematron equivalent in JS would be cool. Maybe it already exists?
    • michaelmior 4y ago
      In some sense, JSON Schema does lean in that direction. In JSON Schema anything is valid except what you constrain. For example, the schema {} will accept any valid JSON. Anything you add to the schema is kind of like a test that further constraints the schema. If I say {"type": "object"}, now my schema will accept any valid object. If I add {"type": "object", "properties": {"foo": "string"}}, now if there is a property "foo", it must have type string. I can still have whatever other properties I want of whatever type.
• deleted 4y ago
  [deleted]
• comprev 4y ago
  I built a tool which uses JSONschema for validating custom policy documents as part of a GitHub Action pipeline. The documents get processed for updating HashiCorp Vault, and being able to validate/restrict fields like "email address domain" keeps InfoSec happy. Part of my motivation to build the tool was to learn more about JSONschema.
• deleted 4y ago
  [deleted]
• Jemaclus 4y ago
  My struggle with JSON Schema is that not everyone uses it! I do a lot of work with various APIs and ingestion systems that accept JSON, but they don't provide a JSON Schema for me to validate my payloads against. Instead, I often have a human being on the other side emailing me and saying, "Your data structure isn't correct." It's mildly infuriating. I've taken to using Cuelang[0] to write my own validators based on their specifications. (Using Cue because JSON isn't the only data format I have to support.) I wish there were an easier way to take some documentation and generate JSON Schema from it. I can take the sample JSON in the docs and generate one, but those samples don't usually contain all the edge cases that the systems complain about, so it's not super useful. [0] https://cuelang.org/ https://cuelang.org/