@planning-inspectorate/data-model 1.11.0

package/pins_data_model/models/model_pins_inspector.py

@@ -0,0 +1,53 @@
+# generated by datamodel-codegen:
+#   filename:  pins-inspector.schema.json
+#   timestamp: 2025-07-16T14:06:09+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PinsInspector(BaseModel):
+    """
+    Inspector attributes as per Horizon. This will be extended with SAP/Entra data
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    horizonId: str
+    """
+    The PINS-generated unique horizon ID
+    """
+    firstName: str
+    """
+    The first name of the inspector
+    """
+    lastName: str
+    """
+    The last name of the inspector
+    """
+    postName: str | None = None
+    """
+    The post name of the inspector
+    """
+    organisationName: str | None = None
+    """
+    The organisation name of the inspector
+    """
+    title: str | None = None
+    """
+    The title of the inspector
+    """
+    salutation: str | None = None
+    """
+    The salutation of the inspector
+    """
+    qualifications: str | None = None
+    """
+    The qualifications of the inspector
+    """
+    email: str | None = None
+    """
+    The email address of the inspector
+    """

package/pins_data_model/models/model_pins_lpa.py

@@ -0,0 +1,69 @@
+# generated by datamodel-codegen:
+#   filename:  pins-lpa.schema.json
+#   timestamp: 2025-07-16T14:06:10+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PinsLpa(BaseModel):
+    """
+    Local Planning Authority (LPA) attributes as per Horizon. This will be extended with ONS data
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    lpaName: str
+    """
+    The PINS name of the LPA
+    """
+    organisationType: str | None = None
+    """
+    The organisation type of the LPA
+    """
+    pinsLpaCode: str
+    """
+    The PINS-generated unqiue LPA code
+    """
+    poBox: str | None = None
+    """
+    LPA address Post Office Box
+    """
+    address1: str | None = None
+    """
+    First line of LPA address
+    """
+    address2: str | None = None
+    """
+    Second line of LPA address
+    """
+    city: str | None = None
+    """
+    LPA address city or town
+    """
+    county: str | None = None
+    """
+    LPA address county
+    """
+    postcode: str | None = None
+    """
+    LPA address postcode
+    """
+    country: str | None = None
+    """
+    LPA address country
+    """
+    telephoneNumber: str | None = None
+    """
+    LPA telephine number
+    """
+    fax: str | None = None
+    """
+    LPA fax number
+    """
+    emailAddress: str | None = None
+    """
+    LPA email address
+    """

package/pins_data_model/models/model_s51_advice.py

@@ -0,0 +1,109 @@
+# generated by datamodel-codegen:
+#   filename:  s51-advice.schema.json
+#   timestamp: 2025-07-16T14:06:09+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+class Method(Enum):
+    """
+    How the enquiry was made
+    """
+
+    phone = "phone"
+    email = "email"
+    meeting = "meeting"
+    post = "post"
+    fax = "fax"
+    NoneType_None = None
+
+
+class Status(Enum):
+    checked = "checked"
+    unchecked = "unchecked"
+    readytopublish = "readytopublish"
+    published = "published"
+    donotpublish = "donotpublish"
+    NoneType_None = None
+
+
+class RedactionStatus(Enum):
+    unredacted = "unredacted"
+    redacted = "redacted"
+    NoneType_None = None
+
+
+class S51Advice(BaseModel):
+    """
+    Section 51 Advice schema
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    adviceId: int = Field(..., examples=[1234])
+    adviceReference: str = Field(..., examples=["TR0200007-0005"])
+    caseId: int | None = Field(..., examples=[1234])
+    caseReference: str | None = Field(..., examples=["BC0110002"])
+    title: str = Field(
+        ...,
+        examples=[
+            "Advice following issue of decision to accept the application for examination"
+        ],
+    )
+    """
+    Title of the advice
+    """
+    titleWelsh: str | None = None
+    """
+    Title of the advice in Welsh
+    """
+    from_: str | None = Field(..., alias="from")
+    """
+    Who the enquiry is from
+    """
+    agent: str | None = None
+    """
+    Who the enquiry is on behalf of
+    """
+    method: Method
+    """
+    How the enquiry was made
+    """
+    enquiryDate: AwareDatetime | None = Field(
+        ..., examples=["2023-07-27T20:30:00.000Z"]
+    )
+    """
+    Date the enquiry was made
+    """
+    enquiryDetails: str | None = None
+    """
+    Details of the enquiry
+    """
+    enquiryDetailsWelsh: str | None = None
+    """
+    Details of the enquiry in Welsh
+    """
+    adviceGivenBy: str | None = None
+    """
+    Who issued the advice
+    """
+    adviceDate: AwareDatetime | None = Field(..., examples=["2023-07-27T20:30:00.000Z"])
+    """
+    Date the advice was given
+    """
+    adviceDetails: str | None = None
+    """
+    Details of the advice
+    """
+    adviceDetailsWelsh: str | None = None
+    """
+    Details of the advice in Welsh
+    """
+    status: Status
+    redactionStatus: RedactionStatus
+    attachmentIds: list[str]

package/pins_data_model/models/model_service_user.py

@@ -0,0 +1,121 @@
+# generated by datamodel-codegen:
+#   filename:  service-user.schema.json
+#   timestamp: 2025-07-16T14:06:10+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ServiceUserType(Enum):
+    """
+    Type or category of the service user.
+    """
+
+    Applicant = "Applicant"
+    Appellant = "Appellant"
+    Agent = "Agent"
+    Rule6Party = "Rule6Party"
+    InterestedParty = "InterestedParty"
+    RepresentationContact = "RepresentationContact"
+    Subscriber = "Subscriber"
+
+
+class ServiceUser(BaseModel):
+    """
+    Service User of the planning inspectorate. Also contains role information by combining serviceUserType and caseReference.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    id: str = Field(..., examples=["12345"])
+    """
+    A unique identifier for the entity.
+    """
+    salutation: str | None = Field(..., examples=["Mr"])
+    """
+    A formal greeting, e.g., Mr, Mrs, Ms.
+    """
+    firstName: str | None = Field(..., examples=["John"])
+    """
+    The first name of the individual.
+    """
+    lastName: str | None = Field(..., examples=["Doe"])
+    """
+    The last name of the individual.
+    """
+    addressLine1: str | None = Field(..., examples=["123 Elm Street"])
+    """
+    The first line of the address.
+    """
+    addressLine2: str | None = Field(..., examples=["Apt 4B"])
+    """
+    The second line of the address, usually includes suite or apartment number.
+    """
+    addressTown: str | None = Field(..., examples=["Springfield"])
+    """
+    The town or city of the address.
+    """
+    addressCounty: str | None = Field(..., examples=["Hampshire"])
+    """
+    The county in which the town or city is located.
+    """
+    postcode: str | None = Field(..., examples=["M12 4AF"])
+    """
+    The postal code for the address.
+    """
+    addressCountry: str | None = Field(..., examples=["United Kingdom"])
+    """
+    The country of the address.
+    """
+    organisation: str | None = Field(..., examples=["Tech Corp"])
+    """
+    The name of the organisation associated with the individual.
+    """
+    organisationType: str | None = Field(..., examples=["Private Company"])
+    """
+    The type or nature of the organisation.
+    """
+    role: str | None = Field(..., examples=["Agent"])
+    """
+    The individual's role or position within the organisation.
+    """
+    telephoneNumber: str | None = Field(..., examples=["+447123456789"])
+    """
+    The primary telephone contact number.
+    """
+    otherPhoneNumber: str | None = Field(..., examples=["+447123456789"])
+    """
+    An alternate or secondary phone number.
+    """
+    faxNumber: str | None = Field(..., examples=["+447123456789"])
+    """
+    A fax contact number.
+    """
+    emailAddress: str | None = Field(..., examples=["john.doe@example.com"])
+    """
+    The primary email address for contact.
+    """
+    webAddress: str | None = Field(..., examples=["https://www.example.com"])
+    """
+    Website address or URL.
+    """
+    serviceUserType: ServiceUserType
+    """
+    Type or category of the service user.
+    """
+    caseReference: str = Field(..., examples=["BC0510001"])
+    """
+    Reference number for a particular case or incident.
+    """
+    sourceSystem: str = Field(..., examples=["ODT", "Horizon"])
+    """
+    The originating system from where the data was sourced.
+    """
+    sourceSuid: str = Field(..., examples=["12345"])
+    """
+    Unique identifier from the source system.
+    """

package/requirements.txt

@@ -0,0 +1,2 @@
+datamodel-code-generator==0.25.2
+jsonc-parser==1.1.0

package/schemas/appeal-document.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "appeal-document.schema.json",
+  "title": "Appeal Document",
+  "description": "Schema defining the metadata for appeal documents",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "documentId",
+    "caseId",
+    "caseReference",
+    "version",
+    "filename",
+    "originalFilename",
+    "size",
+    "mime",
+    "documentURI",
+    "publishedDocumentURI",
+    "virusCheckStatus",
+    "fileMD5",
+    "dateCreated",
+    "dateReceived",
+    "datePublished",
+    "lastModified",
+    "caseType",
+    "redactedStatus",
+    "documentType",
+    "sourceSystem",
+    "origin",
+    "owner",
+    "author",
+    "description",
+    "caseStage",
+    "horizonFolderId"
+  ],
+  "properties": {
+    "documentId": {
+      "type": "string",
+      "examples": ["4547fec8-16b2-47bb-836d-4d0baac04079"],
+      "description": "The unique identifier for the document"
+    },
+    "caseId": {
+      "type": ["integer", "null"],
+      "examples": [1200],
+      "description": "Internal case identifier"
+    },
+    "caseReference": {
+      "type": "string",
+      "examples": ["7002471"],
+      "description": "External case identifier"
+    },
+    "version": {
+      "type": "integer",
+      "examples": [1],
+      "description": "A document can have multiple versions, and this indicates the latest version"
+    },
+    "filename": {
+      "type": "string",
+      "examples": ["filename.pdf"],
+      "description": "Current stored name of the document"
+    },
+    "originalFilename": {
+      "type": "string",
+      "examples": ["original_filename.pdf"],
+      "description": "Original name of document"
+    },
+    "size": {
+      "type": "integer",
+      "examples": [23452],
+      "description": "The file size, in bytes"
+    },
+    "mime": {
+      "type": ["string"],
+      "examples": ["application/pdf"],
+      "description": "The mime type for the current version of the file"
+    },
+    "documentURI": {
+      "type": "string",
+      "examples": [
+        "https://custom-domain.gov.uk/container-name/appeal/7002471/4547fec8-16b2-47bb-836d-4d0baac04079/v1/filename.pdf"
+      ],
+      "description": "The internal location of the document",
+      "$comment": "This property contains blob storage info (domain, container), caseReference, version and filename"
+    },
+    "publishedDocumentURI": {
+      "type": ["string", "null"],
+      "examples": [
+        "https://custom-domain.gov.uk/container-name/appeal/7002471/4547fec8-16b2-47bb-836d-4d0baac04079/v1/filename.pdf"
+      ],
+      "description": "The location of the published document, will be null if the datePublished is not set"
+    },
+    "virusCheckStatus": {
+      "type": ["string", "null"],
+      "enum": ["not_scanned", "scanned", "affected", null],
+      "description": "Indicates the virus check status for the current document"
+    },
+    "fileMD5": {
+      "type": ["string", "null"],
+      "examples": ["b1946ac92492d2347c6235b4d2611184"],
+      "description": "A MD5 hash to check the validity of the file"
+    },
+    "dateCreated": {
+      "type": "string",
+      "format": "date-time",
+      "examples": ["2023-07-27T20:30:00.000Z"],
+      "description": "The creation date for the document"
+    },
+    "dateReceived": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "examples": ["2023-07-27T20:30:00.000Z"],
+      "description": "The date the document was received",
+      "$comment": "This is a manually entered date to indicate documents exchanged manually"
+    },
+    "datePublished": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "examples": ["2023-07-27T20:30:00.000Z"],
+      "description": "The date the document was published"
+    },
+    "lastModified": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "examples": ["2023-07-27T20:30:00.000Z"],
+      "description": "The last update date for the document"
+    },
+    "caseType": {
+      "type": ["string", "null"],
+      "enum": ["C", "D", "F", "G", "H", "L", "Q", "S", "V", "W", "X", "Y", "Z", "ZA", "ZP", null],
+      "description": "The internal code for an appeal type, e.g. Householder (D)"
+    },
+    "redactedStatus": {
+      "type": ["string", "null"],
+      "enum": ["not_redacted", "redacted", "no_redaction_required", null],
+      "description": "Indicates the redaction status for the document"
+    },
+    "documentType": {
+      "type": ["string", "null"],
+      "enum": [
+        "appellantCaseCorrespondence",
+        "appellantCaseWithdrawalLetter",
+        "appellantCostsApplication",
+        "appellantCostsCorrespondence",
+        "appellantCostsWithdrawal",
+        "appellantStatement",
+        "applicationDecisionLetter",
+        "changedDescription",
+        "originalApplicationForm",
+        "whoNotified",
+        "whoNotifiedSiteNotice",
+        "whoNotifiedLetterToNeighbours",
+        "whoNotifiedPressAdvert",
+        "conservationMap",
+        "lpaCaseCorrespondence",
+        "lpaCostsApplication",
+        "lpaCostsCorrespondence",
+        "lpaCostsWithdrawal",
+        "otherPartyRepresentations",
+        "planningOfficerReport",
+        "appellantCostsDecisionLetter",
+        "lpaCostsDecisionLetter",
+        "caseDecisionLetter",
+        "crossTeamCorrespondence",
+        "inspectorCorrespondence",
+        "mainPartyCorrespondence",
+        "uncategorised",
+        "designAccessStatement",
+        "plansDrawings",
+        "newPlansDrawings",
+        "planningObligation",
+        "ownershipCertificate",
+        "otherNewDocuments",
+        "statementCommonGround",
+        "communityInfrastructureLevy",
+        "supplementaryPlanning",
+        "otherRelevantPolicies",
+        "emergingPlan",
+        "developmentPlanPolicies",
+        "consultationResponses",
+        "eiaEnvironmentalStatement",
+        "eiaScreeningDirection",
+        "eiaScreeningOpinion",
+        "eiaScopingOpinion",
+        "definitiveMapStatement",
+        "treePreservationPlan",
+        "interestedPartyComment",
+        "lpaStatement",
+        "rule6Statement",
+        "appellantFinalComment",
+        "lpaFinalComment",
+        "appellantProofOfEvidence",
+        "appellantWitnessesEvidence",
+        "lpaProofOfEvidence",
+        "lpaWitnessesEvidence",
+        "rule6ProofOfEvidence",
+        "rule6WitnessesEvidence",
+        "environmentalAssessment",
+        "appealNotification",
+        "historicEnglandConsultation",
+        null
+      ],
+      "description": "The type of document, used for exchange, migrations and consumption from the appeal back-office system"
+    },
+    "sourceSystem": {
+      "type": ["string", "null"],
+      "enum": ["back-office-appeals", "horizon", "acp", "sharepoint", null],
+      "description": "The system mastering the metadata for the current document"
+    },
+    "origin": {
+      "type": ["string", "null"],
+      "enum": ["pins", "citizen", "lpa", "ogd", null],
+      "description": "Indicates where the documents originates from"
+    },
+    "owner": {
+      "type": ["string", "null"],
+      "description": "Owner of the current document"
+    },
+    "author": {
+      "type": ["string", "null"],
+      "description": "Name of person who authored document"
+    },
+    "description": {
+      "type": ["string", "null"],
+      "description": "A custom description for the document"
+    },
+    "caseStage": {
+      "type": ["string", "null"],
+      "enum": [
+        "appellant-case",
+        "lpa-questionnaire",
+        "statements",
+        "third-party-comments",
+        "evidence",
+        "witnesses",
+        "final-comments",
+        "appeal-decision",
+        "costs",
+        "internal",
+        null
+      ],
+      "description": "The stage in the appeal process that has created the document",
+      "$comment": "This could be useful to reduce the number of document types, allowing the same type to be reused across stages"
+    },
+    "horizonFolderId": {
+      "type": ["string", "null"],
+      "description": "The folder ID containing the document in Horizon",
+      "$comment": "Used for legacy / migrations"
+    }
+  }
+}

package/schemas/appeal-event-estimate.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "appeal-event-estimate.schema.json",
+  "title": "Appeal Event Estimate",
+  "description": "All event estimates belong to a case. A case has only one event estimate.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["id", "caseReference", "preparationTime", "sittingTime", "reportingTime"],
+  "properties": {
+    "id": {
+      "type": "integer",
+      "description": "The unique identifier within the Back Office."
+    },
+    "caseReference": {
+      "type": "string",
+      "description": "The case reference the event estimate belongs to."
+    },
+    "preparationTime": {
+      "type": ["number", "null"],
+      "description": "Estimated inspector time (days) to prepare for event."
+    },
+    "sittingTime": {
+      "type": ["number", "null"],
+      "description": "Estimated inspector time (days) for event."
+    },
+    "reportingTime": {
+      "type": ["number", "null"],
+      "description": "Estimated inspector time (days) for event reporting."
+    }
+  }
+}