公開日

JSON Schemaについて発表しました

「JSON Schemaでバックエンドエンジニアとフロントエンドエンジニアがコラボする」と題してエムスリー x Gunosy Beer bashで発表してきました。

当日ハッシュタグ: #gunosybeer hashtag on Twitter

発表資料:point_down:

2 Types of JSON Schema

JSON Schema and Hyper-Schema

  • JSON Schema
  • JSON Hyper-Schema

JSON Schema

  • JSONの データフォーマット を記述する
  • 人間にも機械にもわかりやすいドキュメント
  • フォームでサブミットするデータのバリデーションに使える
  • 自動テストにも使える

JSON Hyper-Schema

  • Web APIの仕様 を記述する
  • APIで期待するデータをJSON Schemaの形式で記述
  • 日本ではこっちの方がポピュラー？

観測範囲内だと日本のコミュニティでJSON Schemaといったときにこちらを指すことが多い気がする。

コラボレーション図

JSON Schemaでコラボレーションした事例を紹介するよ。

+------------------+
|                  |
|  Client-side JS  |
|     (React)      |
|                  |
+---+--------+-----+
    |        ^
    |        |            +---------------+
    |  JSON  |  <-------- |  JSON Schema  |
    |        |            +---------------+
    v        |
+---+--------+-----+
|                  |
| Server-side API  |
|     (Rails)      |
|                  |
+------------------+

JSON Schema for us

  • For Humans
    • Clear specification
  • For Apps
    • useful for Validation
    • useful for Test
    • etc.

Repositories

  • :point_down: Rails API Repo :point_down:
  • :point_right: JSON Schema Repo :point_left:
  • :point_up_2: Frontend Repo :point_up_2:

バックエンドAPIのレポジトリ、フロントエンドのJSレポジトリ、共通で使うJSON Schemaのためのレポジトリ、これら３つを用意した。

Workflow

  1. 必要なAPIとそこに含まれるべきデータを洗い出し
  2. 1をJSON Schemaに落としこむ
  3. プルリク！

1は仕様・ワイヤーをもとにマークダウンでもスプレッドシートでも荒くアウトプット出す。

バックエンドエンジニアとフロントエンドエンジニアが共通認識を深めながらJSON Schemaレポジトリを育てていく。

GET /users/{id}

# user.schema.yml
$schema: http://json-schema.org/draft-04/schema#
title: User
description: An User
type: object
properties:
  id:
    type: integer
  email:
    type: string
    format: email
  name:
    type: string
    minLength: 1
    maxLength: 32
required:
  - id
  - email
  - name

PUT /users/{id}とかもスキーマ使いまわせる。

JSON Schema Validation

require 'json-schema'

schema = {
  "type" => "object",
  "required" => ["a"],
  "properties" => {
    "a" => {"type" => "integer"}
  }
}
data = {
  "a" => 5
}

JSON::Validator.validate(schema, data)

RSpec JSON Schema Matcher

describe "Fetching the current user" do
  context "with valid auth token" do
    it "returns the current user" do
      user = create(:user)
      auth_header = { "Auth-Token" => user.auth_token }

      get v1_current_user_url, {}, auth_header

      expect(response.status).to eq 200
      expect(response).to match_response_schema("user")
    end
  end
end

参考: Validating JSON Schemas with an RSpec Matcher

Ruby JSON Schema Library

ダッシュとアンダースコア！ わかりにくい！！

json-schema vs json_schema

json-schema vs json_schema

JavaScript JSON Schema Library

弊社フロンエンドエンジニアのオススメ2つ。

JSON書くのツラい問題

  • 「閉じカッコがー!!」
  • 「カンマがー!!!!」
  • 「コメントがー!!!!!!」
  • 「クオテーションがー!!!!!!」

黙ってYAMLで書こう。 こっちのが可読性もよいしミスも少ないし書きやすいです。

JSON Schemaの今とこれから

JSON Schemaコラボでよかったこと

  • バックエンドエンジニアとフロントエンドエンジニアの仕様の共通認識
  • JSON Schemaを先に定義しておくことでバックエンドエンジニアとフロントエンドエンジニアが疎に開発できる
  • JSON Schemaでバグの混入を防ぐ

所感

時間にシビアなLT形式だったので発表途中でぶった切られた。もう少し簡潔にすべきだったかもしれない。

関連記事