openapi: 3.1.0
info:
  title: IEC CIM 61968 Distribution Management Customers Work Orders API
  description: REST API for distribution utility systems based on IEC 61968 Common Information Model (CIM) standards. Provides access to network assets, outage management, customer information, meter reading, and work management data using CIM-compliant resource representations. Implements IEC 61968 Parts 3, 4, 9, and 11 interfaces for distribution management systems (DMS) integration.
  version: 1.0.0
  contact:
    name: CIM User Group
    url: https://cimug.ucaiug.org/
  license:
    name: IEC License
    url: https://www.iec.ch/
servers:
- url: https://dms-gateway.utility.example.com/cim/61968/v1
  description: Distribution Management System CIM API gateway
security:
- OAuth2: []
- BasicAuth: []
tags:
- name: Work Orders
  description: Maintenance and construction work orders
paths:
  /work-orders:
    get:
      operationId: listWorkOrders
      summary: List work orders
      description: Returns distribution maintenance and construction work orders.
      tags:
      - Work Orders
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - PENDING
          - ISSUED
          - INPROGRESS
          - COMPLETED
          - CANCELLED
      - name: workType
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Work orders returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrderList'
components:
  schemas:
    WorkOrderList:
      type: object
      properties:
        workOrders:
          type: array
          items:
            $ref: '#/components/schemas/WorkOrder'
        total:
          type: integer
    WorkOrder:
      type: object
      description: CIM Work – a work order for utility field operations
      properties:
        mRID:
          type: string
          format: uuid
        workOrderNumber:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - ISSUED
          - INPROGRESS
          - COMPLETED
          - CANCELLED
        workType:
          type: string
        priority:
          type: string
          enum:
          - EMERGENCY
          - HIGH
          - ROUTINE
          - LOW
        scheduledStart:
          type: string
          format: date-time
        actualStart:
          type: string
          format: date-time
        completedDateTime:
          type: string
          format: date-time
        location:
          $ref: '#/components/schemas/Location'
        assignedCrew:
          type: string
    Location:
      type: object
      description: CIM Location with coordinates
      properties:
        mRID:
          type: string
          format: uuid
        name:
          type: string
        addressGeneral:
          type: string
        positionPoints:
          type: array
          items:
            type: object
            properties:
              sequenceNumber:
                type: integer
              xPosition:
                type: string
                description: Longitude
              yPosition:
                type: string
                description: Latitude
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.utility.example.com/oauth/token
          scopes:
            cim.read: Read CIM data
            cim.write: Write CIM data
    BasicAuth:
      type: http
      scheme: basic
externalDocs:
  description: IEC CIM User Group
  url: https://cimug.ucaiug.org/