API Blueprint(aglio)で、生成されたSchemaのarrayにitemsがない

tl;dr

arrayにしたプロパティにfixed-typeオプションをつける。

- + books: (array[Book])
+ + books: (array[Book], fixed-type) 

公式にしっかり書いてありますね。無駄にGithubとか調べてしまった。。

何が起きたの？

API BlueprintでAPIドキュメントを作成していたときに、どうにもarrayの中身がドキュメント化されない事が気持ち悪くなったので調べてみた。

例えば。次のドキュメントだとこのように変換される。

input.apib

+ Response 200 (application/json)
    + Attributes
        + books (array[object])
            + (object)
                + name: ほんのなまえ (string, required) - 書籍名
                + cost: 50 (number, required) - 価格

Body

{
  "books": [
    {
      "name": "ほんのなまえ",
      "cost": 50
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "books": {
      "type": "array"
    }
  }
}

Bodyはまぁ良いが、Schemaはあまり意味をなさなくなってしまう（折角input.apibで定義した意味が・・・）ので、ここにitemsプロパティをどうにか入れられないかという話。

答えは前にも書いたとおり、arrayにしたプロパティにfixed-typeをつける。

input.apib

 + Response 200 (application/json)
     + Attributes
-        + books (array[object])
+        + books (array[object], fixed-type)
             + (object)
                 + name: ほんのなまえ (string, required) - 書籍名
                 + cost: 50 (number, required) - 価格

Body

{
  "books": [
    {
      "name": "ほんのなまえ",
      "cost": 50
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "書籍名"
          },
          "cost": {
            "type": "number",
            "description": "価格"
          }
        },
        "required": [
          "name",
          "cost"
        ]
      }
    }
  }
}

ちゃんと出力されるようになりました。

参考URL

4.3 Nested Member Type - MSON Specification | API Blueprint
Arrays in JSONSchema do not contain `items` field · Issue #243 · danielgtaylor/aglio - Github

Githubのissuesを見てから、公式資料に載っているのを見つけました。
それにしても、なんでデフォルトではないんでしょうか。皆さんそんなに気にならないのかな。。