# ---Notes by KaizenX -----
# ---Endpoints mirror BPS structure, with an explicit profile query (defaulting to the AIPS profile IRI) and AIPS artifactType enums.
# ---All DPP responses are JSON-LD. Lite vs Full is controlled by ?lite= and authorization.
# ---The schema here is informative for API shape; authoritative validation remains the JSON Schema + SHACL artifacts available as part of the spec.

openapi: 3.1.0

info:
  title: AIPS Digital Product Passport API
  version: "0.1"
  description: |
    REST API for retrieving AI Product Digital Product Passports (DPPs),
    built on the BPS DPP Core with the AIPS DPP profile.

    - All passport responses MUST be application/ld+json.
    - Passports are product-centric and bind an immutable AI Product version.
    - effectiveRiskTierInline is mandatory.
    - Behavioral classifications align with the Kivanura Agent Ontology.
    - Profiles MUST include:
      https://aips.kivanura.org/spec/aips/dpp/0.1/

servers:
  - url: https://{host}/api/v1
    variables:
      host:
        default: aips.kivanura.org

tags:
  - name: DPP
    description: Retrieve AIPS Digital Product Passports
  - name: Discovery
    description: Search or browse passports
  - name: Policy
    description: Revocation and lifecycle state
  - name: Health
    description: Service health

paths:

  /dpp/{productId}:
    get:
      tags: [DPP]
      summary: Get AI Product passport (Lite or Full)
      operationId: getPassport
      parameters:
        - $ref: '#/components/parameters/productId'
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/lite'
        - $ref: '#/components/parameters/profile'
      responses:
        '200':
          description: AIPS DPP Passport
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/AipsDppPassport'
        '304':
          description: Not Modified
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '500':
          $ref: '#/components/responses/ServerError'

  /dpp/{productId}/status:
    get:
      tags: [Policy]
      summary: Get passport lifecycle status
      operationId: getPassportStatus
      parameters:
        - $ref: '#/components/parameters/productId'
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/profile'
      responses:
        '200':
          description: Current lifecycle state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PassportStatus'

  /dpp/search:
    get:
      tags: [Discovery]
      summary: Search AI Product passports
      operationId: searchPassports
      parameters:
        - name: issuer
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [Valid, Revoked, Superseded]
        - name: keyword
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/profile'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 25
      responses:
        '200':
          description: Search results (Lite previews)
          content:
            application/ld+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AipsDppPassportLitePreview'

  /healthz:
    get:
      tags: [Health]
      summary: Liveness probe
      responses:
        '204':
          description: OK

components:

  parameters:

    productId:
      name: productId
      in: path
      required: true
      schema:
        type: string

    version:
      name: version
      in: query
      required: false
      schema:
        type: string

    lite:
      name: lite
      in: query
      required: false
      schema:
        type: boolean
        default: false

    profile:
      name: profile
      in: query
      required: false
      schema:
        type: string
        default: https://aips.kivanura.org/spec/aips/dpp/0.1/

  responses:

    BadRequest:
      description: Bad request

    Unauthorized:
      description: Authentication required

    Forbidden:
      description: Insufficient permissions

    NotFound:
      description: Resource not found

    Gone:
      description: Passport revoked or deleted

    ServerError:
      description: Internal server error

  schemas:

    PassportStatus:
      type: object
      properties:
        status:
          type: string
          enum: [Valid, Revoked, Superseded]
        reason:
          type: string

    EffectiveRiskTierInline:
      type: object
      required:
        - tier
        - computationTimestamp
        - escalationRequired
      properties:
        tier:
          type: string
          enum: [R0, R1, R2, R3, R4]
        computationTimestamp:
          type: string
          format: date-time
        computationMethod:
          type: string
        escalationRequired:
          type: boolean

    BehavioralSummaryInline:
      type: object
      properties:
        topologyScope:
          type: string
          format: uri
        authorityScope:
          type: string
          format: uri
        autonomyLevel:
          type: string
          format: uri
        controlMode:
          type: string
          format: uri

    AipsDppPassport:
      type: object
      required:
        - "@context"
        - type
        - profiles
        - subject
        - issuer
        - issuedAt
        - status
        - contentHash
        - signature
        - effectiveRiskTierInline
      properties:
        "@context":
          type: object
        type:
          type: string
          const: dpp:Passport
        profiles:
          type: array
          items:
            type: string
            format: uri
        subject:
          type: string
        issuer:
          type: string
        issuedAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [Valid, Revoked, Superseded]
        contentHash:
          type: string
          description: Hash of the AI Product publish projection
        signature:
          type: string

        effectiveRiskTierInline:
          $ref: '#/components/schemas/EffectiveRiskTierInline'

        behavioralSummaryInline:
          $ref: '#/components/schemas/BehavioralSummaryInline'

    AipsDppPassportLitePreview:
      type: object
      properties:
        subject:
          type: string
        issuer:
          type: string
        status:
          type: string
        issuedAt:
          type: string
          format: date-time
        effectiveRiskTierInline:
          $ref: '#/components/schemas/EffectiveRiskTierInline'