$jsonSchema (JSON Schema Validation)
Last updated: 2026-10-09
$jsonSchema (JSON Schema Validation)
$jsonSchema validates document structure against the JSON Schema draft standard, usable as a query predicate or collection validator. `{ $jsonSchema: { required: ['name'], properties: { age: { bsonType: 'int' } } } }`. It supports required fields, type constraints and property patterns, but cannot use normal indexes and is costly on large collections — best for data-quality checks.
| Category | Element & Evaluation |
|---|---|
| MongoDB Version | 3.6+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $jsonSchema: { required: [ <field name> ], properties: { <property>: { <constraint> } } } }⚙️ Parameters
| schema object | A JSON Schema document with keys like required, properties, bsonType. |
|---|
Returns：Cursor of matching documents
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $jsonSchema: name required, age must be int
db.users.find({
$jsonSchema: {
required: ['name'],
properties: {
age: { bsonType: 'int' }
}
}
})Output：
// Returns documents with name present and age of type int (undeclared age also passes)📌 Notes
- Use bsonType to pin BSON types (int, string, objectId, etc.)
- Cannot use normal indexes; avoid frequent use on large collections
- The same syntax powers collection validators (the validator option of db.createCollection)
🏷️ Related Tags
💡 Related Cases
📚 Related Tutorials
❓ FAQ
QCan $jsonSchema validate nested objects?
AYes, nest properties inside properties to validate level by level.
QWhat is the difference between $jsonSchema and $type?
A$type tests one field's type; $jsonSchema validates whole-document structure with required, nesting and multiple fields.
QCan I use $jsonSchema when creating a collection?
AYes, pass validator: { $jsonSchema: {...} } to db.createCollection as a write-time validator.
