Skip to main content

The Problem With JSON Schema (And What We Did Differently)

CJ Cummings
Creator and maintainer of Stof, co-founder & CEO of Limitr

JSON Schema's real limitation isn't its syntax. It's that a schema is always a second document describing a first one, and nothing keeps the two in agreement. Add a field to your data, forget the schema, and nothing tells you.

Stof takes a different approach: #[schema(...)] puts the rule on the field it protects, in the same document. There's no second file to fall out of sync.

Where JSON Schema struggles​

It's kept in sync by hand. The schema and the data live in different places, maintained by whoever remembers to update both. Nothing enforces the connection except discipline, which is the first thing to go under a deadline.

It has no units. "Memory in MB, at least 256" ends up as a string with a description. JSON Schema can check that a value is a number, but it can't know that "2GB" and 2000 MB are the same thing, or that a value in KB doesn't belong where MB was meant.

Rules across fields are awkward. Checking one field against another takes $data references or vendor extensions that most tools only partly support. Something that's one line of real code turns into a fight with the format.

The checks get written twice anyway. Most teams still write the same validation in app code: for better error messages, for logic the schema can't express, or because it's faster than fighting the format.

None of this means JSON Schema is badly designed. It validates the shape of any JSON, in a language-neutral way that tools understand. The problem is structural: validation lives somewhere other than the data.

Validation as part of the data​

In Stof, a rule is an attribute on the field it checks. Press Run:

plan.stofPlayground ↗
#[type]
Plan: {
  #[schema((target_val: str): bool => target_val != null && target_val.len() > 0)]
  str label: 'Growth'

  #[schema((target_val: hr): bool => target_val != null && target_val > 0hr)]
  hr reset_every: 1hr
}

#[main]
fn main() {
  pln(<Plan>.schemafy(new { label: 'Pro', reset_every: 60min }));
  pln(<Plan>.schemafy(new { label: '', reset_every: 0s }));
}
Output

schemafy checks an object against every rule on the type. The unit-typed field means something: 1hr and 60min are the same value as far as the rule is concerned.

More than one rule​

A list of rules runs in order, and every one has to pass:

fn not_empty(target_val: str) -> bool { target_val != null && target_val.len() > 0 }

#[type]
Contact: {
#[schema([self.not_empty, (target_val: str): bool => target_val.contains('@')])]
str email: ''
}

A bare #[schema] on a field that holds an object checks that object against the rules inside it, so nested data is validated without writing the traversal yourself.

And schemafy can clean data instead of only rejecting it. remove_invalid = true drops fields that fail their rules, and remove_undefined = true drops fields the type doesn't declare:

clean.stofPlayground ↗
#[type]
Profile: {
  #[schema((target_val: str): bool => target_val != null && target_val.len() > 0)]
  str name: ''

  #[schema((target_val: str): bool => target_val != null && target_val.len() <= 12)]
  str nickname: ''
}

#[main]
fn main() {
  const input = new { name: 'Ada', nickname: 'a nickname far too long', admin: true };
  <Profile>.schemafy(input, remove_invalid = true, remove_undefined = true);
  pln(stringify('json', input));
}
Output

None of this needs a second file, a second syntax, or a build step to keep generated types in sync. It's the same document doing one more thing. A Self-Validating Config builds a complete example, and Prototypes & Schemas is the full reference.

FAQ​

Does Stof replace JSON Schema? For Stof documents, yes: #[schema] is built in. For checking plain JSON in a system that doesn't use Stof, JSON Schema is still a fine tool for that narrower job.

Can a Stof schema check data that didn't start as Stof? Yes. schemafy works on any object, including one parsed from JSON, YAML, TOML, or form data. It doesn't need to have been created from the type.

What happens when validation fails? schemafy returns false instead of throwing, so a failure is a value you check. With remove_invalid, it can also clean the object, and comparing before and after tells you which fields failed.

Is this like Zod, Yup, or Pydantic? Same goal: the rule next to the type, not in a separate file. But those check data at the edge of one language's app. Stof's rules live in the document, so they run the same in TypeScript, Python, Rust, or a browser.