読者です 読者をやめる 読者になる 読者になる

JSON Schemaの書き方がわからないので調べた件について

現在RailsAPIサーバを開発しております。
WebでAPI開発について色々調べた結果、API開発にあたりJSON Schemaと言うものを設計しておくと色々捗るようなのですが、
初見では書き方・読み方がいまいちわからなかったので少しは読み書きできる程度に調べてみました。
なおyamljsonと混在してますが、僕はyamlで書く予定のためそうなってます。あしからず。

また、自分なりの解釈のため間違っている箇所が多々あると思いますが、やんわり教えてもらえると助かります。

公式 json-schema.org


- 最初に書くヘッダ的な数行 - idはこのリソースのURI

id: http://some.site.somewhere/entry-schema#
"$schema": http://json-schema.org/draft-04/hyper-schema
title: Product
description: A product from Acme's catalog
type: object
properties:


- typeがarrayの場合、次にitemsが続く

type: array
items:
  type: string


- itemsは下記のような要素を持てる(ここで全て網羅してません)

title:
type:
properties:


- typeがobjectの場合、次にpropertiesが続く

dimesions:
  type: object
    properties:
      length:
        type: number


- propertiesの後は任意の変数名が続く
- properties内はtypeがほぼ必須
- description:で説明が追加できる
- minimum: 0などの制約が追加できる

properties:
  options:
    description: about this option
    type: array
    minItems: 1
    items:
      type: string
    uniqueItems: true


- $ref:schema内の該当箇所を参照する
- required:で必須プロパティを指定できる
- oneOf: スキーマの配列であり、インスタンスはこれらのスキーマのうちの1つに対して有効である場合にのみ有効
- definitions: スキーマで使用されるインラインサブスキーマを定義できる標準化されたプレースホルダ

{
    "id": "http://some.site.somewhere/entry-schema#",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "schema for an fstab entry",
    "type": "object",
    "required": [ "storage" ],
    "properties": {
        "storage": {
            "type": "object",
            "oneOf": [
                { "$ref": "#/definitions/diskDevice" },
                { "$ref": "#/definitions/diskUUID" },
                { "$ref": "#/definitions/nfs" },
                { "$ref": "#/definitions/tmpfs" }
            ]
        }
    },
    "definitions": {
        "diskDevice": {},
        "diskUUID": {},
        "nfs": {},
        "tmpfs": {}
    }
}