openapi: 3.2.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'
  /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:
  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).
      required:
      - propertyRef
      - propertyName
    SubscriptionPropertyPut:
      type: object
      properties:
        propertyName:
          type: string
        aliasName:
          type: string
        owner:
          type: string
      required:
      - propertyName
    SubscriptionPropertyUpdate:
      type: object
      properties:
        propertyRef:
          type: string
        propertyName:
          type: string
        aliasName:
          type: string
        owner:
          type: string
      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
    DeleteResult:
      type: object
      properties:
        propertyRef:
          type: string
        message:
          type: string
        status:
          type: integer
          description: HTTP-like code (200, 204, 400, 404, 500).
  parameters:
    type:
      name: type
      in: query
      required: false
      description: "Which properties to return:  \n`all` (default), `global`, or `owner`. Non-admins only see their own private when `owner`.\n"
      schema:
        type: string
        enum:
        - all
        - global
        - owner
    platformType:
      name: platformType
      in: path
      required: true
      description: Platform catalog (cloud or containers).
      schema:
        type: string
        enum:
        - cloud
        - containers
    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
    propertyRef:
      name: propertyRef
      in: path
      required: true
      description: Unique property identifier.
      schema:
        type: string