PlanResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/lettance-com/json-schema/lettance-com-plan-response-schema.json",
  "title": "PlanResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lettance-com-openapi.json#/components/schemas/PlanResponse",
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/$defs/PlanResult"
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "$defs": {
    "Meta": {
      "type": "object",
      "properties": {
        "sources": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Absolute URL"
          },
          "description": "Distinct upstream sources this response draws on: legislation, GOV.UK guidance, council pages and data services."
        },
        "coverage": {
          "type": "string",
          "description": "How much of England the council licensing research covers today."
        },
        "notice": {
          "type": "string",
          "description": "How to use this answer. It is information, not legal advice."
        },
        "catalogueDate": {
          "type": "string",
          "description": "The catalogue edition this response was built from."
        },
        "links": {
          "type": "object",
          "properties": {
            "documentation": {
              "type": "string",
              "description": "Absolute URL"
            },
            "openapi": {
              "type": "string",
              "description": "Absolute URL"
            },
            "html": {
              "description": "The human page for this answer.",
              "type": "string"
            },
            "markdown": {
              "description": "The same page as Markdown, for agents.",
              "type": "string"
            }
          },
          "required": [
            "documentation",
            "openapi"
          ]
        }
      },
      "required": [
        "sources",
        "coverage",
        "notice",
        "catalogueDate",
        "links"
      ],
      "description": "Sources, coverage and links. Present on every response, including errors."
    },
    "PlanItem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The checklist item a saved home would use for the same duty, such as gas or deposit."
        },
        "title": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "action",
            "due_soon",
            "unknown",
            "upcoming",
            "ok"
          ],
          "description": "action: do it now. due_soon: due within 60 days, or before the next tenancy starts. unknown: needs an answer or a council check. upcoming: a later date or a continuing duty. ok: on track by the landlord's own answers, not checked against documents."
        },
        "date": {
          "anyOf": [
            {
              "type": "string",
              "description": "ISO date, YYYY-MM-DD"
            },
            {
              "type": "null"
            }
          ],
          "description": "The item's key date: a deadline, an expiry or the earliest new rent."
        },
        "dateLabel": {
          "description": "What the date is, such as Due by, Deadline or Earliest new rent.",
          "type": [
            "string",
            "null"
          ]
        },
        "detail": {
          "type": "string"
        },
        "basis": {
          "type": "string",
          "enum": [
            "address",
            "answers",
            "unanswered"
          ],
          "description": "address: from the postcode. answers: from the landlord's answers. unanswered: waiting for an answer."
        },
        "ongoing": {
          "type": "boolean",
          "description": "A continuing duty with no date of its own."
        },
        "otherDates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "description": "ISO date, YYYY-MM-DD"
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "date",
              "label"
            ]
          },
          "description": "Other dates for the same item, such as a register window opening."
        },
        "applyUrl": {
          "anyOf": [
            {
              "type": "string",
              "description": "Absolute URL"
            },
            {
              "type": "null"
            }
          ],
          "description": "The council's page to apply for a licence, when one is needed and not held."
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "Absolute URL"
              }
            },
            "required": [
              "id",
              "title",
              "url"
            ]
          }
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "date",
        "dateLabel",
        "detail",
        "basis",
        "ongoing",
        "otherDates",
        "applyUrl",
        "rules"
      ]
    },
    "PlanQuestion": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "parameter": {
          "type": "string",
          "description": "The query parameter that answers it on /api/v1/plan and /plan."
        },
        "argument": {
          "type": "string",
          "description": "The plan_rental MCP tool argument that answers it."
        },
        "prompt": {
          "type": "string"
        },
        "hint": {
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "type": "string",
          "enum": [
            "date",
            "choice"
          ]
        },
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The allowed values for a choice; empty for a date."
        }
      },
      "required": [
        "key",
        "parameter",
        "argument",
        "prompt",
        "hint",
        "kind",
        "options"
      ]
    },
    "PlanResult": {
      "type": "object",
      "properties": {
        "postcode": {
          "type": "string"
        },
        "ward": {
          "type": [
            "string",
            "null"
          ]
        },
        "council": {
          "type": "string"
        },
        "councilPage": {
          "anyOf": [
            {
              "type": "string",
              "description": "Absolute URL"
            },
            {
              "type": "null"
            }
          ]
        },
        "region": {
          "type": [
            "string",
            "null"
          ]
        },
        "household": {
          "type": "string",
          "enum": [
            "single",
            "small_hmo",
            "large_hmo"
          ]
        },
        "letting": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "now",
                "next"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "now: tenants live there. next: a tenancy is starting or the home is being got ready. null: not answered yet."
        },
        "asOf": {
          "type": "string",
          "description": "The London date the plan was worked out for."
        },
        "licence": {
          "type": "object",
          "properties": {
            "needed": {
              "type": "string",
              "enum": [
                "yes",
                "no",
                "check"
              ],
              "description": "check means the answer depends on something a postcode cannot settle, or the council is not researched yet. It never means no."
            },
            "summary": {
              "type": "string"
            },
            "kind": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "selective",
                    "additional",
                    "mandatory_hmo"
                  ]
                },
                {
                  "type": "null"
                }
              ],
              "description": "The kind of licence this household needs, which the licence question names."
            },
            "scheme": {
              "description": "The leading council scheme.",
              "type": [
                "string",
                "null"
              ]
            },
            "confidence": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                {
                  "type": "null"
                }
              ],
              "description": "The research confidence for the leading scheme."
            },
            "sources": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "Absolute URL"
              },
              "description": "The council sources behind every scheme matched for this household."
            },
            "openQuestions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "researched": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "ISO date, YYYY-MM-DD"
                },
                {
                  "type": "null"
                }
              ],
              "description": "When the council's licensing was researched; null if not researched yet."
            },
            "verified": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "ISO date, YYYY-MM-DD"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "needed",
            "summary",
            "kind",
            "scheme",
            "confidence",
            "sources",
            "openQuestions",
            "researched",
            "verified"
          ],
          "description": "The council research behind the licence and licensing scheme items. Keep the confidence, sources and open questions with any answer."
        },
        "summary": {
          "type": "object",
          "properties": {
            "now": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "soon": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "upcoming": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "ok": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "toAnswer": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "ongoing": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "now",
            "soon",
            "upcoming",
            "ok",
            "toAnswer",
            "ongoing"
          ]
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PlanItem"
          },
          "description": "Work first, then questions, then dates, then what is on track."
        },
        "questions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PlanQuestion"
          },
          "description": "Answers that would make the plan more exact, most useful first. Ask the landlord; never guess them."
        },
        "answers": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          },
          "description": "The answers this plan used, as query parameters."
        },
        "links": {
          "type": "object",
          "properties": {
            "plan": {
              "type": "string",
              "description": "The interactive plan page."
            },
            "api": {
              "type": "string",
              "description": "Absolute URL"
            },
            "calendar": {
              "type": "string",
              "description": "The plan's future dates as an iCalendar file."
            }
          },
          "required": [
            "plan",
            "api",
            "calendar"
          ]
        },
        "notice": {
          "type": "string"
        }
      },
      "required": [
        "postcode",
        "ward",
        "council",
        "councilPage",
        "region",
        "household",
        "letting",
        "asOf",
        "licence",
        "summary",
        "items",
        "questions",
        "answers",
        "links",
        "notice"
      ]
    }
  }
}