openapi: '3.0.3'
info:
  title: Accruals
  description: Manages access to Accrual data. A thin layer over the data store with some convenience endpoints to hide the complexity of joining data
  version: 0.1.0
paths: 
  /resources/accrualDefinition:
    get:
      summary: Get all AccrualDefinition resources known to the API
      operationId: getAccrualDefinitions
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AccrualDefinition'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
  /resources/accruals:
    get:
      summary: Get all Accrual instances that meet the query criteria
      operationId: findAccruals
      parameters:
        - name: dateFrom
          in: query
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string 
            format: date
        - name: dateTo
          in: query
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string 
            format: date 
        - name: typeCode
          in: query
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string 
            format: date            
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Accrual'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
    put:
      summary: Update a collection of Accrual resources atomically
      operationId: updateAccruals
      responses:
        '200':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'  
  /operations/accrualSummary:
    get:
      summary: Return a set of AccrualSummary resources for the given person and date
      operationId: getAccrualSummaries
      parameters:
        - name: date
          in: query
          description: The date which the AccrualSummary resources will target
          required: true
          schema:
            type: string
            format: date
        - name: personId
          in: query
          description: The person targeted by the AccrualSummary resources
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AccrualSummary'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'                 
  /operations/isPublicHoliday:
    get:
      summary: Determine whether or not the given day is a public holiday (or a substitute public holiday)
      operationId: isPublicHoliday
      parameters:
        - name: date
          in: query
          description: The date whose Public holiday status is to be determined
          required: true
          schema:
            type: string
            format: date
        - name: personId
          in: query
          description: The person has a bearing on whether a date is a public holiday
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A boolean value. True if the date is a public  holiday in the context of the person otherwise False
          content:
            application/json:    
              schema:
                type:
                  boolean 
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'  
  /operations/isNightShift:
    get:
      summary: Determine whether or not the given time period falls within the bounds of a night shift
      operationId: isNightShift
      parameters:
        - name: personId
          in: query
          description: The person has a bearing on whether the time period is considered to be a night shift
          required: true
          schema:
            type: string
        - name: startTime
          in: query
          description: The start of the time period to be assessed
          required: true
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          description: The end of the time period to be assessed
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A boolean value. True if the time period encapsulated by the startTime and endTime params is a Night shift otherwise False
          content:
            application/json:    
              schema:
                type:
                  boolean 
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error' 
  /operations/isNormalShift:
    get:
      summary: Determine whether or not the given time period falls within the bounds of a normal shift
      operationId: isNormalShift
      parameters:
        - name: personId
          in: query
          description: The person has a bearing on whether the time period is considered to be a normal shift
          required: true
          schema:
            type: string      
        - name: startTime
          in: query
          description: The start of the time period to be assessed
          required: true
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          description: The end of the time period to be assessed
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A boolean value. True if the time period encapsulated by the startTime and endTime params is a Normal shift otherwise False
          content:
            application/json:    
              schema:
                type:
                  boolean 
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'                
components:
  schemas:
    Contribution:
      type: object
      description: A contribution towards the balance of an Accrual
      required: 
        - value
        - timeEntryId
      properties:
        value:
          description: Holds the count that this resource contributes to the owning Accrual resource's balance
          type: number
          format: double
        timeEntryId:
           description: The identifier of the TimeEntry that contributed some or all of this resource's value
           type: number
    Accrual:
      type: object
      description: . 
      required:
            - code
            - date
            - balance
      properties:
        personId:
          description: The identifier of the Person who's balance this Accrual is tracking
          type: number        
        code: 
          description: The code of the type of Accrual that this resource is an instance of eg "AnnualHours". Can be used to retrieve meta-data about this type of Accrual
          type: string
        date:
          description: The date that this resource is associated with
          type: string
          format: date
        balance:
          description: The total of all associated contribution values plus the balance from the previous day's Accrual
          format: double
        contributions:
            description: The set of contributions that help to make up this resource's balance
            allOf:
              - $ref: '#/components/schemas/Contribution'
    AccrualDefinition:
      type: object
      description: . 
      required:
            - code
            - name
            - measurementUnit
      properties:
        code: 
          description: The code of the type of Accrual that this resource is an instance of eg "AnnualHours". Can be used to retrieve meta-data about this type of Accrual
          type: string
        name:
          description: The user friendly name of this type of Accrual. Intended to be displayed in a user interface
          type: string
        measurementUnit:
          description: The way that the balance of an Accrual of this `accrual_type` should be interpreted eg "hours" or "count"
          format: string
    AccrualSummary:
      type: object
      description: Provides an overview of a specific type of Accrual for a specific date. 
      required:
            - name
            - measurementUnit
            - personId
            - date
            - target
            - remainingLowPrecision
            - remainingHighPrecision
            - targetVariance
            - agreementVariance
            - targetStatus
      properties:
        name:
          description: The user friendly name of this type of Accrual. Intended to be displayed in a user interface
          type: string
        personId:
          description: The identifier of the Person who's Accrual is being summarised
          type: number             
        date:
          description: The date that this summary covers 
          type: string
          format: date 
        measurementUnit:
          description: The way that the balance of an Accrual of this `accrual_type` should be interpreted eg "hours" or "count"
          type: string  
        total:
          description: The total amount agreed for the Accrual in the Agreement period. 
          type: number
          format: double 
        worked:
          description: The total amount of units worked to date. 
          type: number
          format: double           
        totalNetOrGrossOfPH: 
          description: Shows whether the target is net or gross of public holiday allowence
          type: string
          enum:
            - net_of_ph
            - gross_of_ph                  
        target:
          description: The pro-rated target value for the Accrual. Shows how many units of the Accrual type the worker should have worked (or been sheduled to work) by this date in order to remain on track to meet the target by the end of the agreement period
          type: number
          format: double 
        remainingLowPrecision: 
          description: The balance that is remaining at the given date presented as a rounded number
          type: integer 
        remainingHighPrecision: 
          description: The balance that is remaining at the given date presented as a floating point number
          type: number
          format: double
        targetVariance:
          description: Shows how far in surplus (positive number) or deficit (negative number) the worker is against their target
          type: number
          format: double
        agreementVariance: 
          description: Shows how far in surplus (positive number) or deficit (negative number) the worker is against their agreement
          type: number
          format: double   
        targetStatus: 
          description: Shows whether the worker is over, under or on target 
          type: string
          enum:
            - over_target
            - under_target
            - on_target                                                            
    Error:
      type: object
      description: A container for returning error conditions.
      required: 
        - error-code
        - message
      properties:
        error-code:
          description: Unique within the context of the API and specific to the category of error being reported
          type: string
        message:
           description: A user friendly summary of the issue. Should be suitable to display in a user interface
           type: string
        detail:
           description: Detail to help the client-developer understand the issue
           type: string