JSON スキーマ検証の作成と使用サポートされるキーワード bypassDocumentValidation 制約事項

JSON スキーマ検証の使用

$jsonSchema 評価クエリ演算子を使用すると、コレクションに挿入されているドキュメントを検証できます。

トピック

JSON スキーマ検証の作成と使用
サポートされるキーワード
bypassDocumentValidation
制約事項

JSON スキーマ検証の作成と使用

スキーマ検証によるコレクションの作成

createCollection 操作ルールと検証ルールを含むコレクションを作成できます。これらの検証ルールは、Amazon DocumentDB ドキュメントの挿入または更新時に適用されます。以下は、従業員のコレクションの検証ルールを説明するコード例です。


db.createCollection("employees", {
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   },
   "validationLevel": "strict", "validationAction": "error"
} )

有効なドキュメントを挿入します

次の例では、上記のスキーマ検証ルールに準拠するドキュメントを挿入します。


db.employees.insert({"name" : { "firstName" : "Carol" , "lastName" : "Smith"}, "employeeId": "c720a" , "salary": 1000.0 })
db.employees.insert({ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24})

無効なドキュメントを挿入します

次の例では、上記のスキーマ検証ルールに準拠していないドキュメントを挿入します。この例では、employeeId の値は文字列ではありません。


db.employees.insert({
    "name" : { "firstName" : "Carol" , "lastName" : "Smith"}, 
    "employeeId": 720 , 
    "salary": 1000.0 
})

この例は、文書内の構文が正しくないことを示しています。

コレクションを変更する

collMod コマンドは、既存のコレクションの検証ルールを追加または変更するために使用されます。次の例では、給与フィールドを必須フィールドリストに追加しています。


db.runCommand({"collMod" : "employees", 
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId", "salary"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   }
} )

検証ルールが変更される前に追加されたドキュメントの対処

検証ルールが変更される前にコレクションに追加されたドキュメントの対処には、以下の validationLevel 修飾子を使用します。

strict: すべての挿入と更新に検証ルールを適用します。
moderate: 既存の有効なドキュメントに検証ルールを適用します。更新中、既存の無効なドキュメントはチェックされません。

次の例では、「employees」という名前のコレクションの検証ルールを更新した後に、給与フィールドが必須になります。次のドキュメントの更新は失敗します。


db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }] 
})

Amazon DocumentDB は、次の出力を返します。


{
"n" : 0,
    "nModified" : 0,
    "writeErrors" : [
        {
"index" : 0,
            "code" : 121,
            "errmsg" : "Document failed validation"
        }
    ],
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

検証レベルを moderate に更新すると、上記のドキュメントを正常に更新できるようになります。


db.runCommand({
    "collMod" : "employees", 
    validationLevel : "moderate"
})

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }]
})

Amazon DocumentDB は、次の出力を返します。


{
"n" : 1,
    "nModified" : 1,
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

$jsonSchema を使用してドキュメントの取得

$jsonSchema 演算子は、JSON スキーマに一致するドキュメントをクエリするフィルタとして使用できます。これは最上位の演算子で、フィルタードキュメントに最上位フィールドとして含めることも $and、$or、$nor などのクエリ演算子と一緒に使用することもできます。以下の例は、$jsonSchema を個別のフィルターとして、また他のフィルター演算子と併用する方法を示しています。

「employee」コレクションに挿入されたドキュメント:


{ "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
{ "name" : { "firstName" : "Jane", "lastName" : "Doe" }, "employeeId" : "c721a", "salary" : 1300 }

$jsonSchema 演算子のみでフィルタリングされたコレクション:


db.employees.find({ 
       $jsonSchema: { required: ["age"] } })

Amazon DocumentDB は、次の出力を返します。


{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

$jsonSchema 演算子と別の演算子でフィルタリングされたコレクション:


db.employees.find({ 
       $or: [{ $jsonSchema: { required: ["age", "name"]}}, 
            { salary: { $lte:1000}}]});

Amazon DocumentDB は、次の出力を返します。


{ "_id" : ObjectId("64e5f8886218c620cf0e8f8a"), "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

$jsonSchema 演算子でフィルタリングされ、集計フィルタでは $match でフィルタリングされたコレクション:


db.employees.aggregate(
    [{ $match: { 
        $jsonSchema: { 
            required: ["name", "employeeId"],  
            properties: {"salary" :{"bsonType": "double"}}
        }
       }
    }]
)

Amazon DocumentDB は、次の出力を返します。


{ 
"_id" : ObjectId("64e5f8886218c620cf0e8f8a"),
 "name" : { "firstName" : "Carol", "lastName" : "Smith" },
"employeeId" : "c720a",
"salary" : 1000 
}
{
"_id" : ObjectId("64e5f91c6218c620cf0e8f8b"),
"name" : { "firstName" : "Emily", "lastName" : "Brown" },
"employeeId" : "c720b",
"age" : 25,
"salary" : 1050.2
}
{
"_id" : ObjectId("64e5f94e6218c620cf0e8f8c"),
"name" : { "firstName" : "William", "lastName" : "Taylor" },
"employeeId" : "c721a",
"age" : 24,
"salary" : 1400.5
}
{
"_id" : ObjectId("64e5f9786218c620cf0e8f8d"),
"name" : { "firstName" : "Jane", "lastName" : "Doe" },
"employeeId" : "c721a",
"salary" : 1300
}

既存の検証ルールの表示

コレクションの既存の検証ルールを確認するには、以下を使用してください。


db.runCommand({
    listCollections: 1, 
    filter: { name: 'employees' }
})

Amazon DocumentDB は、次の出力を返します。


{
    "waitedMS" : NumberLong(0),
    "cursor" : {
        "firstBatch" : [
            {
                "name" : "employees",
                "type" : "collection",
                "options" : {
                    "autoIndexId" : true,
                    "capped" : false,
                    "validator" : {
                        "$jsonSchema" : {
                            "bsonType" : "object",
                            "title" : "employee validation",
                            "required" : [
                                "name",
                                "employeeId",
                                "salary"
                            ],
                            "properties" : {
                                "name" : {
                                    "bsonType" : "object",
                                    "properties" : {
                                        "firstName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        },
                                        "lastName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        }
                                    },
                                    "additionalProperties" : false
                                },
                                "employeeId" : {
                                    "bsonType" : "string",
                                    "description" : "Unique Identifier for employee"
                                },
                                "salary" : {
                                    "bsonType" : "double"
                                },
                                "age" : {
                                    "bsonType" : "number"
                                }
                            },
                            "additionalProperties" : true
                        }
                    },
                    "validationLevel" : "moderate",
                    "validationAction" : "error"
                },
                "info" : {
                    "readOnly" : false
                },
                "idIndex" : {
                    "v" : 2,
                    "key" : {
                        "_id" : 1
                    },
                    "name" : "_id_",
                    "ns" : "test.employees"
                }
            }
        ],
        "id" : NumberLong(0),
        "ns" : "test.$cmd.listCollections"
    },
    "ok" : 1,
    "operationTime" : Timestamp(1692788937, 1)
}

Amazon DocumentDB は、$out 集約ステージでも検証ルールを保持します。

サポートされるキーワード

create および collMod コマンドでは以下のフィールドがサポートされています。

Validator: $jsonSchem オペレーションをサポートしています。
ValidationLevel: off、strict、moderate の値をサポートします。
ValidationAction: error の値をサポートします。

$jsonSchema 演算子は以下のキーワードをサポートします。

additionalItems
additionalProperties
allOf
anyOf
bsonType
dependencies
description
enum
exclusiveMaximum
exclusiveMinimum
items
maximum
minimum
maxItems
minItems
maxLength
minLength
maxProperties
minProperties
multipleOf
not
oneOf
pattern
patternProperties
properties
required
title
type
uniqueItems

bypassDocumentValidation

Amazon DocumentDB は、次のコマンドとメソッドについて bypassDocumentValidation をサポートしています。

insert
update
findAndModify
aggregate コマンドおよび db.collection.aggregate() メソッドにおける $out ステージ

Amazon DocumentDB は、次のコマンドについては bypassDocumentValidation をサポートしていません。

aggregate コマンドおよび db.collection.aggregate() メソッドにおける $merge
mapReduce コマンドおよび db.collection.mapReduce() メソッド
applyOps コマンド

制約事項

$jsonSchema の検証には以下の制限が適用されます。

Amazon DocumentDB は、オペレーションが検証ルールに失敗すると、「ドキュメントの検証に失敗しました」というエラーを返します。
Amazon DocumentDB Elastic クラスターは、$jsonSchema をサポートしていません。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

変更ストリームでの AWS Lambda の使用

レプリカセットとして接続する