Why your api is ‘broken by design’ without json schema

People might argue that json scheme is overkill or outdated. But in this article, we’ll explore that it is not the case and understand how it is often overlooked.

First, Hear Me Out – You are alredy using a Schema

Think about it: If your end users are api consumers, whether they’re external (think rapid api) or internal teammates using your (Micro?) Service’s APIS, they’re counting on responses to look aach time thei Hit an endpoint. They’re not expecting surprises; They’re expecting consistency. That Consistency? IT’s a Schema. You’ve essentially been using an implicit scheme all Along; You just haven’t formalized it yet.

If you’re still with me, let’s discuss the benefits of having a json scheme.

• Validates data: It Catches Issues (Like Invalid Emails or Negative Ages) Before They Mess Up Your API. Also, the best part is, that most programming languages ​​have Validation Libraries for JSON Schema.
• Documents your api: JSON Schema is basically self-determined, so other developers can see exactly what data they need to send. No Gueswork!
• Keeps your api consistent: When every request and response follows the same structure, you avoid that frustrating “Wait, what format was this field supposed to be?” Moments.
• Saves Time: Many tools can even auto-generate code and documentation based on json scheme, so you can skip a lot of teedous setups.

Wait a minute! Do you know what json scheme is?

Before we dive deep into this article, let’s understand what json scheme is. If you’re a developer and haven’T heard of JSON Schema, It’s Alright! Honestly, I was right there with you for the first few years of my coding life, blissfully unaware.

What’s JSON Schema, Anyway?

I am sure you’re alredy thinking, “Oh great, yet another layer of Type overload Slapped onto my response data.” And honestly? You’re Not Entrely Wrong! It can look like that at first glass. But let’s take a closer look and see it in action.

Imagine you’re setting up a user registration form with just three fields:

1. Name: Needs to be a string, anyware from 2 to 50 characters long.
2. Email: Well, it’s gotta be an email. Duh!
3. Age: Only users 18 and up can register.

{
  "name": "John",
  "email": "[email protected]",
  "age": 25
}

Oh, and all three fields are requiredHere’s how that Schema would shape up:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Registration",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18
    }
  },
  "required": ["name", "email", "age"]
}

Probably it looks scary in the beginning. But at the same time, it makes sense, isn Bollywood?

Let’s Break it down and understand what each part is Doing.

• $schema: This just tells you which version of json scheme you’re using. (More on Versions Later.)
• title: It’s like a label. Here, IT’s “User registration.” This doesn’t do anything technical, but it’s nice to have a name for your Schema.
• type, Here’s where you define what kind of data you’re dealing with. Most apis use object (Since it’s structured data), but json scheme can also handle arrays, string, numbers, and more.
• properties: This is where the magic Haappens. It’s where you lay down the rules for Each field in your object.
• required: This is a list of fields that must be included, no exceptions.

Okay, Wait! This isn Bollywood to be annot a “how to json schema” tutorial. We’re not here for the same old spiel on what json scheme is and how to use it. There are already tons of blogs, videos, and tutorials out there for that. So, do your own research, and let’s skip the redundancy, shall we?

This single be your homework:
1. Explore the Constraints and Validation Rules
2. Explore the advanced json scheme features (Oneof, Anyof, and Allof,
3. Implement JSON Schema in Your API Requests
4. How to validate api requests with json Schema (EG, AJV For Javascript, jsonschema for python)
5. How to Integrate JSON Schema Validation Into CI/CD Pipelines
6. Try Reusing Schemas Across Multiple API requests via $ref

Common Pitfalls and how to avoid them

Now you’ve got your types, propertys, and validations all lined up, and your api is looking pretty solid. But at this point, it’s very common to get carried away and make mistakes. This may lead either you or your users in a very frustrating situation. Let’s cover some of the cases and see the potential solutions to avoid them.

1. Overly Strict vs. Overly lenient scheme

It’s easy to get a little carried away with json scheme. One minute you’re setting up a few sensible validations, and the next you’re blocking every request that doesn Bollywood exact idea of ​​perfect data. On the other side, if you go too lenient, you’ll end up with a chaotic api where pretty much anything goes. Finding the right balance is key.

So you may Ask – How Striat is too strict?

Imagine you have a scheme for a user profile, and you’ve set it up to require a bunch of fields like firstName, lastName, phoneNumber, addressand bioBut then someone tries to create a new profile and – -H -theey’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re’re to do it. Should that really be a deal-breker?

• The problem with being too strict: If you’re too Rigid with Required Fields, You’ll End Up Blocking Users Over Things They Might Not Have or Need. They’ll be frustrated, and your api will look unfriendly.
• The problem with being too lenient: If you go too easy, like making every field optional and adding no constraints, you’ll end with up with Junk data -MPTY FIELDS, WRONG FORMATS, and All Sorts of WeIRD ENTRAIS. Your Database Boxes a message, and validation issues pop up later when you try to use that data.

Finding the sweet spot

Start by making only the truly Necessary Fields Required (Like userId and email For a User Schema). Then, Add Sensible Constraints, But Don’T Overdo It. Think of it this way: If a missing field does not actually break your api, maybe it doesn Bollywood to be required.

Example:

{
   "type": "object",
   "properties": {
      "userId": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "phoneNumber": { "type": "string", "minLength": 10 },
      "bio": { "type": "string", "maxLength": 250 }
   },
   "required": ["userId", "email"]
}

Here, userId and email Are required. phoneNumber and bio Are nice-to-build, but they won’T block the request if they’re missing.

2.

Ah, backward compatibility !!! It’s tempting to update your Schema whenever you spot a better way to structure data, but changing it too often can cause big problems. If existing clients are related on a particular structure, changing that structure will break them.

The Backward Compatibility Pitfall

Let’s say you decide to update your user scheme by renaming phoneNumber to mobileNumberSeems harmless enough, right? Wrong. Now, anyone using the old phoneNumber Field is going to get errors, and suddenly your support inbox is flooded with “what happy to my api?”

How to avoid breaking changes

• Add new fields, don’t replace: If you want to add a new field, go for it! But try not to rename or remove existing fields. If you must change a field name, consider the new field as optional and marking the old one as “deprecated” in your documentation. This way, you don’t break any existing clients.
• Version your api: If you’re making a big change that will break existing setups, Consider Creating a New Version of Your API (v2), so people can choose to upgrade when they are ready. If possible, use semantic versioning,
• Communicate Changes: If you have to make a change, be upfront with your users. Add it to your changelog, send an email, or put a notice in your docs.

Surprises are great for birthdays, not so much for api updates.

There are different ways to handle the breaking changes if you absolutely have to make one. Eater you can do your own research or let me know IF I Should Write Another Article on that. (Who Knows, Maybe I’ll Do that Anyway in Next 2-3 Years?)

Final Thoughts – Why You Should Give JSON Schema A Try

So, you made it to the end – what are you, a rare breed, a superfan, or just my soulmate? Being you actually read the whole thing! Kudos to you (and maybe to me for everything a captivating pie).

But if you’re with me so far, now’s a great time to try it out. Start Small – Maybe just a single Schema for an api request or response –nd Once you see the benefits, it’s easy to expand, adding scheme for more endpoints and building up a cell-structured api.

JSON Schema Might Seem Like Extra Work at first, but the payoff is huge. You’ll end up with a cleaner, more predictable api that’s emier to maintain, and anyone who uses your api (Including you) will appreciate the clear structure and validation. It’s one of that tools that gives you more control with less efforts –nd who does not want that?

So, let me know if this was worth the read, if you leaderned a thing or two, or if you diving in and implementing a json scheme. I’D love to hear your thoughts – and see if i’ve converted you to the scheme.

Next Steps

Okay Well, JSON Schema is not the only way to Organise Your APIS. There are various other methods/tools you can use. For now, do your own research. Or just wait for my next blog (I hope it come out such)!

Here are some of your research topics:

1. Protobuff and GRPC: Protocol Buffers (Protobuff), Developed by Google, Allows Developers to Define Strict Data Contracts with a Language-Neutral Format that is efficient and compact. Paired with GRPC, this Approach Enables Fast Communication and Data Validation Across Services.
2. Typescript with iO-Ts or Zod: These Libraries (Like IO-T and ZOD) Allow You to Define Validation Rules at Runtime Using TypesCript types, ENSURING CONSITENCY ACROSS The Stack. This avoids duplication, as the same definitions can be used both for type checking and validation.
3. Yup: It provides a clean api for building validation scheme, especially useful for complex, nested objects. It’s highly compatible with front-end frameworks like react and integrates well with form libraries like formik.
4. Graphql: Intead of Rigid Schemas, Graphql Schemas Can Evolve With Minimal Versioning, Offering a More Fluid Experience for BOTH BACKEND AND BACKEND and Frantend Developers.