見出し画像

PostmanでのAjvによるJSONスキーマ検証(Schema validation)|SHIFTのブログリレーDAY18

ーこの春、頑張るあなたを応援したい!ー

こんにちは!SHIFTの公式note「SHIFTグループ技術ブログ」編集部です。
この春、新社会人になられた方や、転職など新天地でのスタートを切られた方など、今を頑張るすべての方へ(勝手に)エールを贈りたい!
今自分たちがもっているノウハウや経験を、書いてつないで、頑張るあなたに届けたい!そんな、“おせっかい心”から生まれた企画です。

・GW明けから勝負本番!良いスタートダッシュを切りたい!
・新人扱いしてもらえる今のうち!やっておくべきことは?
・みんなが優秀に見える・・・これから大丈夫かなあ。

そんなさまざまな気持ちに、社会人の仲間として、ときには少し先輩として、SHIFTの公式ブロガーたちが全力であなたに伴走します。
少しでも、今を頑張る方の前へ進む力になれますように。
みなさまにご一読いただければ幸いです!《開催期間:5/1-25》

▶DAY18 本日はこちらの記事!
PostmanでのAjvによるJSONスキーマ検証(Schema validation)

◀◀◀DAY17
拝啓、20年前の自分へ~山あり谷ありの社会人生活を楽しむための心持ち~



はじめに

こんにちは。DevOps推進1Gの山田です。

本記事では、PostmanでのJSONスキーマの検証手順を簡単な例とともに紹介します。 また、JSONスキーマ検証にあたってPostmanのコレクションが必要になるので、Swagger Petstoreのインポート手順も解説します。

PostmanでのJSONスキーマ検証用のライブラリには、Ajvのほかにtv4が存在しますが、tv4は2017年を最後に更新を停止していて、さらにGitHubのREADME.mdには「This project is no longer actively maintained.」と明示されています。 そのため、Ajvの使用を推奨しAjvでの実装を載せています。

以下、Postman for Windows Version 10.13.5での紹介をさせていただきます。

新卒応援企画の一環としてこちらを投稿していますので、新卒の方には馴染みのない単語などもあるかと思いますが、

  • 「技術ブログってそんなにハードル高くない」

  • 「とりあえずPostmanを触ってみよう」

などを思っていただけたら幸いです。

執筆者プロフィール:山田 直輝
2022/4に新卒入社し、一人前の自動化エンジニアを目指して現在勉強中。
趣味は本読んだり、映画見たり、走ったり、ゲームしたり…。あと睡眠。

環境準備

本記事では、オンラインで公開されているペットショップのサンプルサーバを使用します。 まずはこちらのコレクションのインポート手順から説明します。 ペットショップのOpenAPI仕様書のURLは https://petstore.swagger.io/ になります。

1. OpenAPI仕様書のリンク先からJSONのリンクURLをコピー

2. Postmanで「Import」を押下

3. 手順1でコピーしたリンクURLをペースト

4. 「Import」を押下

5. 完了(左ペインに「Swagger Petstore」のコレクションがある)

検証データ準備

ここでは、検証用のペットのデータを作成します。 まずはペットのIDに重複がないかチェックします。 Swagger Petstore / pet / {petId} / Find pet by ID で「Params」タブの「Path Variables」の「petId」のValueを任意の数値(例:123456)に設定して、検索してみましょう。

ペットのIDに重複がなければ検索に失敗します。 画像の下赤枠部に囲われたレスポンスを見ると、Statusが「404 Not Found」であり、Bodyの"messeage"が"Pet not found"になっています。

重複がないことが確認出来たら、Swagger Petstore / pet / Add a new pet ro the store を実施して、検証用のペットのデータを作成します。 以下はBodyのサンプルです。

{
  "name": "validation_sample",
  "photoUrls": [
    "photoUrls_string"
  ],
  "id": 123456,
  "category": {
    "id": 13,
    "name": "category_string"
  },
  "tags": [{
    "id": 135,
    "name": "tags_name_string"
  }],
  "status": "available"
}

Swagger Petstore / pet / Add a new pet ro the store の実施例

Swagger Petstore / pet / {petId} / Find pet by ID で上で作成したペットのデータを再度検索してみましょう。

ペットIDの作成に成功していれば、Statusが「200 OK」になっていて、Bodyに先ほど作成したデータが入っています。

スキーマ検証

Swagger Petstore / pet / {petId} / Find pet by ID を例にスキーマ検証を実装していきます。 「Tests」タブを開き、次の最も簡単なスキーマ検証スクリプトを記述してみましょう。
1~3行目が検証したいスキーマの内容になります。 5~7行目でPostmanで送ったAPIのレスポンスがschemaで指定した内容と整合するかテストします。 スキーマ検証が通過すれば、下の「Test Results」タブでPASSと表示されます。

const schema = {
    "type": "object"
}

pm.test("Validate schema", () => {
    pm.response.to.have.jsonSchema(schema);
});

スキーマ検証が通過しない場合を確認します。 上記のサンプルの2行目の"object"を"string"にして実行すると検証に失敗します。 その場合は、整合しなかった部分の記載(例: AssertionError: expected data to satisfy schema but found following errors: data should be string)と共にFAILと表示されます。

スキーマ検証のオプション

schemaの記述を変更することで、より詳細な検証が可能になります。

下記リンクにはここに記載していないものもあるので、高度なスキーマ検証を実施する場合には参考にしてください。

JSON Schema | Ajv JSON schema validator
URL:https://ajv.js.org/json-schema.html

type

typeには以下の値を指定することができます。

  • number

  • integer

  • string

  • boolean

  • array

  • object

  • null

required

オブジェクトに指定したプロパティが存在することを検証します。 下記の例では、プロパティに"id","category",name","status"が存在することを検証します。

const schema = {
    "type": "object",
    "required": ["id", "category", "name", "status"]
}

properties

オブジェクトの中にあるプロパティを検証します。 下記の例では、id"のデータ型がinteger型であるかを検証します。

const schema = {
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        }
    }
}

minimum, maximum

数値データに対して、最小値または最大値を検証します。 下記の例では、id"が0以上1000000以下の値であるかを検証します。

const schema = {
    "type": "object",
    "properties": {
        "id": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
        }
    }
}

minLength, maxLength

文字列データに対して文字列の長さの最小値または最大値を検証します。 下記の例では、"name"の文字列の長さが1文字以上20文字以下であるかを検証します。

const schema = {
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20
        }
    }
}

pattern

文字列データに対して、値を正規表現で検証します。 下記の例では、"name"の値が、文頭がvの1回以上の繰り返しで始まる文字列であることを検証します。

const schema = {
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "pattern": "^v+"
        }
    }
}

ネスト構造のスキーマ検証

サンプルで作成したオブジェクトのプロパティをもう一度見てみます。 "category"がネスト構造になっていてその中にも"id"があったり、"tags"が配列であったりと様々な検証が考えられます。

{
  "name": "validation_sample",
  "photoUrls": [
    "photoUrls_string"
  ],
  "id": 123456,
  "category": {
    "id": 13,
    "name": "category_string"
  },
  "tags": [{
    "id": 135,
    "name": "tags_name_string"
  }],
  "status": "available"
}

"properties"を重ねることで、ネスト構造を検証することができます。 配列については、本記事では配列型であることのみを検証し、詳細な検証については割愛しています。

const schema= {
    "type": "object",
    "required": ["id", "category", "name", "status"],
    "properties": {
        "id": {
            "type": "integer",
            "minimum": 100000,
            "maximum": 1000000
        },
    
        "category": {
            "type": "object",
            "required": ["id", "name"],
            "properties": {
                "id": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 100
                },
                "name": {
                    "type": "string",
                    "pattern": "^c+"
                }
            }
        },

        "name": {
            "type": "string",
            "pattern": "^v+"
        },

        "tags": {
            "type": "array",
        }
    }
}

まとめ

本記事では、Postmanでのスキーマ検証方法について紹介しました。 Postmanではほかにもデータドリブンテストが実施できたり、NewmanによるCLIベースの実行に切り替えることでCI/CDに組み込んだりと、できることは様々なので試してみると面白いと思います。


参考サイト

Postman API Platform
URL:https://www.postman.com/

Swagger UI
URL:https://petstore.swagger.io/

JSON Schema | Ajv JSON schema validator
URL:https://ajv.js.org/json-schema.html

GitHub - geraintluff/tv4: Tiny Validator for JSON Schema v4
URL:https://github.com/geraintluff/tv4

Schema validation — Postman Quick Reference Guide Version 1.9.1 - January 2023 documentation
URL:https://postman-quick-reference-guide.readthedocs.io/en/latest/schema-validation.html

TypeScript(Node.js)のバリデーションライブラリ「Ajv」を使ってみた | DevelopersIO
URL:https://dev.classmethod.jp/articles/typescript-node-js-validation/


明日のSHIFTのブログリレーはコチラ!
▶▶▶DAY19  ChatGPTで指示待ち人間から指示出し人間へ(立野)


\SHIFTのフレッシャーズ応援!ブログリレー企画/
25日の給料日まで勝手に伴走するおせっかいを実施中。

お問合せはお気軽に
https://service.shiftinc.jp/contact/

SHIFTについて(コーポレートサイト)
https://www.shiftinc.jp/

SHIFTのサービスについて(サービスサイト)
https://service.shiftinc.jp/

SHIFTの導入事例
https://service.shiftinc.jp/case/

お役立ち資料はこちら
https://service.shiftinc.jp/resources/

SHIFTの採用情報はこちら
https://recruit.shiftinc.jp/career/