- 公開日
JSON Schemaについて発表しました
「JSON Schemaでバックエンドエンジニアとフロントエンドエンジニアがコラボする」と題してエムスリー x Gunosy Beer bashで発表してきました。
当日ハッシュタグ: #gunosybeer hashtag on Twitter
発表資料
2 Types of JSON 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
Rails API Repo
JSON Schema Repo
Frontend Repo
バックエンドAPIのレポジトリ、フロントエンドのJSレポジトリ、共通で使うJSON Schemaのためのレポジトリ、これら3つを用意した。
Workflow
- 必要なAPIとそこに含まれるべきデータを洗い出し
- 1をJSON Schemaに落としこむ
- プルリク!
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
- depending on
json-schema
:
json-schema vs json_schema
- depending on
json_schema
:
JavaScript JSON Schema Library
弊社フロンエンドエンジニアのオススメ2つ。
JSON書くのツラい問題
- 「閉じカッコがー!!」
- 「カンマがー!!!!」
- 「コメントがー!!!!!!」
- 「クオテーションがー!!!!!!」
黙ってYAMLで書こう。 こっちのが可読性もよいしミスも少ないし書きやすいです。
JSON Schemaの今とこれから
- JSON Schema v5 Proposalsが出されている段階
- IssueやGoogle Groupsを追うとよさげ
- v5への具体的なロードマップは引かれていない模様
JSON Schemaコラボでよかったこと
- バックエンドエンジニアとフロントエンドエンジニアの仕様の共通認識
- JSON Schemaを先に定義しておくことでバックエンドエンジニアとフロントエンドエンジニアが疎に開発できる
- JSON Schemaでバグの混入を防ぐ
所感
時間にシビアなLT形式だったので発表途中でぶった切られた。もう少し簡潔にすべきだったかもしれない。