openapi: 3.1.1
info:
  title: EnergyProgramEnrollment
  version: '2.0'
  description: 'Attribute schema for program enrollment (Fulfillment.fulfillmentAttributes and Contract.orderAttributes).
    These attributes support the onboarding flow where BPP verifies credentials, checks for conflicts,
    and issues enrollment credentials. Used in init requests (fulfillmentAttributes) and init/confirm
    responses (Contract.orderAttributes).

    EnergyProgramEnrollment is the successor to EnergyEnrollment (v0.2, v2.0). OWL migration: deg:EnergyProgramEnrollment
    owl:equivalentClass deg:EnergyEnrollment.'
components:
  schemas:
    EnergyProgramEnrollment:
      type: object
      additionalProperties: true
      x-tags:
      - energy-enrollment
      - demand-response
      - vpp
      - fulfillment
      x-jsonld:
        '@context': ./context.jsonld
        '@type': EnergyProgramEnrollment
      properties:
        userAuth:
          description: "User authentication for enrollment verification. Supports OTP-based or OAuth2/OIDC\
            \ token-based authentication.\nFor REQUESTS (init, confirm):\n  Use UserAuthRequest (OtpAuthRequest\
            \ or OAuth2AuthRequest)\n  - OTP: Send mobile (init) or mobile+nguid+otp (confirm)\n  - OAuth2/OIDC:\
            \ Send accessToken (and idToken for OIDC)\n\nFor RESPONSES (on_init, on_confirm):\n  Use UserAuthResponse\
            \ (OtpAuthResponse or OAuth2AuthResponse)\n  - Returns verification status, extracted identity,\
            \ and session tokens\n"
          oneOf:
          - $ref: '#/$defs/UserAuthRequest'
          - $ref: '#/$defs/UserAuthResponse'
          x-jsonld:
            '@id': userAuth
        meters:
          type: array
          description: 'Array of meter identifiers to enroll in the program. Required in confirm request
            - order will only be confirmed if at least one meter is specified. Each meter should include
            the meter ID (UMID) and optionally utility information. If userAuth is verified but meters
            array is empty, on_confirm returns error "no meter specified".

            '
          items:
            $ref: '#/$defs/MeterEnrollment'
          x-jsonld:
            '@id': meters
            '@container': '@set'
        credentials:
          type: array
          description: 'Array of W3C Verifiable Credentials (https://www.w3.org/TR/vc-data-model-2.0/)
            provided by calling entity (Portal/BAP). Includes meter ownership, program eligibility, and
            DER certification credentials.

            '
          items:
            $ref: '#/$defs/VerifiableCredential'
          x-jsonld:
            '@id': credentials
        existingEnrollments:
          type: array
          description: 'Array of existing W3C Verifiable Credentials for conflict checking. Provided by
            calling entity to help BPP identify conflicts.

            '
          items:
            $ref: '#/$defs/VerifiableCredential'
          x-jsonld:
            '@id': existingEnrollments
        credentialVerification:
          type: object
          description: 'Results of credential verification performed by BPP. Returned in on_init response
            after BPP verifies provided credentials.

            '
          x-jsonld:
            '@id': credentialVerification
            '@type': CredentialVerification
          properties:
            status:
              type: string
              enum:
              - VERIFIED
              - FAILED
              - PARTIAL
              description: Overall verification status. VERIFIED if all credentials verified, FAILED if
                any failed, PARTIAL if some verified.
              example: VERIFIED
              x-jsonld:
                '@id': status
            verifiedCredentials:
              type: array
              description: Array of credentials that were successfully verified.
              items:
                $ref: '#/$defs/VerifiedCredential'
              x-jsonld:
                '@id': verifiedCredentials
        conflictCheck:
          type: object
          description: 'Results of conflict checking with existing enrollments. Returned in on_init response
            after BPP checks for conflicts.

            '
          x-jsonld:
            '@id': conflictCheck
            '@type': ConflictCheck
          properties:
            hasConflict:
              type: boolean
              description: 'Boolean indicating if a conflict exists. True if meter/DER is already enrolled
                in another program with overlapping dates, false otherwise.

                '
              example: false
              x-jsonld:
                '@id': hasConflict
            conflictingEnrollments:
              type: array
              description: 'Array of conflicting enrollments. Only present when hasConflict is true. Empty
                array if no conflicts found.

                '
              items:
                $ref: '#/$defs/ConflictingEnrollment'
              x-jsonld:
                '@id': conflictingEnrollments
            checkedAt:
              type: string
              format: date-time
              description: Timestamp when conflict check was performed (ISO 8601 UTC).
              example: '2024-10-15T10:30:05Z'
              x-jsonld:
                '@id': checkedAt
            message:
              type: string
              description: Human-readable message explaining conflict check results.
              example: No conflicts found with existing enrollments
              x-jsonld:
                '@id': message
        requiredCredentials:
          type: array
          description: 'Array of credential types that are required for enrollment. Returned in on_init
            response to inform BAP what credentials are needed. Each entry includes type, description,
            and status (PROVIDED, MISSING).

            '
          items:
            type: object
            additionalProperties: true
            description: Required credential object with type, description, and status
          x-jsonld:
            '@id': requiredCredentials
        requiredConsents:
          type: array
          description: 'Array of consent types that are required for enrollment. Returned in on_init response
            to inform BAP what consents are needed. Each entry includes type, description, and whether
            it''s required or optional.

            '
          items:
            type: object
            additionalProperties: true
            description: Required consent object with type, description, and required flag
          x-jsonld:
            '@id': requiredConsents
        startDate:
          type: string
          format: date-time
          description: 'Date and time when enrollment becomes active (ISO 8601 UTC). Specified by calling
            entity in confirm request, returned in on_confirm response.

            '
          example: '2024-11-01T00:00:00Z'
          x-jsonld:
            '@id': startDate
        endDate:
          type: string
          format: date-time
          description: 'Date and time when enrollment expires or ends (ISO 8601 UTC). Specified by calling
            entity in confirm request, returned in on_confirm response.

            '
          example: '2025-10-31T23:59:59Z'
          x-jsonld:
            '@id': endDate
        consents:
          type: array
          description: 'Array of consent objects provided by the buyer in confirm request. Each consent
            indicates the type of consent and whether it was granted.

            '
          items:
            type: object
            additionalProperties: true
            description: Consent object with type, granted status, grantedAt timestamp, and description
          x-jsonld:
            '@id': consents
        updateType:
          type: string
          enum:
          - CONSENT_REVOCATION
          - UNENROLLMENT
          description: 'Type of update being performed. CONSENT_REVOCATION for revoking consent, UNENROLLMENT
            for cancelling entire enrollment.

            '
          example: CONSENT_REVOCATION
          x-jsonld:
            '@id': updateType
        consentRevocation:
          type: object
          description: 'Consent revocation details. Used in update request to revoke a consent credential,
            and in on_update response to confirm revocation with status list information.

            '
          x-jsonld:
            '@id': consentRevocation
            '@type': ConsentRevocation
          properties:
            consentCredentialId:
              type: string
              format: uri
              description: 'Identifier of the consent credential being revoked. References the Verifiable
                Credential ID.

                '
              example: https://vpp-program-owner.example.com/credentials/vc:consent:consumer-001
              x-jsonld:
                '@id': consentCredentialId
            consentType:
              type: string
              enum:
              - DATA_COLLECTION
              - DER_CONTROL
              - CROSS_UTILITY_SHARING
              description: 'Type of consent being revoked. DATA_COLLECTION for data sharing consent, DER_CONTROL
                for device control consent, CROSS_UTILITY_SHARING for cross-utility data sharing.

                '
              example: DATA_COLLECTION
              x-jsonld:
                '@id': consentType
            reason:
              type: string
              description: 'Reason for revocation. Values: USER_REQUESTED, PROGRAM_TERMINATED, COMPLIANCE_REQUIREMENT,
                etc.

                '
              example: USER_REQUESTED
              x-jsonld:
                '@id': reason
            revokedAt:
              type: string
              format: date-time
              description: 'Timestamp when the consent was revoked (ISO 8601 UTC). In request, this is
                when user initiated revocation. In response, this is when BPP processed it.

                '
              example: '2024-11-20T14:30:00Z'
              x-jsonld:
                '@id': revokedAt
            effectiveDate:
              type: string
              format: date-time
              description: 'Date and time when the revocation becomes effective (ISO 8601 UTC). May be
                in the future for scheduled revocations.

                '
              example: '2024-11-20T14:30:00Z'
              x-jsonld:
                '@id': effectiveDate
            status:
              type: string
              enum:
              - REVOKED
              - PENDING
              description: 'Revocation status. REVOKED when processed, PENDING when scheduled for future.
                Only present in on_update response.

                '
              example: REVOKED
              x-jsonld:
                '@id': status
            statusListUrl:
              type: string
              format: uri
              description: 'URL of the W3C VC status list where the revoked credential is recorded. Only
                present in on_update response after revocation is processed.

                '
              example: https://vpp-program-owner.example.com/status/consent-list
              x-jsonld:
                '@id': statusListUrl
            statusListIndex:
              type: string
              description: 'Index in the status list where this credential''s revocation status is recorded.
                Only present in on_update response.

                '
              example: '94567'
              x-jsonld:
                '@id': statusListIndex
            message:
              type: string
              description: 'Human-readable message about the revocation status. Only present in on_update
                response.

                '
              example: Consent has been revoked and added to revocation status list.
              x-jsonld:
                '@id': message
        unenrollment:
          type: object
          description: 'Unenrollment details. Used in update request to cancel enrollment, and in on_update
            response to confirm cancellation with status list information.

            '
          x-jsonld:
            '@id': unenrollment
            '@type': Unenrollment
          properties:
            enrollmentId:
              type: string
              description: 'Identifier of the enrollment being cancelled.

                '
              example: enrollment-consumer-001
              x-jsonld:
                '@id': enrollmentId
            reason:
              type: string
              description: 'Reason for unenrollment. Values: USER_REQUESTED, PROGRAM_TERMINATED, COMPLIANCE_REQUIREMENT,
                etc.

                '
              example: USER_REQUESTED
              x-jsonld:
                '@id': reason
            effectiveDate:
              type: string
              format: date-time
              description: 'Date and time when the unenrollment becomes effective (ISO 8601 UTC). May
                be in the future for scheduled unenrollment.

                '
              example: '2024-11-20T15:00:00Z'
              x-jsonld:
                '@id': effectiveDate
            revokeAllConsents:
              type: boolean
              description: 'Boolean indicating whether all associated consents should be revoked during
                unenrollment. If true, all consent credentials associated with this enrollment will be
                revoked.

                '
              example: true
              x-jsonld:
                '@id': revokeAllConsents
            status:
              type: string
              enum:
              - CANCELLED
              - PENDING
              description: 'Unenrollment status. CANCELLED when processed, PENDING when scheduled for
                future. Only present in on_update response.

                '
              example: CANCELLED
              x-jsonld:
                '@id': status
            cancelledAt:
              type: string
              format: date-time
              description: 'Timestamp when the enrollment was cancelled (ISO 8601 UTC). Only present in
                on_update response.

                '
              example: '2024-11-20T15:00:05Z'
              x-jsonld:
                '@id': cancelledAt
            enrollmentCredentialStatus:
              type: object
              description: 'Status information for the enrollment credential after revocation. Contains
                status list details for verification. Only present in on_update response.

                '
              x-jsonld:
                '@id': enrollmentCredentialStatus
              additionalProperties: false
              properties:
                statusListUrl:
                  type: string
                  format: uri
                  description: URL of the status list for the enrollment credential.
                  example: https://vpp-program-owner.example.com/status/enrollment-list
                  x-jsonld:
                    '@id': statusListUrl
                statusListIndex:
                  type: string
                  description: Index in the status list for the enrollment credential.
                  example: '12345'
                  x-jsonld:
                    '@id': statusListIndex
                revoked:
                  type: boolean
                  description: Whether the enrollment credential has been revoked.
                  example: true
                  x-jsonld:
                    '@id': revoked
            consentsRevoked:
              type: array
              description: 'Array of consent credentials that were revoked as part of unenrollment. Only
                present in on_update response when revokeAllConsents was true.

                '
              items:
                type: object
                additionalProperties: false
                properties:
                  consentCredentialId:
                    type: string
                    format: uri
                    description: Identifier of the revoked consent credential.
                    example: https://vpp-program-owner.example.com/credentials/vc:consent:consumer-001
                    x-jsonld:
                      '@id': consentCredentialId
                  statusListUrl:
                    type: string
                    format: uri
                    description: URL of the status list for this consent credential.
                    example: https://vpp-program-owner.example.com/status/consent-list
                    x-jsonld:
                      '@id': statusListUrl
                  statusListIndex:
                    type: string
                    description: Index in the status list for this consent credential.
                    example: '94567'
                    x-jsonld:
                      '@id': statusListIndex
                  revoked:
                    type: boolean
                    description: Whether this consent credential has been revoked.
                    example: true
                    x-jsonld:
                      '@id': revoked
              x-jsonld:
                '@id': consentsRevoked
            message:
              type: string
              description: 'Human-readable message about the unenrollment status. Only present in on_update
                response.

                '
              example: Enrollment and all associated consents have been revoked.
              x-jsonld:
                '@id': message
        enrollmentId:
          type: string
          description: 'Unique identifier for the enrollment. Assigned by BPP upon enrollment confirmation.
            Used for tracking, audit, and enrollment management.

            '
          example: enrollment-consumer-001
          x-jsonld:
            '@id': enrollmentId
        programId:
          type: string
          description: 'Identifier of the digital energy program. Matches the program ID from the init
            request.

            '
          example: program-flex-demand-response-001
          x-jsonld:
            '@id': programId
        status:
          type: string
          enum:
          - ACTIVE
          - PENDING
          - CANCELLED
          - SUSPENDED
          description: 'Enrollment status. ACTIVE when enrollment is active, PENDING when awaiting activation,
            CANCELLED when unenrolled, SUSPENDED when temporarily suspended.

            '
          example: ACTIVE
          x-jsonld:
            '@id': status
        enrolledAt:
          type: string
          format: date-time
          description: 'Timestamp when enrollment was confirmed and logged by BPP (ISO 8601 UTC). May
            differ from startDate if enrollment is scheduled for future activation.

            '
          example: '2024-10-15T10:35:05Z'
          x-jsonld:
            '@id': enrolledAt
        credential:
          type: object
          description: 'Signed enrollment credential issued by BPP. Contains W3C Verifiable Credential
            (https://www.w3.org/TR/vc-data-model-2.0/) proving enrollment. Returned in on_confirm response.

            '
          x-jsonld:
            '@id': credential
          allOf:
          - $ref: '#/$defs/VerifiableCredential'
        loggedAt:
          type: string
          format: date-time
          description: 'Timestamp when enrollment was logged in BPP''s audit system (ISO 8601 UTC). Used
            for audit trail and compliance.

            '
          example: '2024-10-15T10:35:05Z'
          x-jsonld:
            '@id': loggedAt
        logReference:
          type: string
          description: 'Reference identifier for the enrollment log entry. Used for audit trail, record
            keeping, and log retrieval.

            '
          example: log-enrollment-consumer-001
          x-jsonld:
            '@id': logReference
      x-owl-equivalentClass: deg:EnergyEnrollment
      $defs:
        VerifiableCredential:
          type: object
          additionalProperties: false
          description: 'Represents a W3C Verifiable Credential (https://www.w3.org/TR/vc-data-model-2.0/)
            used in enrollment flow. This is a wrapper/reference object that contains the credential data
            (as JWT or JSON-LD), metadata, and URLs. The actual credential follows W3C VC Data Model v2.0
            structure. Can be a meter ownership credential, program eligibility credential, DER certification
            credential, or program enrollment credential.

            '
          x-jsonld:
            '@type': vc:VerifiableCredential
          properties:
            credentialId:
              type: string
              description: 'Unique identifier for the credential. Used to reference credentials in verification
                and conflict checking.

                '
              example: vc-meter-ownership-001
              x-jsonld:
                '@id': credentialId
            type:
              type: string
              enum:
              - MeterOwnershipCredential
              - ProgramEligibilityCredential
              - DERCertificationCredential
              - ProgramEnrollmentCredential
              description: 'Credential type as per W3C VC Data Model v2.0. The credential must include
                ''VerifiableCredential'' in its type array plus one of these specific types. MeterOwnershipCredential
                proves meter ownership, ProgramEligibilityCredential proves eligibility, DERCertificationCredential
                proves DER certification, ProgramEnrollmentCredential represents an enrollment.

                '
              example: MeterOwnershipCredential
              x-jsonld:
                '@id': vc:type
            format:
              type: string
              enum:
              - VC-JWT
              - VC-JSON-LD
              description: 'Credential format as per W3C VC Data Model v2.0. VC-JWT for JWT-encoded credentials,
                VC-JSON-LD for JSON-LD encoded credentials. The credentialData field contains the encoded
                credential that must conform to W3C VC structure when decoded.

                '
              example: VC-JWT
              x-jsonld:
                '@id': format
            credentialData:
              type: string
              description: 'The credential data itself, typically a JWT or JSON-LD string containing the
                W3C Verifiable Credential (https://www.w3.org/TR/vc-data-model-2.0/). Contains the full
                credential including signature/proof. When decoded, must conform to W3C VC Data Model
                v2.0 structure with @context, type, credentialSubject, issuer, etc.

                '
              example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
              x-jsonld:
                '@id': credentialData
            credentialUrl:
              type: string
              format: uri
              description: 'URL where the credential can be accessed or retrieved. Used for enrollment
                credentials returned in on_confirm response. Optional for credentials in init request.

                '
              example: https://vpp-program-owner.example.com/credentials/vc:enrollment:consumer-001
              x-jsonld:
                '@id': credentialUrl
            verificationUrl:
              type: string
              format: uri
              description: 'URL for verifying the credential. Used for third-party verification of enrollment
                credentials. Optional for credentials in init request.

                '
              example: https://vpp-program-owner.example.com/verify/vc:enrollment:consumer-001
              x-jsonld:
                '@id': verificationUrl
            issuedAt:
              type: string
              format: date-time
              description: 'Timestamp when the credential was issued (ISO 8601 UTC). Maps to W3C VC issuanceDate
                property. Used for enrollment credentials in on_confirm response.

                '
              example: '2024-10-15T10:35:05Z'
              x-jsonld:
                '@id': vc:issuanceDate
            expiresAt:
              type: string
              format: date-time
              description: 'Timestamp when the credential expires (ISO 8601 UTC). Maps to W3C VC expirationDate
                property. May be null for non-expiring credentials.

                '
              example: '2025-10-15T10:35:05Z'
              x-jsonld:
                '@id': vc:expirationDate
            derId:
              type: string
              description: 'DER identifier associated with a DER certification credential. Links the credential
                to a specific DER. Only present for DERCertificationCredential type.

                '
              example: der-solar-001
              x-jsonld:
                '@id': derId
        VerifiedCredential:
          type: object
          additionalProperties: false
          description: 'Details of a credential that has been verified by the BPP. Returned in credentialVerification.verifiedCredentials
            array.

            '
          x-jsonld:
            '@type': VerifiedCredential
          properties:
            credentialId:
              type: string
              description: 'Identifier of the credential that was verified. Matches the credentialId from
                the init request.

                '
              example: vc-meter-ownership-001
              x-jsonld:
                '@id': credentialId
            status:
              type: string
              enum:
              - VERIFIED
              - FAILED
              description: 'Verification status for this specific credential. VERIFIED if credential is
                valid, FAILED if invalid or expired.

                '
              example: VERIFIED
              x-jsonld:
                '@id': status
            verifiedAt:
              type: string
              format: date-time
              description: 'Timestamp when the credential was verified by BPP (ISO 8601 UTC).

                '
              example: '2024-10-15T10:30:05Z'
              x-jsonld:
                '@id': verifiedAt
        ConflictingEnrollment:
          type: object
          additionalProperties: false
          description: 'Details of a conflicting enrollment that prevents the requested enrollment from
            proceeding. Returned in conflictCheck.conflictingEnrollments array.

            '
          x-jsonld:
            '@type': ConflictingEnrollment
          properties:
            enrollmentId:
              type: string
              description: 'Identifier of the conflicting enrollment. Used to reference the existing enrollment
                causing the conflict.

                '
              example: enrollment-existing-001
              x-jsonld:
                '@id': enrollmentId
            programId:
              type: string
              description: 'Program identifier of the conflicting enrollment. Identifies which program
                the meter/DER is already enrolled in.

                '
              example: program-flex-other-001
              x-jsonld:
                '@id': programId
            conflictReason:
              type: string
              description: 'Human-readable description of why the conflict exists. Explains the nature
                of the conflict (e.g., meter already enrolled, overlapping dates, etc.).

                '
              example: Meter umid-001 is already enrolled in program-flex-other-001 from 2024-09-01 to
                2025-09-01
              x-jsonld:
                '@id': conflictReason
            conflictType:
              type: string
              enum:
              - METER_ALREADY_ENROLLED
              - DER_ALREADY_ENROLLED
              - PROGRAM_CONFLICT
              - DATE_OVERLAP
              description: 'Type of conflict. METER_ALREADY_ENROLLED if meter is enrolled, DER_ALREADY_ENROLLED
                if DER is enrolled, PROGRAM_CONFLICT if program doesn''t allow multiple enrollments, DATE_OVERLAP
                if dates overlap.

                '
              example: METER_ALREADY_ENROLLED
              x-jsonld:
                '@id': conflictType
        UserAuthRequest:
          description: 'User authentication request - sent by BAP to BPP in init/confirm requests. Supports
            OTP-based or OAuth2/OIDC token-based authentication.

            '
          oneOf:
          - $ref: '#/$defs/OtpAuthRequest'
          - $ref: '#/$defs/OAuth2AuthRequest'
          discriminator:
            propertyName: authMethod
            mapping:
              OTP: '#/$defs/OtpAuthRequest'
              OAUTH2: '#/$defs/OAuth2AuthRequest'
              OIDC: '#/$defs/OAuth2AuthRequest'
        UserAuthResponse:
          description: 'User authentication response - returned by BPP to BAP in on_init/on_confirm responses.
            Contains verification results and extracted user identity.

            '
          oneOf:
          - $ref: '#/$defs/OtpAuthResponse'
          - $ref: '#/$defs/OAuth2AuthResponse'
          discriminator:
            propertyName: authMethod
            mapping:
              OTP: '#/$defs/OtpAuthResponse'
              OAUTH2: '#/$defs/OAuth2AuthResponse'
              OIDC: '#/$defs/OAuth2AuthResponse'
        OtpAuthRequest:
          type: object
          additionalProperties: false
          required:
          - authMethod
          - mobile
          description: 'OTP authentication request from BAP. - Init request: Send mobile number to initiate
            OTP - Confirm request: Send mobile + nguid + otp for verification

            '
          x-jsonld:
            '@type': OtpAuthRequest
          properties:
            authMethod:
              type: string
              enum:
              - OTP
              description: Authentication method. Must be "OTP".
              example: OTP
              x-jsonld:
                '@id': authMethod
            mobile:
              type: string
              description: Mobile phone number in E.164 format. Required.
              example: '+919999999999'
              x-jsonld:
                '@id': mobile
            otp:
              type: string
              description: 'One-time password entered by user. Required in confirm request (after user
                receives OTP via SMS).

                '
              example: '123456'
              x-jsonld:
                '@id': otp
            nguid:
              type: string
              description: 'Session token received from on_init response. Required in confirm request
                along with otp.

                '
              example: LQUejkRbBL9nJGQiqbComfQ242AHnbG3hnwWdHJut59jqmdJygnVHoiyDcnAUrKm
              x-jsonld:
                '@id': nguid
            utilityCustomerId:
              type: string
              description: 'Customer account identifier assigned by the utility/DISCOM. Optional - BAP
                may include if known from prior interactions.

                '
              example: CUST-123456
              x-jsonld:
                '@id': utilityCustomerId
            userType:
              type: string
              description: 'Type of user. CONSUMER for consumer, PRODUCER for producer, PROSUMER for prosumer.

                '
              example: CONSUMER
              x-jsonld:
                '@id': userType
        OtpAuthResponse:
          type: object
          additionalProperties: false
          required:
          - authMethod
          description: 'OTP authentication response from BPP. - On_init response: Returns nguid and message
            ("OTP sent") - On_confirm response: Returns verification result

            '
          x-jsonld:
            '@type': OtpAuthResponse
          properties:
            authMethod:
              type: string
              enum:
              - OTP
              description: Authentication method. Always "OTP".
              example: OTP
              x-jsonld:
                '@id': authMethod
            nguid:
              type: string
              description: 'Session token generated by BPP. Returned in on_init response. BAP must include
                this in confirm request.

                '
              example: LQUejkRbBL9nJGQiqbComfQ242AHnbG3hnwWdHJut59jqmdJygnVHoiyDcnAUrKm
              x-jsonld:
                '@id': nguid
            message:
              type: string
              description: 'Human-readable status message. e.g., "OTP sent to +91XXXXXX9999" or "Verification
                successful".

                '
              example: OTP sent to +91XXXXXX9999. Valid for 5 minutes.
              x-jsonld:
                '@id': message
            expiresAt:
              type: string
              format: date-time
              description: When OTP/nguid expires (ISO 8601 UTC).
              example: '2024-10-15T10:35:00Z'
              x-jsonld:
                '@id': expiresAt
            verified:
              type: boolean
              description: Whether OTP verification succeeded. Present in on_confirm.
              example: true
              x-jsonld:
                '@id': verified
            verifiedAt:
              type: string
              format: date-time
              description: When OTP was verified (ISO 8601 UTC).
              example: '2024-10-15T10:35:05Z'
              x-jsonld:
                '@id': verifiedAt
            utilityId:
              type: string
              description: 'Utility/DISCOM identifier returned by IdP after authentication. Identifies
                which utility the authenticated user''s account belongs to.

                '
              example: utility-example-001
              x-jsonld:
                '@id': utilityId
            utilityCustomerId:
              type: string
              description: 'Customer account identifier assigned by the utility/DISCOM. Returned by IdP
                to link the authenticated user to their utility billing account.

                '
              example: CUST-123456
              x-jsonld:
                '@id': utilityCustomerId
        OAuth2AuthRequest:
          type: object
          additionalProperties: false
          required:
          - authMethod
          - accessToken
          description: 'OAuth2/OIDC authentication request from BAP. Contains JWT tokens for BPP to validate.
            BPP extracts claims from token.

            '
          x-jsonld:
            '@type': OAuth2AuthRequest
          properties:
            authMethod:
              type: string
              enum:
              - OAUTH2
              - OIDC
              description: 'Authentication method. "OAUTH2" for access token only, "OIDC" for access +
                ID token.

                '
              example: OIDC
              x-jsonld:
                '@id': authMethod
            accessToken:
              type: string
              description: OAuth2 access token (bearer token). Required.
              example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
              x-jsonld:
                '@id': accessToken
            idToken:
              type: string
              description: 'OIDC ID token (JWT with user claims). Required when authMethod is "OIDC".

                '
              example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
              x-jsonld:
                '@id': idToken
            refreshToken:
              type: string
              description: 'OAuth2 refresh token. Optional - for long-running flows where token might
                expire mid-transaction.

                '
              example: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
              x-jsonld:
                '@id': refreshToken
        OAuth2AuthResponse:
          type: object
          additionalProperties: false
          required:
          - authMethod
          description: 'OAuth2/OIDC authentication response from BPP. Contains verification results and
            extracted user identity from token.

            '
          x-jsonld:
            '@type': OAuth2AuthResponse
          properties:
            authMethod:
              type: string
              enum:
              - OAUTH2
              - OIDC
              description: Authentication method that was used.
              example: OIDC
              x-jsonld:
                '@id': authMethod
            verified:
              type: boolean
              description: Whether token verification succeeded.
              example: true
              x-jsonld:
                '@id': verified
            verifiedAt:
              type: string
              format: date-time
              description: When token was verified (ISO 8601 UTC).
              example: '2024-10-15T10:35:05Z'
              x-jsonld:
                '@id': verifiedAt
            subject:
              type: string
              description: 'User identifier extracted from token "sub" claim.

                '
              example: user-12345
              x-jsonld:
                '@id': subject
            issuer:
              type: string
              format: uri
              description: 'OIDC issuer URL extracted from token "iss" claim.

                '
              example: https://accounts.google.com
              x-jsonld:
                '@id': issuer
            scope:
              type: string
              description: 'Scopes granted to the token (extracted from token or introspection).

                '
              example: openid profile email meter:read
              x-jsonld:
                '@id': scope
            expiresAt:
              type: string
              format: date-time
              description: When the access token expires (from "exp" claim).
              example: '2024-10-15T11:35:00Z'
              x-jsonld:
                '@id': expiresAt
            message:
              type: string
              description: Human-readable verification status message.
              example: Token verified successfully
              x-jsonld:
                '@id': message
        MeterEnrollment:
          type: object
          additionalProperties: false
          required:
          - meterId
          description: 'Meter details for enrollment in an energy program. Contains meter identifier (UMID)
            and optional utility information. Used in the meters array within orderAttributes during confirm
            request. At least one meter must be specified for enrollment to be confirmed.

            '
          x-jsonld:
            '@type': MeterEnrollment
          properties:
            meterId:
              type: string
              description: 'Unique Meter Identifier (UMID) for the meter to be enrolled. This is the primary
                identifier used by the utility/DISCOM.

                '
              example: umid-001
              x-jsonld:
                '@id': meterId
            meterNumber:
              type: string
              description: 'Physical meter number as displayed on the meter device. May differ from meterId
                which is the utility''s internal identifier.

                '
              example: MTR-123456
              x-jsonld:
                '@id': meterNumber
            utilityId:
              type: string
              description: 'Identifier of the utility/DISCOM that owns or manages the meter.

                '
              example: utility-tpddl-001
              x-jsonld:
                '@id': utilityId
            connectionType:
              type: string
              enum:
              - residential
              - commercial
              - industrial
              - agricultural
              description: 'Type of electricity connection for this meter.

                '
              example: residential
              x-jsonld:
                '@id': connectionType
            sanctionedLoad:
              type: number
              minimum: 0
              description: 'Sanctioned load capacity in kilowatts (kW) for this meter connection.

                '
              example: 5.0
              x-jsonld:
                '@id': sanctionedLoad