openapi: 3.1.0
info:
  title: Kubex – Subscriptions Properties API
  version: "1.0.0"
  description: |
    Catalog of recommendation properties available for use in subscription filters (`propertyReferences`).
    Separate catalogs exist per platform type; alias without platform behaves like cloud.  
    Admins can manage global/private properties; non-admins can manage only their private ones.
servers:
  - url: https://{host}
    variables: { host: { default: api.example.com } }
tags:
  - name: Subscriptions Properties
paths:
  /subscriptions/{platformType}/properties:
    get:
      tags: [Subscriptions Properties]
      operationId: listSubscriptionProperties
      summary: List properties in the platform catalog
      parameters:
        - $ref: '#/components/parameters/platformType'
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/owner'
      responses:
        '200':
          description: Property list
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SubscriptionProperty' }
        '400': { description: Bad Request (e.g. non-admin querying another user with `type=owner`). }
        '401': { description: Authentication failed. }
        '404': { description: Not found. }
        '500': { description: Server error. }

    post:
      tags: [Subscriptions Properties]
      operationId: addSubscriptionProperties
      summary: Add properties (bulk)
      description: |
        Adds one or more properties to the platform catalog.  
        Bulk add is all-or-nothing; a single error rolls back the set.  
        `propertyName` must be unique within the catalog; `aliasName` uniqueness depends on scope
        (global vs private). Platform-specific properties must be added to their matching catalog.
      parameters:
        - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items: { $ref: '#/components/schemas/SubscriptionPropertyCreate' }
      responses:
        '200':
          description: Created properties
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SubscriptionProperty' }

    put:
      tags: [Subscriptions Properties]
      operationId: replaceSubscriptionProperties
      summary: Replace existing properties (bulk PUT)
      description: |
        Replaces parameters for existing properties.  
        You must supply all parameters required by each property.  
        Admins may promote private→global by setting `owner: ""`. Bulk edit is all-or-nothing.
      parameters:
        - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items: { $ref: '#/components/schemas/SubscriptionPropertyUpdate' }
      responses:
        '200':
          description: Updated properties
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SubscriptionProperty' }

    delete:
      tags: [Subscriptions Properties]
      operationId: deleteSubscriptionProperties
      summary: Delete properties (bulk)
      description: |
        Deletes a collection of properties by ID.  
        Each delete is independent; errors for some IDs do not affect others.  
        Properties referenced by subscriptions cannot be deleted.
      parameters:
        - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  propertyRef: { type: string }
                required: [propertyRef]
      responses:
        '204': { description: No Content (all attempted deletes processed).}
        '200':
          description: Partial failures (per-item status)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeleteResult'
        '401': { description: Authentication failed. }
        '404': { description: Not found. }
        '500': { description: Server error. }

  /subscriptions/{platformType}/properties/{propertyRef}:
    get:
      tags: [Subscriptions Properties]
      operationId: getSubscriptionProperty
      summary: Get a property by ID
      parameters:
        - $ref: '#/components/parameters/platformType'
        - $ref: '#/components/parameters/propertyRef'
      responses:
        '200':
          description: Property
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SubscriptionProperty' }
        '404': { description: Not found. }

    put:
      tags: [Subscriptions Properties]
      operationId: replaceSubscriptionProperty
      summary: Replace a property by ID (full PUT)
      description: "Admins can promote private→global (`owner: \"\"`); non-admins can only set `owner` to themselves."
      parameters:
        - $ref: '#/components/parameters/platformType'
        - $ref: '#/components/parameters/propertyRef'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SubscriptionPropertyPut' }
      responses:
        '200':
          description: Updated property
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SubscriptionProperty' }
        '400': { description: Validation error. }
        '404': { description: Not found. }

    delete:
      tags: [Subscriptions Properties]
      operationId: deleteSubscriptionProperty
      summary: Delete a property by ID
      description: Returns 204 on success; 404 if not found; if referenced by a subscription, returns `propertyRef`, `message`, and `status`.
      parameters:
        - $ref: '#/components/parameters/platformType'
        - $ref: '#/components/parameters/propertyRef'
      responses:
        '204': { description: No Content. }
        '404': { description: Not found. }
        '200':
          description: In-use error payload
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DeleteResult' }

  # Back-compat alias (acts like /subscriptions/cloud/properties)
  /subscriptions/properties:
    get:
      tags: [Subscriptions Properties]
      operationId: listSubscriptionPropertiesDefaultPlatform
      summary: List properties (alias of cloud)
      responses:
        '200':
          description: Property list
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SubscriptionProperty' }

components:
  parameters:
    platformType:
      name: platformType
      in: path
      required: true
      description: Platform catalog (cloud or containers).
      schema: { type: string, enum: [cloud, containers] }
    propertyRef:
      name: propertyRef
      in: path
      required: true
      description: Unique property identifier.
      schema: { type: string }
    type:
      name: type
      in: query
      required: false
      description: |
        Which properties to return:  
        `all` (default), `global`, or `owner`. Non-admins only see their own private when `owner`.
      schema: { type: string, enum: [all, global, owner] }
    owner:
      name: owner
      in: query
      required: false
      description: Username to combine with `type=owner` (admins can query any user; non-admins only themselves).
      schema: { type: string }

  schemas:
    SubscriptionProperty:
      type: object
      properties:
        propertyRef: { type: string, description: "Unique referenced ID." }
        propertyName:
          type: string
          description: >
            Recommendation element name (must exist in the applicable Recommendations response schema).
        aliasName: { type: string, description: "Display alias (scope-unique per rules)." }
        owner:
          type: string
          description: 'Empty = global; otherwise username (private).'  # includes F-filterable indicator in docs
      required: [propertyRef, propertyName]
    SubscriptionPropertyCreate:
      type: object
      properties:
        propertyName: { type: string }
        aliasName: { type: string }
        owner:
          type: string
          description: 'Omit or empty for global (admins only); otherwise username for private.'
      required: [propertyName]
    SubscriptionPropertyUpdate:
      type: object
      properties:
        propertyRef: { type: string }
        propertyName: { type: string }
        aliasName: { type: string }
        owner: { type: string }
      required: [propertyRef, propertyName]
    SubscriptionPropertyPut:
      type: object
      properties:
        propertyName: { type: string }
        aliasName: { type: string }
        owner: { type: string }
      required: [propertyName]
    DeleteResult:
      type: object
      properties:
        propertyRef: { type: string }
        message: { type: string }
        status:
          type: integer
          description: 'HTTP-like code (200, 204, 400, 404, 500).'