Validate catalog entries with JSON Schema — lab audio overview

Host: Welcome back to AI Developer Platform Engineering — the course about building the internal systems that let AI teams ship safely and quickly. You're in the chapter on Internal Developer Platform Vision, which is really about designing the front door your engineers walk through to launch new services. Today's skill — checking that the information teams submit about their services is actually valid — is one every platform team hits the moment real users show up. Expert: Let me paint the scene. Imagine you're on a platform team at a mid-sized company — maybe eighty engineers spread across a dozen product squads. You've built a shiny internal portal where any team can register a new AI service. They fill out a form, or submit a configuration file, describing things like which model they're using, how much memory it needs, who owns it, and what environment it runs in. It works great for the first week. Then chaos. Someone types the memory limit as the word "big" instead of a number. Someone else forgets to list an owner, so when the service breaks at 2 a.m., nobody knows who to page. A third team uses a model name that doesn't exist. Your portal happily accepts all of it, and now your service catalog — the master list of every AI service in the company — is full of garbage. Deployments fail. Dashboards show nonsense. Trust in the platform evaporates. What you needed, from day one, was a strict bouncer at the door — something that inspects every entry before it gets in and rejects the bad ones with a clear explanation of what's wrong. That's exactly what you're building in this exercise. Host: In the previous exercise, you built a registry for what the industry calls golden paths — pre-approved, opinionated templates that show teams the blessed way to build a new service. Your registry stored those templates, versioned them, and checked their parameters. Now you're extending that same validation thinking to the service catalog itself. So what exactly are we building here? Expert: You're building a validator — a piece of code whose only job is to look at a service catalog entry and answer one question: is this entry well-formed and complete? And the tool you'll use is called JSON Schema. Let me unpack that. JSON is just a common text format for structured data — think of it as a standard way to write down a list of fields and values. JSON Schema is a companion standard that lets you write a separate document describing the rules: this field must be present, this one must be a number between one and sixteen, this one must be one of these three specific strings. Your validator takes two inputs — the rules document and the catalog entry — and tells you whether the entry follows the rules. Here's the key idea. You're not writing a pile of hand-coded if-statements checking every field. You're writing the rules as data, in a separate file, and letting a validation library do the checking. That separation is the whole point. When your platform evolves — when you add a new required field, or a new allowed environment — you update the rules document, not the code. This is what engineers mean by schema evolution. Your validator also needs to produce detailed error messages. Not "invalid entry," but "the memory field expected a number, got the string 'big', at line 14." That's the difference between a tool engineers love and one they curse. Host: Every lab has a gotcha. What's the one thing that trips people up in this exercise? Expert: The trap here is error message quality. The validation library will, by default, give you a raw, ugly error — something technical and hard to read. Beginners accept that output and move on. Don't. The whole reason a platform team builds this tool is so the engineer submitting the entry can fix their mistake without filing a support ticket. So before you start, plan to spend real time on the error path — translating raw validation failures into friendly messages that name the field, show the bad value, and suggest what was expected. Test your validator with deliberately broken entries and ask yourself: if I got this error, would I know how to fix it? If not, keep polishing. Host: Bring it home for us. What does the listener walk away able to do, and where does this leave them? Expert: After this exercise, you'll be able to take any service configuration an engineer submits, check it against a formal set of rules, and either accept it cleanly or reject it with a message precise enough that the engineer fixes it on their own. You'll also be able to evolve those rules over time without rewriting your validator — a skill that keeps platforms maintainable as they grow. For your team, this is a foundational building block. Combined with the data models and the golden path registry from the earlier exercises, you now have the complete starter kit for an internal developer platform's service catalog — the models that define what a service is, the templates that show how to build one, and the validator that guards the front door. That's three exercises that together form a real, working vision for self-service infrastructure — something you can bring straight into your team's architecture discussions. Thanks for listening, and good luck.