openapi: 3.1.0
info:
  title: IEC CIM 61968 Distribution Management Customers 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: Customers
  description: Customer service agreements and locations
paths:
  /customers:
    get:
      operationId: listCustomers
      summary: List utility customers
      description: Returns utility customer accounts and service agreements. Supports search by name, address, or account number.
      tags:
      - Customers
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Search query (name or address)
      - name: accountNumber
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Customer list returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerList'
components:
  schemas:
    CustomerList:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        total:
          type: integer
    Customer:
      type: object
      description: CIM Customer – utility customer record
      properties:
        mRID:
          type: string
          format: uuid
        name:
          type: string
        accountNumber:
          type: string
        customerType:
          type: string
          enum:
          - RESIDENTIAL
          - COMMERCIAL
          - INDUSTRIAL
          - AGRICULTURAL
        serviceLocation:
          $ref: '#/components/schemas/Location'
        email:
          type: string
        phone:
          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/