Thrift Schema
A thrift schema is a shared interface file that defines data types and service calls. You write this contract once, then run a compiler to build code for each app. Teams use this setup to pass data between services written in different languages. When teams grant broad service roles, any caller can run every method in that contract. A shared key lets one app call admin methods meant for another team. How a thrift schema works across services The workflow starts with one plain text file that h
API Schema Validation: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
A thrift schema is a shared interface file that defines data types and service calls. You write this contract once, then run a compiler to build code for each app. Teams use this setup to pass data between services written in different languages. When teams grant broad service roles, any caller can run every method in that contract. A shared key lets one app call admin methods meant for another team.
How a thrift schema works across services
The workflow starts with one plain text file that holds your contract rules. You list base types like numbers, text strings, and true or false flags. Then you group those fields into data structures and give each field a number tag. These number tags matter because the wire format uses tags instead of field names. Next, you define services, which are lists of remote calls that take and return structs. You also declare custom error structs so callers know when a remote task fails. Once the file is ready, the build tool reads it and writes source code. A backend written in Go can talk to a Python worker using those generated files. Both apps agree on field tags and types before they send a single byte. You can also choose how the bytes travel over the network. A binary format keeps messages small and fast for internal calls between backend servers. A text format helps developers read payloads when they test new calls in a staging lab.
Keeping your thrift schema safe during updates
Shared contracts change as your product grows and new features ship to users. You must follow strict rules so old callers do not break when servers update. Never change the number tag of an existing field in a shared data struct. Instead, add new fields with fresh number tags and mark them as optional. When you retire a field, stop reading it in code, but keep its tag reserved. Reusing an old tag number causes old clients to read the wrong data type. You should also avoid marking fields as required in long-lived backend services. Required fields lock you in and cause crashes if one app misses an update. Keep every field optional so old and new apps can run at the same time. Store your contract files in one central code repo so every team reads the same rules. Run a check in your build pipeline to catch tag changes before code merges.
What native contracts solve and what they leave open
A shared contract solves type safety and wire formatting across many programming languages. It stops teams from writing custom parsers for every internal network call. Still, the schema compiler only checks data shapes and method names at build time. It does not check who calls a method or what data travels inside the payload. Native network setups usually check identity once when a client opens a socket. After that login step, the caller can invoke any method listed in the service file. If a struct holds sensitive fields like emails, phone numbers, or card numbers, all fields return. The wire protocol has no built-in rule to rewrite matched fields in results per caller. It also lacks a native audit log that records which user ran a specific call. Teams must build extra checks inside every app handler to block risky requests in flight.
API Schema Validation: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev runs beside each supported service as an open-source proxy, a sidecar for your database or API.
First, hoop.dev guardrails block banned queries before they run. Then hoop.dev data masking rewrites matched sensitive values in responses in memory. The audit trail records every statement and verdict per resource. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
What is the main purpose of a thrift schema?
It defines data structures and service methods in one language-neutral text file. A build tool then creates client and server code for many programming languages.
Why do fields in a thrift schema need number tags?
The wire format sends number tags instead of field names to keep messages small. Tags let apps match fields even if a team renames a field later.
How do you remove a field without breaking old apps?
Make sure the field is optional, then remove its use from your app code. Never reuse that field tag number for a new field in the future.