{
  "openapi": "3.1.0",
  "info": {
    "title": "The Pet Docket product dataset",
    "version": "1.1.0",
    "summary": "Independent review site for smart pet hardware. Every specification, price and owner complaint record carries a source URL and the date it was observed.",
    "license": {
      "name": "Attribution required"
    }
  },
  "servers": [
    {
      "url": "https://thepetdocket.com"
    }
  ],
  "paths": {
    "/api/catalog.json": {
      "get": {
        "operationId": "getCatalog",
        "summary": "The full product dataset.",
        "parameters": [
          {
            "name": "cluster",
            "in": "query",
            "required": false,
            "description": "Filter to one cluster.",
            "schema": {
              "type": "string",
              "enum": [
                "smart-litter-box",
                "automatic-feeder",
                "water-fountain",
                "indoor-potty"
              ]
            }
          },
          {
            "name": "species",
            "in": "query",
            "required": false,
            "description": "Only the records the maker sells for this animal. A record can be sold for both.",
            "schema": {
              "type": "string",
              "enum": [
                "cat",
                "dog"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Return a single record by its stable identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A dataset object containing an items array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "400": {
            "description": "A parameter was supplied with an invalid value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cluster/{cluster}.json": {
      "get": {
        "operationId": "getCluster",
        "summary": "Every record in one cluster, as a file. The same answer the query string returns where a function evaluates it.",
        "parameters": [
          {
            "name": "cluster",
            "in": "path",
            "required": true,
            "description": "One cluster identifier.",
            "schema": {
              "type": "string",
              "enum": [
                "smart-litter-box",
                "automatic-feeder",
                "water-fountain",
                "indoor-potty"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A dataset object containing an items array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/species/{species}.json": {
      "get": {
        "operationId": "getSpecies",
        "summary": "Every record sold for one animal, as a file.",
        "parameters": [
          {
            "name": "species",
            "in": "path",
            "required": true,
            "description": "cat or dog.",
            "schema": {
              "type": "string",
              "enum": [
                "cat",
                "dog"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A dataset object containing an items array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/items/{id}.json": {
      "get": {
        "operationId": "getProduct",
        "summary": "One product record by its stable identifier.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The stable record identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A single product record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "No record has that identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness and dataset version.",
        "responses": {
          "200": {
            "description": "The service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "id",
          "cluster",
          "brand",
          "model",
          "url",
          "sourceUrl",
          "observedOn"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable identifier. The join key across every representation."
          },
          "cluster": {
            "type": "string",
            "enum": [
              "smart-litter-box",
              "automatic-feeder",
              "water-fountain",
              "indoor-potty"
            ]
          },
          "brand": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Path of the human-readable page for this record."
          },
          "design": {
            "type": "string"
          },
          "priceUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Observed list price in USD. Null when no dated price was found."
          },
          "priceLowUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "priceHighUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "priceSource": {
            "type": "string"
          },
          "priceObservedOn": {
            "type": "string",
            "format": "date"
          },
          "priceVerification": {
            "type": [
              "string",
              "null"
            ]
          },
          "wasteBinL": {
            "type": [
              "number",
              "null"
            ]
          },
          "interiorL": {
            "type": [
              "number",
              "null"
            ]
          },
          "catWeightMinLb": {
            "type": [
              "number",
              "null"
            ]
          },
          "catWeightMaxLb": {
            "type": [
              "number",
              "null"
            ]
          },
          "maxCats": {
            "type": [
              "number",
              "null"
            ]
          },
          "entryHeightIn": {
            "type": [
              "number",
              "null"
            ]
          },
          "noiseDb": {
            "type": [
              "number",
              "null"
            ]
          },
          "wifiBands": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "warrantyMonths": {
            "type": [
              "number",
              "null"
            ]
          },
          "capacityL": {
            "type": [
              "number",
              "null"
            ]
          },
          "capacityCups": {
            "type": [
              "number",
              "null"
            ]
          },
          "mealsPerDay": {
            "type": [
              "number",
              "null"
            ]
          },
          "portionsPerMeal": {
            "type": [
              "number",
              "null"
            ]
          },
          "wetFood": {
            "type": "boolean"
          },
          "strengths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tradeoffs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "documentedComplaints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sourceUrl": {
            "type": "string",
            "description": "Where the specification was read."
          },
          "sourceLabel": {
            "type": "string"
          },
          "observedOn": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Catalog": {
        "type": "object",
        "required": [
          "meta",
          "clusters",
          "items"
        ],
        "properties": {
          "meta": {
            "type": "object"
          },
          "clusters": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "status",
          "datasetVersion"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "datasetVersion": {
            "type": "string"
          },
          "observedOn": {
            "type": "string",
            "format": "date"
          },
          "itemCount": {
            "type": "integer"
          }
        }
      }
    }
  }
}