openapi: "3.0.2"
info:
  title: Sample API
  version: "2.1.0.0"
  description: |
    Schema definition for SmarterWX Sentinel Referral Webhook notifications (v2.1.0.0)

paths: {} # No paths defined as the focus is on the schema

components:
  schemas:
    Organisation:
      type: object
      properties:
        id:
          type: integer
          example: 234
          description: Internal ID for this organisation
        name:
          type: string
          maxLength: 100
          example: Melbourne Water
        utilityId:
          type: integer
          minimum: 10001
          maximum: 999999
          example: 80010
        contactName:
          type: string
          maxLength: 100
          example: Asset Protection Team
        contactEmail:
          type: string
          maxLength: 254
          example: assets.protection@melbournewater.com
        contactPhoneNumber:
          type: string
          maxLength: 16
          example: +61131234
      required:
        - id
        - name
        - utilityId

    Address:
      type: object
      properties:
        id:
          type: integer
          example: 123
          description: Internal ID
        line1:
          type: string
          maxLength: 100
          example: 613 King St
          description: First line of the address
        line2:
          type: string
          maxLength: 100
          example: Suite 13
          description: Second line of the address
        locality:
          type: string
          maxLength: 100
          example: West Melbourne
          description: Locality or suburb
        state:
          type: string
          maxLength: 20
          example: VIC
          description: State - in Australia this is two/three character short forms
        postcode:
          type: string
          maxLength: 10
          example: 3003
          description: Postcode - in Australia this is a four digit string
        country:
          type: string
          maxLength: 3
          example: AUS
          description: Country - ISO-3166 Alpha-3 code
      required:
        - id
        - line1
        - locality
        - state
        - postcode
        - country

    User:
      type: object
      properties:
        Address:
          $ref: '#/components/schemas/Address'
        id:
          type: integer
          example: 234
          description: Internal ID for this user - will not change
        email:
          type: string
          format: email
          maxLength: 254
          example: as567sadf.asdf87asdf@relay.smarterwx.com
          description: |
            For a referral, this field will hold the relay email address.
            For an enquiry, it will hold the user's registered email address.
        registeredEmail:
          type: string
          format: email
          maxLength: 254
          example: gary@smarterwx.com
          description: |
            Only included for referrals, this field holds 
            the user's registered email address.
        firstName:
          type: string
          minLength: 2
          maxLength: 100
          example: Ross
        lastName:
          type: string
          minLength: 2
          maxLength: 100
          example: Noble
        phoneNumber:
          type: string
          maxLength: 16
          example: +61444111222
        companyName:
          type: string
          maxLength: 100
          example: Jim's Locating Services
        verificationStatus:
          type: string
          description: Describes how this user identity has been verified
          example: EmailOnly
          enum: [EmailOnly]
        subscriptionStatus:
          type: string
          description: Not in use
          example: None
          enum: [None]
        preferredDataFormat:
          type: string
          description: Not in use
          example: None
          enum: [None]
      required:
        - id
        - email
        - registeredEmail
        - firstName
        - lastName
        - phoneNumber
        - verificationStatus
        - subscriptionStatus
        - preferredDataFormat
        - Address

    Enquiry:
      type: object
      properties:
        Address:
          $ref: '#/components/schemas/Address'
        User:
          $ref: '#/components/schemas/User'
        id:
          type: integer
          example: 234
          description: Internal ID for this enquiry
        createdAt:
          type: string
          format: date-time
          example: "2020-11-28 06:08:00.000Z"
          description: The timestamp when the enquiry was created
        jobNumber:
          type: integer
          example: 40000255
          description: User facing job number
        userReference:
          type: string
          maxLength: 100
          example: Plan Ref AB/123
          description: Free text reference entered by enquirer
        notes:
          type: string
          maxLength: 500
          example: I am going to be digging a rather large hole.
          description: Free text description of the job
        digStartAt:
          type: string
          format: date
          example: "2020-11-29"
          description: Planned start date for the works
        digEndAt:
          type: string
          format: date
          example: "2020-11-30"
          description: Planned end date for the works
        isPlanningJob:
          type: boolean
          example: false
          description: Indicates if this is a planning/design job
        activityTypes:
          type: array
          items:
            type: string
            maxLength: 25
            example: MANUAL_EXCAVATION, HORIZ_BORING
            description: The coded activities being performed on this job
        activityTypesLocalized:
          type: array
          items:
            type: string
            maxLength: 30
            example: Manual Excavation, Horizontal Boring
            description: The friendly activities being performed on this job
        authorityType:
          type: string
          enum: [Utility, Local Government, Private, Other]
        authorityName:
          type: string
          maxLength: 100
          example: Melbourne Water
        locationTypes:
          type: array
          items:
            type: string
            enum: [Road Reserve, Private]
            example: Road Reserve
            description: Where the job is taking place
        locationsInRoad:
          type: array
          items:
            type: string
            enum: [Road, Nature Strip, Footpath]
            description: Where the job is taking place if in the road reserve
        isSandboxTest:
          type: boolean
          example: false
          description: True if this referral is a test
        source:
          type: string
          enum: [API, AUTORENEW, BULK, MOBILE, WEB]
          example: WEB
          description: Describes how this enquiry was lodged
        projectReference:
          type: string
          description: Not in use
          example: ""
          enum: [""]
        geometry:
          type: object
          description: |
            GeoJSON description of the job site.
            For referrals, this may be sent in the CRS of organisation's choice.
      required:
        - id
        - createdAt
        - jobNumber
        - digStartAt
        - digEndAt
        - isPlanningJob
        - activityTypes
        - authorityType
        - locationTypes
        - isSandboxTest
        - source
        - projectReference
        - geometry
        - Address
        - User
      
    AutoRenew:
      type: object
      description: Only included if the source of this enquiry is AUTORENEW
      properties:
        firstEnquiryId:
          type: integer
          example: 234
          description: The original internal id of the enquiry lodged by the user that triggers this new referral.
        firstJobNumber:
          type: integer
          example: 40000255
          description: The original job number of the enquiry lodged by the user that triggers this new referral.
        firstReferralId:
          type: integer
          example: 234
          description: The original internal id of the referral lodged by the user that triggers this new referral.
        firstSequenceNumber:
          type: integer
          example: 300077255
          description: The original sequence number of the enquiry lodged by the user that triggers this new referral.
      required:
        - firstEnquiryId
        - firstJobNumber
        - firstReferralId
        - firstSequenceNumber

    LodgedBy:
      type: object
      description: |
        Not currently in use.
        If the enquiry was lodged on behalf of the enquirer by a BYDA or Helpdesk user,
        this object will describe the user who performed the enquiry lodgement.
      properties:
        id:
          type: integer
          example: 234
          description: Internal ID for this user - will not change
        registeredEmail:
          type: string
          format: email
          maxLength: 254
          example: chris@byda.com.au
          description: The registered email address for the user who lodged the enquiry.
        firstName:
          type: string
          minLength: 2
          maxLength: 100
          example: Chris
        lastName:
          type: string
          minLength: 2
          maxLength: 100
          example: Jobling
        phoneNumber:
          type: string
          maxLength: 16
          example: +61444111222
        companyName:
          type: string
          maxLength: 100
          example: Before You Dig Australia
      required:
        - id
        - registeredEmail
        - firstName
        - lastName
        - phoneNumber

    Root:
      type: object
      properties:
        Organisation:
          $ref: '#/components/schemas/Organisation'
        Enquiry:
          $ref: '#/components/schemas/Enquiry'
        LodgedBy:
          $ref: '#/components/schemas/LodgedBy'
        autoRenew:
          $ref: '#/components/schemas/AutoRenew'
        id:
          type: integer
          example: 234
          description: Internal ID for this referral
        createdAt:
          type: string
          format: date-time
          example: "2020-11-28 06:08:01.000Z"
          description: The timestamp when the referral was created
        status:
          type: string
          enum: ["CREATED", "WAITING", "COMPLETED", "TIMEDOUT", "FAILED"]
          example: WAITING
          description: The current status of this referral
        sequenceNumber:
          type: integer
          example: 300077255
          description: User facing sequence number for this referral
        messageVersion:
          type: string
          enum: ["2.1.0.0"]
          example: "2.1.0.0"
          description: Version number of this message format
      required:
        - id
        - createdAt
        - status
        - sequenceNumber
        - messageVersion
        - Enquiry
        - Organisation