MongoDB $jsonSchema Operator

What Is $jsonSchema?

$jsonSchema is a MongoDB query operator that checks whether a document matches a JSON Schema rules object. Use it in $match / find() to filter good documents, or attach the same rules as a collection validator to protect inserts and updates.

$jsonSchema = document must match these rules

{ $jsonSchema: {
    bsonType: "object",
    required: ["name", "age"],
    properties: {
      name: { bsonType: "string" },
      age:  { bsonType: "int", minimum: 0 }
    }
  }
}

find / $match  → filter matching docs
validator      → reject or warn on bad writes
prefer bsonType over type

How to Use $jsonSchema in MongoDB

Write a schema once, then either filter with it or enforce it on writes.

1. Describe the document: bsonType: "object", plus required and properties.
2. To audit existing data, put that object inside find({ $jsonSchema: ... }) or $match.
3. To protect new writes, pass the same object as a collection validator.
4. For rollout, start with validationAction: "warn", then switch to "error".

Pseudocode

schema = {
  bsonType: "object",
  required: ["name", "age"],
  properties: {
    name: { bsonType: "string" },
    age:  { bsonType: "int", minimum: 0 }
  }
}

// Filter mode
for each document:
    if document matches schema:
        keep it
    else:
        skip it

// Validator mode (on insert/update)
if newDocument matches schema:
    accept write
else:
    error or warn (per validationAction)

Cheat Sheet

Keep these facts handy while writing validators.

Live Preview

Pick a sample document and see whether it passes a simple student schema (name string + age int ≥ 0.

document = { name: "Asha", age: 14 }

checks:
  required name ✓
  required age  ✓
  name is string ✓
  age is int ≥ 0 ✓

match → YES (kept by find / $match)

Worked Walkthrough — Student Shape

A class roster should always store a student name (string) and age (non-negative int). One document is valid; another is missing age.

Schema:
  required: ["name", "age"]
  name → string
  age  → int, minimum 0

Doc A: { name: "Asha", age: 14 }
  name present + string ✓
  age present + int ≥ 0 ✓
  → MATCH

Doc B: { name: "Ravi" }
  age missing ✗
  → NO MATCH

find({ $jsonSchema: schema }) → only Doc A

MongoDB Examples

We use one small students collection. First insert sample docs, then filter with $jsonSchema, then show a collection validator. Run these in mongosh.

db.students.insertMany([
  { _id: 1, name: "Asha", age: NumberInt(14) },
  { _id: 2, name: "Ravi" }
]);

db.students.find()

[
  { _id: 1, name: "Asha", age: 14 },
  { _id: 2, name: "Ravi" }
]
// age stored as int via NumberInt(14)

Schema wants:  name (string) + age (int ≥ 0)

  Asha  → name ✓  age ✓   MATCH
  Ravi  → name ✓  age ✗   FAIL

Next: find only the matching ones

db.students.find({
  $jsonSchema: {
    bsonType: "object",
    required: ["name", "age"],
    properties: {
      name: { bsonType: "string" },
      age: { bsonType: "int", minimum: 0 }
    }
  }
});

{ _id: 1, name: "Asha", age: 14 }

db.createCollection("roster", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["name", "age"],
      properties: {
        name: { bsonType: "string" },
        age: { bsonType: "int", minimum: 0 }
      }
    }
  },
  validationAction: "error"
});

// OK
db.roster.insertOne({ name: "Asha", age: NumberInt(14) });

// Rejected — missing age
db.roster.insertOne({ name: "Ravi" });

// First insert — accepted
{ acknowledged: true, insertedId: ObjectId("...") }

// Second insert — rejected
MongoServerError: Document failed validation

Performance Notes

Keep schemas lean—only the fields you truly need. For hot paths, prefer $type or $exists when a full schema is overkill.

Key Takeaways