Bug 29620: Move the OpenAPI spec to YAML format

This patch moves all the REST API spec pieces into YAML. To test: 1. Run: $ kshell k$ prove t/db_dependent/api/v1/* => SUCCESS: Tests pass 2. Apply this patch 3. Repeat 1 => SUCCESS: Tests still pass! 4. Sign off :-D Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io> Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com> Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
2 months ago · d6c67eddd3
167 changed files with 7616 additions and 10385 deletions
--- a/api/v1/swagger/definitions.json
+++ b/api/v1/swagger/definitions.json
@ -1,95 +0,0 @@
-{
-  "account_line": {
-    "$ref": "definitions/account_line.json"
-  },
-  "basket": {
-    "$ref": "definitions/basket.json"
-  },
-  "cashup": {
-    "$ref": "definitions/cashup.json"
-  },
-  "circ-rule-kind": {
-    "$ref": "definitions/circ-rule-kind.json"
-  },
-  "city": {
-    "$ref": "definitions/city.yaml"
-  },
-  "error": {
-    "$ref": "definitions/error.json"
-  },
-  "fund": {
-    "$ref": "definitions/fund.json"
-  },
-  "hold": {
-    "$ref": "definitions/hold.json"
-  },
-  "invoice": {
-    "$ref": "definitions/invoice.json"
-  },
-  "item": {
-    "$ref": "definitions/item.yaml"
-  },
-  "checkouts": {
-    "$ref": "definitions/checkouts.json"
-  },
-  "checkout": {
-    "$ref": "definitions/checkout.json"
-  },
-  "holds": {
-    "$ref": "definitions/holds.json"
-  },
-  "ill_backends": {
-    "$ref": "definitions/ill_backends.json"
-  },
-  "ill_backend": {
-    "$ref": "definitions/ill_backend.json"
-  },
-  "import_batch_profile": {
-    "$ref": "definitions/import_batch_profile.json"
-  },
-  "import_batch_profiles": {
-    "$ref": "definitions/import_batch_profiles.json"
-  },
-  "library": {
-    "$ref": "definitions/library.json"
-  },
-  "transfer_limit": {
-    "$ref": "definitions/transfer_limit.json"
-  },
-  "order": {
-    "$ref": "definitions/order.json"
-  },
-  "advancededitormacro": {
-    "$ref": "definitions/advancededitormacro.json"
-  },
-  "patron": {
-    "$ref": "definitions/patron.json"
-  },
-  "patron_account_credit": {
-    "$ref": "definitions/patron_account_credit.json"
-  },
-  "patron_balance": {
-    "$ref": "definitions/patron_balance.json"
-  },
-  "patron_extended_attribute": {
-    "$ref": "definitions/patron_extended_attribute.json"
-  },
-  "quote": {
-    "$ref": "definitions/quote.json"
-  },
-  "allows_renewal": {
-    "$ref": "definitions/allows_renewal.json"
-  },
-  "vendor": {
-    "$ref": "definitions/vendor.json"
-  },
-  "return_claim": {
-    "$ref": "definitions/return_claim.json"
-  },
-  "smtp_server": {
-    "$ref": "definitions/smtp_server.json"
-  },
-  "suggestion": {
-    "$ref": "definitions/suggestion.yaml"
-  }
-}
--- a/api/v1/swagger/definitions.yaml
+++ b/api/v1/swagger/definitions.yaml
@ -0,0 +1,63 @@
+---
+account_line:
+  $ref: definitions/account_line.yaml
+advancededitormacro:
+  $ref: definitions/advancededitormacro.yaml
+allows_renewal:
+  $ref: definitions/allows_renewal.yaml
+basket:
+  $ref: definitions/basket.yaml
+cashup:
+  $ref: definitions/cashup.yaml
+checkout:
+  $ref: definitions/checkout.yaml
+checkouts:
+  $ref: definitions/checkouts.yaml
+circ-rule-kind:
+  $ref: definitions/circ-rule-kind.yaml
+city:
+  $ref: definitions/city.yaml
+error:
+  $ref: definitions/error.yaml
+fund:
+  $ref: definitions/fund.yaml
+hold:
+  $ref: definitions/hold.yaml
+holds:
+  $ref: definitions/holds.yaml
+ill_backend:
+  $ref: definitions/ill_backend.yaml
+ill_backends:
+  $ref: definitions/ill_backends.yaml
+import_batch_profile:
+  $ref: definitions/import_batch_profile.yaml
+import_batch_profiles:
+  $ref: definitions/import_batch_profiles.yaml
+invoice:
+  $ref: definitions/invoice.yaml
+item:
+  $ref: definitions/item.yaml
+library:
+  $ref: definitions/library.yaml
+order:
+  $ref: definitions/order.yaml
+patron:
+  $ref: definitions/patron.yaml
+patron_account_credit:
+  $ref: definitions/patron_account_credit.yaml
+patron_balance:
+  $ref: definitions/patron_balance.yaml
+patron_extended_attribute:
+  $ref: definitions/patron_extended_attribute.yaml
+quote:
+  $ref: definitions/quote.yaml
+return_claim:
+  $ref: definitions/return_claim.yaml
+smtp_server:
+  $ref: definitions/smtp_server.yaml
+suggestion:
+  $ref: definitions/suggestion.yaml
+transfer_limit:
+  $ref: definitions/transfer_limit.yaml
+vendor:
+  $ref: definitions/vendor.yaml
--- a/api/v1/swagger/definitions/account_line.json
+++ b/api/v1/swagger/definitions/account_line.json
@ -1,121 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "account_line_id": {
-      "type": "integer",
-      "description": "Internal account line identifier"
-    },
-    "checkout_id": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "description": "Internal identifier for the checkout the account line is related to"
-    },
-    "patron_id": {
-      "type": "integer",
-      "description": "Internal identifier for the patron the account line belongs to"
-    },
-    "item_id": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "description": "Internal identifier for the item the account line is related to"
-    },
-    "date": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Date the account line was created"
-    },
-    "amount": {
-      "type": "number",
-      "description": "Account line amount"
-    },
-    "description": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Account line description"
-    },
-    "account_type": {
-      "type": [
-          "string",
-          "null"
-      ],
-      "description": "Account line type"
-    },
-    "debit_type": {
-      "type": [
-          "string",
-          "null"
-      ],
-      "description": "Account line debit type"
-    },
-    "credit_type": {
-      "type": [
-          "string",
-          "null"
-      ],
-      "description": "Account line credit type"
-    },
-    "payment_type": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Payment type"
-    },
-    "amount_outstanding": {
-      "type": "number",
-      "description": "Outstanding amount"
-    },
-    "last_increment": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "The amount the line was increased last time"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Timestamp for the latest line update"
-    },
-    "internal_note": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Internal note"
-    },
-    "user_id": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "description": "Internal patron identifier for the staff member that introduced the account line"
-    },
-    "library_id": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Internal identifier for the library in which the transaction took place"
-    },
-    "interface": {
-      "type": [ "string", "null" ],
-      "description": "Interface in which the account line was generated (values can be: api, cron, commandline, intranet, opac and sip)"
-    },
-    "status": {
-      "type": [ "string", "null" ],
-      "description": "The credit/debit status"
-    },
-    "cash_register_id": {
-      "type": [ "integer", "null" ],
-      "description": "Internal identifier for the cash register used for the payment (if any)"
-    }
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/account_line.yaml
+++ b/api/v1/swagger/definitions/account_line.yaml
@ -0,0 +1,96 @@
+---
+type: object
+properties:
+  account_line_id:
+    type: integer
+    description: Internal account line identifier
+  checkout_id:
+    type:
+      - integer
+      - "null"
+    description: Internal identifier for the checkout the account line is related to
+  patron_id:
+    type: integer
+    description: Internal identifier for the patron the account line belongs to
+  item_id:
+    type:
+      - integer
+      - "null"
+    description: Internal identifier for the item the account line is related to
+  date:
+    type: string
+    format: date-time
+    description: Date the account line was created
+  amount:
+    type: number
+    description: Account line amount
+  description:
+    type:
+      - string
+      - "null"
+    description: Account line description
+  account_type:
+    type:
+      - string
+      - "null"
+    description: Account line type
+  debit_type:
+    type:
+      - string
+      - "null"
+    description: Account line debit type
+  credit_type:
+    type:
+      - string
+      - "null"
+    description: Account line credit type
+  payment_type:
+    type:
+      - string
+      - "null"
+    description: Payment type
+  amount_outstanding:
+    type: number
+    description: Outstanding amount
+  last_increment:
+    type:
+      - number
+      - "null"
+    description: The amount the line was increased last time
+  timestamp:
+    type: string
+    format: date-time
+    description: Timestamp for the latest line update
+  internal_note:
+    type:
+      - string
+      - "null"
+    description: Internal note
+  user_id:
+    type:
+      - integer
+      - "null"
+    description: Internal patron identifier for the staff member that introduced the
+      account line
+  library_id:
+    type:
+      - string
+      - "null"
+    description: Internal identifier for the library in which the transaction took place
+  interface:
+    type:
+      - string
+      - "null"
+    description: "Interface in which the account line was generated (values can be: api,
+      cron, commandline, intranet, opac and sip)"
+  status:
+    type:
+      - string
+      - "null"
+    description: The credit/debit status
+  cash_register_id:
+    type:
+      - integer
+      - "null"
+    description: Internal identifier for the cash register used for the payment (if any)
+additionalProperties: false
--- a/api/v1/swagger/definitions/advancededitormacro.json
+++ b/api/v1/swagger/definitions/advancededitormacro.json
@ -1,26 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "macro_id": {
-      "$ref": "../x-primitives.json#/advancededitormacro_id"
-    },
-    "name": {
-      "description": "macro name",
-      "type": "string"
-    },
-    "macro_text": {
-      "description": "macro text",
-      "type": ["string", "null"]
-    },
-    "patron_id": {
-      "description": "borrower number",
-      "type": ["integer", "null"]
-    },
-    "shared": {
-        "description": "is macro shared",
-        "type": ["boolean", "null"]
-    }
-  },
-  "additionalProperties": false,
-  "required": ["name", "macro_text", "patron_id", "shared"]
-}
--- a/api/v1/swagger/definitions/advancededitormacro.yaml
+++ b/api/v1/swagger/definitions/advancededitormacro.yaml
@ -0,0 +1,29 @@
+---
+type: object
+properties:
+  macro_id:
+    $ref: ../x-primitives.yaml#/advancededitormacro_id
+  name:
+    description: macro name
+    type: string
+  macro_text:
+    description: macro text
+    type:
+      - string
+      - "null"
+  patron_id:
+    description: borrower number
+    type:
+      - integer
+      - "null"
+  shared:
+    description: is macro shared
+    type:
+      - boolean
+      - "null"
+additionalProperties: false
+required:
+  - name
+  - macro_text
+  - patron_id
+  - shared
--- a/api/v1/swagger/definitions/allows_renewal.json
+++ b/api/v1/swagger/definitions/allows_renewal.json
@ -1,26 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "allows_renewal": {
-      "type": "boolean",
-      "description": "Renewability status; true = renewable, false = not renewable"
-    },
-    "max_renewals": {
-      "type": "integer",
-      "description": "Maximum number of possible renewals"
-    },
-     "current_renewals": {
-      "type": "integer",
-      "description": "Current used renewals"
-    },
-     "unseen_renewals": {
-      "type": "integer",
-      "description": "Number of consecutive times the item was renewed without being seen"
-    },
-    "error": {
-      "type": ["string", "null"],
-      "description": "Description on false allows_renewal."
-    }
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/allows_renewal.yaml
+++ b/api/v1/swagger/definitions/allows_renewal.yaml
@ -0,0 +1,21 @@
+---
+type: object
+properties:
+  allows_renewal:
+    type: boolean
+    description: Renewability status; true = renewable, false = not renewable
+  max_renewals:
+    type: integer
+    description: Maximum number of possible renewals
+  current_renewals:
+    type: integer
+    description: Current used renewals
+  unseen_renewals:
+    type: integer
+    description: Number of consecutive times the item was renewed without being seen
+  error:
+    type:
+      - string
+      - "null"
+    description: Description on false allows_renewal.
+additionalProperties: false
--- a/api/v1/swagger/definitions/basket.json
+++ b/api/v1/swagger/definitions/basket.json
@ -1,100 +0,0 @@
-{
-    "type": "object",
-    "properties": {
-        "basket_id": {
-            "type": "integer",
-            "description": "Internal identifier for the basket"
-        },
-        "name": {
-            "type": "string",
-            "description": "Basket name"
-        },
-        "internal_note": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "Internal note"
-        },
-        "vendor_note": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "Vendor note"
-        },
-        "contract_id": {
-            "type": "integer",
-            "description": "Internal identifier of the linked contract"
-        },
-        "creation_date": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "format": "date",
-            "description": "The date the basket was created"
-        },
-        "close_date": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "format": "date",
-            "description": "The date the basket was closed"
-        },
-        "vendor_id": {
-            "type": "integer",
-            "description": "Internal identifier for the vendor"
-        },
-        "authorised_by": {
-            "type": [
-                "integer",
-                "null"
-            ],
-            "description": "Internal patron identifier of the basket creator"
-        },
-        "basket_group_id": {
-            "type": [
-                "integer",
-                "null"
-            ],
-            "description": "links this basket to its group (aqbasketgroups.id)"
-        },
-        "delivery_library": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "basket delivery place"
-        },
-        "billing_library": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "basket billing place"
-        },
-        "library_id": {
-            "type": [
-                "integer",
-                "null"
-            ],
-            "description": "Library the basket belongs to"
-        },
-        "standing": {
-            "type": "boolean",
-            "description": "If the orders in this basket are standing"
-        },
-        "create_items": {
-            "type": "string",
-            "enum": [
-                "ordering",
-                "receiving",
-                "cataloguing"
-            ],
-            "description": "When items should be created for orders in this basket (Options: 'ordering', 'receiving', 'cataloguing'. Null means system wide config)"
-        }
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/basket.yaml
+++ b/api/v1/swagger/definitions/basket.yaml
@ -0,0 +1,74 @@
+---
+type: object
+properties:
+  basket_id:
+    type: integer
+    description: Internal identifier for the basket
+  name:
+    type: string
+    description: Basket name
+  internal_note:
+    type:
+      - string
+      - "null"
+    description: Internal note
+  vendor_note:
+    type:
+      - string
+      - "null"
+    description: Vendor note
+  contract_id:
+    type: integer
+    description: Internal identifier of the linked contract
+  creation_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the basket was created
+  close_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the basket was closed
+  vendor_id:
+    type: integer
+    description: Internal identifier for the vendor
+  authorised_by:
+    type:
+      - integer
+      - "null"
+    description: Internal patron identifier of the basket creator
+  basket_group_id:
+    type:
+      - integer
+      - "null"
+    description: links this basket to its group (aqbasketgroups.id)
+  delivery_library:
+    type:
+      - string
+      - "null"
+    description: basket delivery place
+  billing_library:
+    type:
+      - string
+      - "null"
+    description: basket billing place
+  library_id:
+    type:
+      - integer
+      - "null"
+    description: Library the basket belongs to
+  standing:
+    type: boolean
+    description: If the orders in this basket are standing
+  create_items:
+    type: string
+    enum:
+      - ordering
+      - receiving
+      - cataloguing
+    description: "When items should be created for orders in this basket (Options:
+      'ordering', 'receiving', 'cataloguing'. Null means system wide config)"
+additionalProperties: false
--- a/api/v1/swagger/definitions/cashup.json
+++ b/api/v1/swagger/definitions/cashup.json
@ -1,38 +0,0 @@
-{
-    "type": "object",
-    "properties": {
-        "cashup_id": {
-            "type": "integer",
-            "description": "Internal cashup identifier"
-        },
-        "cash_register_id": {
-            "type": "integer",
-            "description": "Internal identifier for the register the cashup belongs to"
-        },
-        "manager_id": {
-            "type": "integer",
-            "description": "Internal identifier for the manager the cashup was performed by"
-        },
-        "manager": {
-            "type": [
-                "object",
-                "null"
-            ],
-            "description": "The object representing the manager the cashup was performed by"
-        },
-        "amount": {
-            "type": "number",
-            "description": "Account line amount"
-        },
-        "timestamp": {
-            "type": "string",
-            "format": "date-time",
-            "description": "Timestamp for the latest line update"
-        },
-        "summary": {
-            "type": "object",
-            "description": "A summary of the cashup action"
-        }
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/cashup.yaml
+++ b/api/v1/swagger/definitions/cashup.yaml
@ -0,0 +1,28 @@
+---
+type: object
+properties:
+  cashup_id:
+    type: integer
+    description: Internal cashup identifier
+  cash_register_id:
+    type: integer
+    description: Internal identifier for the register the cashup belongs to
+  manager_id:
+    type: integer
+    description: Internal identifier for the manager the cashup was performed by
+  manager:
+    type:
+      - object
+      - "null"
+    description: The object representing the manager the cashup was performed by
+  amount:
+    type: number
+    description: Account line amount
+  timestamp:
+    type: string
+    format: date-time
+    description: Timestamp for the latest line update
+  summary:
+    type: object
+    description: A summary of the cashup action
+additionalProperties: false
--- a/api/v1/swagger/definitions/checkout.json
+++ b/api/v1/swagger/definitions/checkout.json
@ -1,110 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "checkout_id": {
-      "type": "integer",
-      "description": "internally assigned checkout identifier"
-    },
-    "patron_id": {
-      "$ref": "../x-primitives.json#/patron_id"
-    },
-    "item_id": {
-      "type": "integer",
-      "description": "internal identifier of checked out item"
-    },
-    "due_date": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Due date"
-    },
-    "library_id": {
-      "type": ["string", "null"],
-      "description": "code of the library the item was checked out"
-    },
-    "issuer_id": {
-      "type": [ "integer", "null" ],
-      "description": "internally assigned for the user that processed the checkout"
-    },
-    "checkin_date": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Date the item was returned"
-    },
-    "last_renewed_date": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Date the item was last renewed"
-    },
-    "renewals": {
-      "type": ["integer", "null"],
-      "description": "Number of renewals"
-    },
-    "unseen_renewals": {
-      "type": ["integer", "null"],
-      "description": "Number of consecutive unseen renewals"
-    },
-    "auto_renew": {
-      "type": "boolean",
-      "description": "Auto renewal"
-    },
-    "auto_renew_error": {
-      "type": ["string", "null"],
-      "description": "Auto renewal error"
-    },
-    "timestamp": {
-      "type": "string",
-      "description": "Last update time"
-    },
-    "checkout_date": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Date the item was issued"
-    },
-    "onsite_checkout": {
-      "type": "boolean",
-      "description": "On site checkout"
-    },
-    "note": {
-      "type": ["string", "null"],
-      "description": "Issue note text"
-    },
-    "note_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "Datetime of the issue note"
-    },
-    "note_seen": {
-      "type": ["boolean", "null"],
-      "description": "has the note been seen already"
-    },
-    "issuer": {
-      "type": [
-          "object",
-          "null"
-      ],
-      "description": "The object representing the checkout issuer"
-    },
-    "item": {
-      "type": [
-          "object",
-          "null"
-      ],
-      "description": "The object representing the checked out item"
-    },
-    "library": {
-      "type": [
-          "object",
-          "null"
-      ],
-      "description": "The object representing the checkout library"
-    },
-    "patron": {
-      "type": [
-          "object",
-          "null"
-      ],
-      "description": "The object representing the checkout patron"
-    }
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/checkout.yaml
+++ b/api/v1/swagger/definitions/checkout.yaml
@ -0,0 +1,102 @@
+---
+type: object
+properties:
+  checkout_id:
+    type: integer
+    description: internally assigned checkout identifier
+  patron_id:
+    $ref: ../x-primitives.yaml#/patron_id
+  item_id:
+    type: integer
+    description: internal identifier of checked out item
+  due_date:
+    type: string
+    format: date-time
+    description: Due date
+  library_id:
+    type:
+      - string
+      - "null"
+    description: code of the library the item was checked out
+  issuer_id:
+    type:
+      - integer
+      - "null"
+    description: internally assigned for the user that processed the checkout
+  checkin_date:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: Date the item was returned
+  last_renewed_date:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: Date the item was last renewed
+  renewals:
+    type:
+      - integer
+      - "null"
+    description: Number of renewals
+  unseen_renewals:
+    type:
+      - integer
+      - "null"
+    description: Number of consecutive unseen renewals
+  auto_renew:
+    type: boolean
+    description: Auto renewal
+  auto_renew_error:
+    type:
+      - string
+      - "null"
+    description: Auto renewal error
+  timestamp:
+    type: string
+    description: Last update time
+  checkout_date:
+    type: string
+    format: date-time
+    description: Date the item was issued
+  onsite_checkout:
+    type: boolean
+    description: On site checkout
+  note:
+    type:
+      - string
+      - "null"
+    description: Issue note text
+  note_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: Datetime of the issue note
+  note_seen:
+    type:
+      - boolean
+      - "null"
+    description: has the note been seen already
+  issuer:
+    type:
+      - object
+      - "null"
+    description: The object representing the checkout issuer
+  item:
+    type:
+      - object
+      - "null"
+    description: The object representing the checked out item
+  library:
+    type:
+      - object
+      - "null"
+    description: The object representing the checkout library
+  patron:
+    type:
+      - object
+      - "null"
+    description: The object representing the checkout patron
+additionalProperties: false
--- a/api/v1/swagger/definitions/checkouts.json
+++ b/api/v1/swagger/definitions/checkouts.json
@ -1,7 +0,0 @@
-{
-  "type": "array",
-  "items": {
-    "$ref": "checkout.json"
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/checkouts.yaml
+++ b/api/v1/swagger/definitions/checkouts.yaml
@ -0,0 +1,5 @@
+---
+type: array
+items:
+  $ref: checkout.yaml
+additionalProperties: false
--- a/api/v1/swagger/definitions/circ-rule-kind.json
+++ b/api/v1/swagger/definitions/circ-rule-kind.json
@ -1,15 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "scope": {
-      "description": "levels that this rule kind can be set for",
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [ "branchcode", "categorycode", "itemtype" ]
-      }
-    }
-  },
-  "additionalProperties": false,
-  "required": ["scope"]
-}
--- a/api/v1/swagger/definitions/circ-rule-kind.yaml
+++ b/api/v1/swagger/definitions/circ-rule-kind.yaml
@ -0,0 +1,15 @@
+---
+type: object
+properties:
+  scope:
+    description: levels that this rule kind can be set for
+    type: array
+    items:
+      type: string
+      enum:
+        - branchcode
+        - categorycode
+        - itemtype
+additionalProperties: false
+required:
+  - scope
--- a/api/v1/swagger/definitions/city.yaml
+++ b/api/v1/swagger/definitions/city.yaml
@ -2,7 +2,7 @@
 type: object
 properties:
  city_id:
-    $ref: ../x-primitives.json#/city_id
+    $ref: ../x-primitives.yaml#/city_id
  name:
    description: city name
    type: string
--- a/api/v1/swagger/definitions/club_hold.json
+++ b/api/v1/swagger/definitions/club_hold.json
@ -1,27 +0,0 @@
-{
-    "type": "object",
-    "properties": {
-      "club_hold_id": {
-        "type": "integer",
-        "description": "Internal club hold identifier"
-      },
-      "club_id": {
-        "type": "integer",
-        "description": "Internal club identifier"
-      },
-      "biblio_id": {
-        "type": "integer",
-        "description": "Internal biblio identifier"
-      },
-      "item_id": {
-        "type": ["string", "null"],
-        "description": "Internal item identifier"
-      },
-      "date_created": {
-        "type": "string",
-        "format": "date-time",
-        "description": "Date and time the hold was created"
-      }
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/club_hold.yaml
+++ b/api/v1/swagger/definitions/club_hold.yaml
@ -0,0 +1,22 @@
+---
+type: object
+properties:
+  club_hold_id:
+    type: integer
+    description: Internal club hold identifier
+  club_id:
+    type: integer
+    description: Internal club identifier
+  biblio_id:
+    type: integer
+    description: Internal biblio identifier
+  item_id:
+    type:
+      - string
+      - "null"
+    description: Internal item identifier
+  date_created:
+    type: string
+    format: date-time
+    description: Date and time the hold was created
+additionalProperties: false
--- a/api/v1/swagger/definitions/club_hold_patron_hold.json
+++ b/api/v1/swagger/definitions/club_hold_patron_hold.json
@ -1,31 +0,0 @@
-{
-    "type": "object",
-    "properties": {
-      "club_hold_patron_hold_id": {
-        "type": "integer",
-        "description": "Internal club hold to patron hold identifier"
-      },
-      "club_hold_id": {
-        "type": "integer",
-        "description": "Internal club hold identifier"
-      },
-      "hold_id": {
-        "type": ["integer", "null"],
-        "description": "Internal hold identifier"
-      },
-      "patron_id": {
-        "type": "integer",
-        "description": "Internal patron identifier"
-      },
-      "error_code": {
-        "type": ["string", "null"],
-        "format": "date",
-        "description": "Code returned by CanItemBeReserved"
-      },
-      "error_message": {
-        "type": ["string", "null"],
-        "description": "Generic error message"
-      }
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/club_hold_patron_hold.yaml
+++ b/api/v1/swagger/definitions/club_hold_patron_hold.yaml
@ -0,0 +1,29 @@
+---
+type: object
+properties:
+  club_hold_patron_hold_id:
+    type: integer
+    description: Internal club hold to patron hold identifier
+  club_hold_id:
+    type: integer
+    description: Internal club hold identifier
+  hold_id:
+    type:
+      - integer
+      - "null"
+    description: Internal hold identifier
+  patron_id:
+    type: integer
+    description: Internal patron identifier
+  error_code:
+    type:
+      - string
+      - "null"
+    format: date
+    description: Code returned by CanItemBeReserved
+  error_message:
+    type:
+      - string
+      - "null"
+    description: Generic error message
+additionalProperties: false
--- a/api/v1/swagger/definitions/club_hold_patron_holds.json
+++ b/api/v1/swagger/definitions/club_hold_patron_holds.json
@ -1,7 +0,0 @@
-{
-    "type": "array",
-    "items": {
-      "$ref": "club_hold_patron_hold.json"
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/club_hold_patron_holds.yaml
+++ b/api/v1/swagger/definitions/club_hold_patron_holds.yaml
@ -0,0 +1,5 @@
+---
+type: array
+items:
+  $ref: club_hold_patron_hold.yaml
+additionalProperties: false
--- a/api/v1/swagger/definitions/club_holds.json
+++ b/api/v1/swagger/definitions/club_holds.json
@ -1,7 +0,0 @@
-{
-    "type": "array",
-    "items": {
-      "$ref": "club_hold.json"
-    },
-    "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/club_holds.yaml
+++ b/api/v1/swagger/definitions/club_holds.yaml
@ -0,0 +1,5 @@
+---
+type: array
+items:
+  $ref: club_hold.yaml
+additionalProperties: false
--- a/api/v1/swagger/definitions/error.json
+++ b/api/v1/swagger/definitions/error.json
@ -1,10 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "error": {
-      "description": "Error message",
-      "type": "string"
-    }
-  },
-  "additionalProperties": true
-}
--- a/api/v1/swagger/definitions/error.yaml
+++ b/api/v1/swagger/definitions/error.yaml
@ -0,0 +1,7 @@
+---
+type: object
+properties:
+  error:
+    description: Error message
+    type: string
+additionalProperties: true
--- a/api/v1/swagger/definitions/fund.json
+++ b/api/v1/swagger/definitions/fund.json
@ -1,105 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "fund_id": {
-      "$ref": "../x-primitives.json#/fund_id"
-    },
-    "code": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Code assigned to the fund by the user"
-    },
-    "name": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Name assigned to the fund by the user"
-    },
-    "library_id": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Internal identifier for the library that this fund belongs to"
-    },
-    "total_amount": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Total amount for this fund"
-    },
-    "warn_at_percentage": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Warning at percentage"
-    },
-    "warn_at_amount": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Warning at amount"
-    },
-    "notes": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Notes related to this fund"
-    },
-    "budget_id": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Internal identifier for the budget"
-    },
-    "timestamp": {
-      "type": [
-        "string"
-      ],
-      "format": "date-time",
-      "description": "Timestamp"
-    },
-    "fund_owner_id": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Internal identifier for the fund owner"
-    },
-    "fund_access": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "description": "Level of permission for this fund (1: owner, 2: owner, users and library, 3: owner and users)"
-    },
-    "parent_fund_id": {
-        "type": [ "integer", "null" ],
-        "description": "Internal identifier for parent fund"
-    },
-    "statistic1_auth_value_category": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Statistical category for this fund"
-    },
-    "statistic2_auth_value_category": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Second statistical category for this fund"
-    }
-  },
-  "additionalProperties": false,
-  "required": ["name"]
-}
--- a/api/v1/swagger/definitions/fund.yaml
+++ b/api/v1/swagger/definitions/fund.yaml
@ -0,0 +1,79 @@
+---
+type: object
+properties:
+  fund_id:
+    $ref: ../x-primitives.yaml#/fund_id
+  code:
+    type:
+      - string
+      - "null"
+    description: Code assigned to the fund by the user
+  name:
+    type:
+      - string
+      - "null"
+    description: Name assigned to the fund by the user
+  library_id:
+    type:
+      - string
+      - "null"
+    description: Internal identifier for the library that this fund belongs to
+  total_amount:
+    type:
+      - number
+      - "null"
+    description: Total amount for this fund
+  warn_at_percentage:
+    type:
+      - number
+      - "null"
+    description: Warning at percentage
+  warn_at_amount:
+    type:
+      - number
+      - "null"
+    description: Warning at amount
+  notes:
+    type:
+      - string
+      - "null"
+    description: Notes related to this fund
+  budget_id:
+    type:
+      - number
+      - "null"
+    description: Internal identifier for the budget
+  timestamp:
+    type:
+      - string
+    format: date-time
+    description: Timestamp
+  fund_owner_id:
+    type:
+      - number
+      - "null"
+    description: Internal identifier for the fund owner
+  fund_access:
+    type:
+      - number
+      - "null"
+    description: "Level of permission for this fund (1: owner, 2: owner, users and library,
+      3: owner and users)"
+  parent_fund_id:
+    type:
+      - integer
+      - "null"
+    description: Internal identifier for parent fund
+  statistic1_auth_value_category:
+    type:
+      - string
+      - "null"
+    description: Statistical category for this fund
+  statistic2_auth_value_category:
+    type:
+      - string
+      - "null"
+    description: Second statistical category for this fund
+additionalProperties: false
+required:
+  - name
--- a/api/v1/swagger/definitions/hold.json
+++ b/api/v1/swagger/definitions/hold.json
@ -1,96 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "hold_id": {
-      "type": "integer",
-      "description": "Internal hold identifier"
-    },
-    "patron_id": {
-      "type": "integer",
-      "description": "Internal patron identifier"
-    },
-    "hold_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the hold was placed"
-    },
-    "biblio_id": {
-      "type": "integer",
-      "description": "Internal biblio identifier"
-    },
-    "pickup_library_id": {
-      "type": ["string", "null"],
-      "description": "Internal library identifier for the pickup library"
-    },
-    "desk_id": {
-      "type": ["integer", "null"],
-      "description": "The id of the desk"
-    },
-    "cancellation_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the hold was cancelled"
-    },
-    "cancellation_reason": {
-      "type": ["string", "null"],
-      "description": "The reason the hold was cancelled"
-    },
-    "notes": {
-      "type": ["string", "null"],
-      "description": "Notes related to this hold"
-    },
-    "priority": {
-      "type": ["integer", "null"],
-      "description": "Where in the queue the patron sits"
-    },
-    "status": {
-      "type": ["string", "null"],
-      "description": "A one letter code defining what the status of the hold is after it has been confirmed"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Timestamp for the latest hold update"
-    },
-    "item_id": {
-      "type": ["string", "null"],
-      "description": "Internal item identifier"
-    },
-    "waiting_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the item was marked as waiting for the patron at the library"
-    },
-    "expiration_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the hold expires"
-    },
-    "lowest_priority": {
-      "type": "boolean",
-      "description": "Controls if the hold is given the lowest priority on the queue"
-    },
-    "suspended": {
-      "type": "boolean",
-      "description": "Controls if the hold is suspended"
-    },
-    "suspended_until": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Date until which the hold has been suspended"
-    },
-    "non_priority": {
-      "description": "Set this hold as non priority",
-      "type": "boolean"
-    },
-    "item_type": {
-      "type": ["string", "null"],
-      "description": "If record level hold, the optional itemtype of the item the patron is requesting"
-    },
-    "item_level": {
-      "type": "boolean",
-      "description": "If the hold is placed at item level"
-    }
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/hold.yaml
+++ b/api/v1/swagger/definitions/hold.yaml
@ -0,0 +1,101 @@
+---
+type: object
+properties:
+  hold_id:
+    type: integer
+    description: Internal hold identifier
+  patron_id:
+    type: integer
+    description: Internal patron identifier
+  hold_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the hold was placed
+  biblio_id:
+    type: integer
+    description: Internal biblio identifier
+  pickup_library_id:
+    type:
+      - string
+      - "null"
+    description: Internal library identifier for the pickup library
+  desk_id:
+    type:
+      - integer
+      - "null"
+    description: The id of the desk
+  cancellation_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the hold was cancelled
+  cancellation_reason:
+    type:
+      - string
+      - "null"
+    description: The reason the hold was cancelled
+  notes:
+    type:
+      - string
+      - "null"
+    description: Notes related to this hold
+  priority:
+    type:
+      - integer
+      - "null"
+    description: Where in the queue the patron sits
+  status:
+    type:
+      - string
+      - "null"
+    description: A one letter code defining what the status of the hold is after it has
+      been confirmed
+  timestamp:
+    type: string
+    format: date-time
+    description: Timestamp for the latest hold update
+  item_id:
+    type:
+      - string
+      - "null"
+    description: Internal item identifier
+  waiting_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the item was marked as waiting for the patron at the library
+  expiration_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the hold expires
+  lowest_priority:
+    type: boolean
+    description: Controls if the hold is given the lowest priority on the queue
+  suspended:
+    type: boolean
+    description: Controls if the hold is suspended
+  suspended_until:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: Date until which the hold has been suspended
+  non_priority:
+    description: Set this hold as non priority
+    type: boolean
+  item_type:
+    type:
+      - string
+      - "null"
+    description: If record level hold, the optional itemtype of the item the patron is
+      requesting
+  item_level:
+    type: boolean
+    description: If the hold is placed at item level
+additionalProperties: false
--- a/api/v1/swagger/definitions/holds.json
+++ b/api/v1/swagger/definitions/holds.json
@ -1,7 +0,0 @@
-{
-  "type": "array",
-  "items": {
-    "$ref": "hold.json"
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/holds.yaml
+++ b/api/v1/swagger/definitions/holds.yaml
@ -0,0 +1,5 @@
+---
+type: array
+items:
+  $ref: hold.yaml
+additionalProperties: false
--- a/api/v1/swagger/definitions/ill_backend.json
+++ b/api/v1/swagger/definitions/ill_backend.json
@ -1,14 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "ill_backend_id": {
-      "type": "string",
-      "description": "Internal ILL backend identifier"
-    },
-    "capabilities": {
-      "type": "object",
-      "description": "List of capabilities"
-    }
-  },
-  "additionalProperties": false
-}
--- a/api/v1/swagger/definitions/ill_backend.yaml
+++ b/api/v1/swagger/definitions/ill_backend.yaml
@ -0,0 +1,10 @@
+---
+type: object
+properties:
+  ill_backend_id:
+    type: string
+    description: Internal ILL backend identifier
+  capabilities:
+    type: object
+    description: List of capabilities
+additionalProperties: false
--- a/api/v1/swagger/definitions/ill_backends.json
+++ b/api/v1/swagger/definitions/ill_backends.json
@ -1,7 +0,0 @@
-{
-  "type": "array",
-  "items": {
-    "$ref": "ill_backend.json"