Skip to content

Commit 1a61fa8

Browse files
Pavithra Vetriselvankay-kim
Pavithra Vetriselvan
authored and
kay-kim
committed
DOCS-10810 added new page for JSON schema support
1 parent c32ee2c commit 1a61fa8

File tree

5 files changed

+353
-0
lines changed

5 files changed

+353
-0
lines changed

‎source/core/document-validation.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,16 @@ but allows the insertion or update to proceed.
158158

159159
2015-10-15T11:20:44.260-0400 W STORAGE [conn3] Document would fail validation collection: example.contacts doc: { _id: ObjectId('561fc44c067a5d85b96274e4'), name: "Amanda", status: "Updated" }
160160

161+
Schema Validation
162+
~~~~~~~~~~~~~~~~~
163+
164+
.. versionadded:: 3.6
165+
166+
With the addition of the :query:`$jsonSchema` operator, you can write queries
167+
to express a richer set of schema validation rules.
168+
169+
See :ref:`doc-insert-schema-validation` for an example using the ``validator``
170+
option with :query:`$jsonSchema` while inserting a document.
161171

162172
Restrictions
163173
------------

‎source/includes/fact-json-schema-validation-keywords.rst

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. list-table::
2+
:header-rows: 1
3+
4+
* - Keyword
5+
- Type
6+
- Definition
7+
- Behavior
8+
9+
* - bsonType
10+
- all types
11+
- string alias or array of string aliases
12+
- Accepts same :ref:`string aliases <document-type-available-types>`
13+
used for the :query:`$type` operator
14+
15+
* - enum
16+
- all types
17+
- array of values
18+
- Enumerates all possible values of the field
19+
20+
* - type
21+
- all types
22+
- string or array of unique strings
23+
- Enumerates the possible JSON types of the field. Available types are
24+
"object", "array", "number", "boolean", "string", and "null".
25+
26+
* - allOf
27+
- all types
28+
- array of JSON Schema objects
29+
- Field must match all specified schemas
30+
31+
* - anyOf
32+
- all types
33+
- array of JSON Schema objects
34+
- Field must match at least one of the specified schemas
35+
36+
* - oneOf
37+
- all types
38+
- array of JSON Schema objects
39+
- Field must match exactly one of the specified schemas
40+
41+
* - not
42+
- all types
43+
- a JSON Schema object
44+
- Field must not match the schema
45+
46+
* - multipleOf
47+
- numbers
48+
- number
49+
- Field must be a multiple of this value
50+
51+
* - maximum
52+
- numbers
53+
- number
54+
- Indicates the maximum value of the field
55+
56+
* - exclusiveMaximum
57+
- numbers
58+
- boolean
59+
- If true and field is a number, ``maximum`` is an exclusive maximum.
60+
Otherwise, it is an inclusive maximum.
61+
62+
* - minimum
63+
- numbers
64+
- number
65+
- Indicates the minimum value of the field
66+
67+
* - exclusiveMinimum
68+
- numbers
69+
- boolean
70+
- If true, ``minimum`` is an exclusive minimum. Otherwise, it is an
71+
inclusive minimum.
72+
73+
* - maxLength
74+
- strings
75+
- integer
76+
- Indicates the maximum length of the field
77+
78+
* - minLength
79+
- strings
80+
- integer
81+
- Indicates the minimum length of the field
82+
83+
* - pattern
84+
- strings
85+
- string containing a regex
86+
- Field must match the regular expression
87+
88+
* - maxProperties
89+
- objects
90+
- integer
91+
- Indicates the field's maximum number of properties
92+
93+
* - minProperties
94+
- objects
95+
- integer
96+
- Indicates the field's minimum number of properties
97+
98+
* - required
99+
- objects
100+
- array of unique strings
101+
- Object's property set must contain all the specified elements in the
102+
array
103+
104+
* - additionalProperties
105+
- objects
106+
- boolean or object
107+
- If ``true``, additional fields are allowed. If ``false``, they are not.
108+
If a valid JSON Schema object is specified, additional fields must
109+
validate against the schema.
110+
111+
Defaults to ``true``.
112+
113+
* - properties
114+
- objects
115+
- object
116+
- A valid JSON Schema where each value is also a valid JSON Schema object
117+
118+
* - patternProperties
119+
- objects
120+
- object
121+
- In addition to ``properties`` requirements, each property name of this
122+
object must be a valid regular expression
123+
124+
* - dependencies
125+
- objects
126+
- object
127+
- Describes field or schema dependencies
128+
129+
* - additionalItems
130+
- arrays
131+
- boolean or object
132+
- If an object, must be a valid JSON Schema
133+
134+
* - items
135+
- arrays
136+
- object or array
137+
- Must be either a valid JSON Schema, or an array of valid JSON Schemas
138+
139+
* - maxItems
140+
- arrays
141+
- integer
142+
- Indicates the maximum length of arrayy
143+
144+
* - minItems
145+
- arrays
146+
- integer
147+
- Indicates the minimum length of array
148+
149+
* - uniqueItems
150+
- arrays
151+
- boolean
152+
- If true, each item in the array must be unique. Otherwise, no uniqueness
153+
constraint is enforced.
154+
155+
* - title
156+
- N/A
157+
- string
158+
- A descriptive title string with no effect.
159+
160+
* - description
161+
- N/A
162+
- string
163+
- A string that describes the schema and has no effect.

‎source/reference/operator/query/jsonSchema.txt

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
===========
2+
$jsonSchema
3+
===========
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. query:: $jsonSchema
17+
18+
.. versionadded:: 3.6
19+
20+
The :query:`$jsonSchema` operator matches documents that validate against
21+
the given JSON Schema.
22+
23+
.. code-block:: javascript
24+
25+
{ $jsonSchema: <schema> }
26+
27+
.. note::
28+
29+
MongoDB 3.6 supports draft 4 of JSON Schema, including
30+
`core specification <https://tools.ietf.org/html/draft-zyp-json-schema-04>`_
31+
and `validation specification
32+
<https://tools.ietf.org/html/draft-fge-json-schema-validation-00>`_,
33+
with some differences. See `Extensions` and `Omissions` for details.
34+
35+
For more information about JSON Schema, see the
36+
`official website <http://json-schema.org/>`_.
37+
38+
Behavior
39+
--------
40+
41+
:query:`$jsonSchema` can be used in a document validator, which enforces that
42+
inserted or updated documents are valid against the schema. It can also be used
43+
to query for documents with the :dbcommand:`find` command or :pipeline:`$match`
44+
aggregation stage.
45+
46+
.. warning::
47+
48+
``featureCompatibilityVersion`` must be set to ``"3.6"`` or higher in order to
49+
use :query:`$jsonSchema` in a document validator. Any such validator must be
50+
removed, either by dropping the collection or by using :dbcommand:`collMod`,
51+
before downgrading to version 3.4 of the server.
52+
53+
Available Keywords
54+
~~~~~~~~~~~~~~~~~~
55+
56+
.. include:: /includes/fact-json-schema-validation-keywords.rst
57+
58+
Extensions
59+
----------
60+
61+
MongoDB's implementation of JSON Schema includes the addition of the ``bsonType``
62+
keyword, which allows you to use all :term:`BSON` types in the
63+
:query:`$jsonSchema` operator. ``bsonType`` accepts the same string aliases used
64+
for the :query:`$type` operator.
65+
66+
Omissions
67+
---------
68+
69+
The following will not be supported in MongoDB's implemenation of JSON Schema:
70+
71+
- `Hypertext definitions <https://tools.ietf.org/html/draft-luff-json-hyper-schema-00>`_
72+
in draft 4 of the JSON Schema spec.
73+
74+
- The keywords:
75+
76+
- ``$ref``
77+
78+
- ``$schema``
79+
80+
- ``default``
81+
82+
- ``definitions``
83+
84+
- ``format``
85+
86+
- ``id``
87+
88+
- The ``integer`` type. You must use the :term:`BSON` type ``int`` or ``long``
89+
with the ``bsonType`` keyword.
90+
91+
- Hypermedia and linking properties of JSON Schema, including the use of
92+
JSON References and JSON Pointers.
93+
94+
- Unknown keywords.
95+
96+
Examples
97+
--------
98+
99+
.. _doc-insert-schema-validation:
100+
101+
Schema Validation
102+
~~~~~~~~~~~~~~~~~
103+
104+
The following :method:`db.createCollection()` method creates a collection
105+
named ``students`` and uses the ``validator`` to set multiple rules for the
106+
schema design:
107+
108+
.. code-block:: javascript
109+
110+
db.createCollection("students", {
111+
validator: {
112+
$jsonSchema: {
113+
bsonType: "object",
114+
required: [ "name", "year", "major", "gpa" ],
115+
properties: {
116+
name: {
117+
bsonType: "string",
118+
description: "must be a string and is required"
119+
},
120+
gender: {
121+
bsonType: "string",
122+
description: "must be a string and is not required"
123+
},
124+
year: {
125+
bsonType: "int",
126+
minimum: 2017,
127+
maximum: 3017,
128+
exclusiveMaximum: false,
129+
description: "must be an integer in [ 2017, 3017 ] and is required"
130+
},
131+
major: {
132+
enum: [ "Math", "English", "Computer Science", "History", null ],
133+
description: "can only be one of the enum values and is required"
134+
},
135+
gpa: {
136+
bsonType: [ "double" ],
137+
description: "must be a double and is required"
138+
}
139+
}
140+
}
141+
}
142+
})
143+
144+
Given the created ``validator`` for the collection, the following insert
145+
operation will fail because ``gpa`` is an integer when the ``validator``
146+
requires a ``double``.
147+
148+
.. code-block:: javascript
149+
150+
db.students.insert({
151+
name: "Alice",
152+
grad_year: NumberInt(2019),
153+
major: "History",
154+
gpa: NumberInt(3)
155+
})
156+
WriteResult({
157+
"nInserted" : 0,
158+
"writeError" : {
159+
"code" : 121,
160+
"errmsg" : "Document failed validation"
161+
}
162+
})
163+

‎source/release-notes/3.6-compatibility.txt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ Compatibility Changes in MongoDB 3.6 Release Candidate
44

55
.. default-domain:: mongodb
66

7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: twocols
12+
713
.. include:: /includes/in-dev.rst
814

915
Security Compatibility Changes
@@ -234,3 +240,11 @@ To set the ``featureCompatibilityVersion``, see
234240

235241
.. include:: /includes/list-table-featureCompatibilityVersion-defaults.rst
236242

243+
Upgrading Before Using ``$jsonSchema``
244+
-------------------------------------
245+
246+
``featureCompatibilityVersion`` must be set to ``"3.6"`` in order to use
247+
:query:`$jsonSchema` in a document validator. Any such validator must be
248+
removed by either dropping the collection or by using :dbcommand:`collMod`
249+
before downgrading to version 3.4 of the server. Otherwise, a 3.4 server
250+
will not start up.

‎source/release-notes/3.6.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,9 @@ MongoDB 3.6 includes the following enhancements:
367367
database have propagated to a majority of the replica set members.
368368

369369

370+
- The new :query:`$jsonSchema` operator matches documents that validate
371+
against the given JSON Schema.
372+
370373
Changes Affecting Compatibility
371374
-------------------------------
372375

0 commit comments

Comments
 (0)