asyncapi: '2.6.0'
info:
  title: Taxonomy Service Events
  version: 1.0.0
  description: |
    Kafka events published by taxonomy-svc following CloudEvents 1.0 specification.
    All events are partitioned by tenant_id and published to Amazon MSK Serverless.

    24 event types across 7 categories:
    - Taxonomy lifecycle (9): created, updated, deleted, published, unpublished, rolled_back, locked, merged, cloned
    - Item lifecycle (5): items.upserted, item.created, item.added, item.deprecated, item.translated
    - Versioning (1): version.created
    - Bulk operations (1): bulk_import.completed
    - AI/Analytics (3): gap_analysis.completed, suggestion.pending, suggestion.approved
    - System (1): cache.invalidate
    - Seeding pipeline (4): entity.seeded, landing_page.requested, seeding.progress, entity.indexed
  contact:
    name: Epique Events & Experiences
    email: support@epiqueevents.com
  license:
    name: Proprietary

servers:
  staging:
    url: b-1.eventzr-msk.ap-south-1.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Staging)
  production:
    url: b-1.eventzr-msk-prod.ap-south-1.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Production)

defaultContentType: application/json

channels:
  eventzr.taxonomy.created.v1:
    description: Emitted when a new taxonomy is created
    publish:
      operationId: publishTaxonomyCreated
      message:
        $ref: '#/components/messages/TaxonomyCreated'

  eventzr.taxonomy.updated.v1:
    description: Emitted when a taxonomy is updated
    publish:
      operationId: publishTaxonomyUpdated
      message:
        $ref: '#/components/messages/TaxonomyUpdated'

  eventzr.taxonomy.deleted.v1:
    description: Emitted when a taxonomy is deleted
    publish:
      operationId: publishTaxonomyDeleted
      message:
        $ref: '#/components/messages/TaxonomyDeleted'

  eventzr.taxonomy.published.v1:
    description: Emitted when a taxonomy is published
    publish:
      operationId: publishTaxonomyPublished
      message:
        $ref: '#/components/messages/TaxonomyPublished'

  eventzr.taxonomy.unpublished.v1:
    description: Emitted when a taxonomy is unpublished
    publish:
      operationId: publishTaxonomyUnpublished
      message:
        $ref: '#/components/messages/TaxonomyUnpublished'

  eventzr.taxonomy.rolled_back.v1:
    description: Emitted when a taxonomy is rolled back to a previous version
    publish:
      operationId: publishTaxonomyRolledBack
      message:
        $ref: '#/components/messages/TaxonomyRolledBack'

  eventzr.taxonomy.locked.v1:
    description: Emitted when a taxonomy is locked for editing
    publish:
      operationId: publishTaxonomyLocked
      message:
        $ref: '#/components/messages/TaxonomyLocked'

  eventzr.taxonomy.merged.v1:
    description: Emitted when two taxonomies are merged
    publish:
      operationId: publishTaxonomyMerged
      message:
        $ref: '#/components/messages/TaxonomyMerged'

  eventzr.taxonomy.cloned.v1:
    description: Emitted when a taxonomy is cloned
    publish:
      operationId: publishTaxonomyCloned
      message:
        $ref: '#/components/messages/TaxonomyCloned'

  eventzr.taxonomy.items.upserted.v1:
    description: Emitted when taxonomy items are bulk upserted
    publish:
      operationId: publishItemsUpserted
      message:
        $ref: '#/components/messages/ItemsUpserted'

  eventzr.taxonomy.item.created.v1:
    description: Emitted when a single taxonomy item is created
    publish:
      operationId: publishItemCreated
      message:
        $ref: '#/components/messages/ItemCreated'

  eventzr.taxonomy.item.added.v1:
    description: Emitted when a taxonomy item is added (e.g., via suggestion approval)
    publish:
      operationId: publishItemAdded
      message:
        $ref: '#/components/messages/ItemAdded'

  eventzr.taxonomy.item.deprecated.v1:
    description: Emitted when a taxonomy item is deprecated
    publish:
      operationId: publishItemDeprecated
      message:
        $ref: '#/components/messages/ItemDeprecated'

  eventzr.taxonomy.item.translated.v1:
    description: Emitted when a taxonomy item is translated to a new locale
    publish:
      operationId: publishItemTranslated
      message:
        $ref: '#/components/messages/ItemTranslated'

  eventzr.taxonomy.version.created.v1:
    description: Emitted when a new taxonomy version snapshot is created
    publish:
      operationId: publishVersionCreated
      message:
        $ref: '#/components/messages/VersionCreated'

  eventzr.taxonomy.bulk_import.completed.v1:
    description: Emitted when a bulk import operation completes
    publish:
      operationId: publishBulkImportCompleted
      message:
        $ref: '#/components/messages/BulkImportCompleted'

  eventzr.taxonomy.gap_analysis.completed.v1:
    description: Emitted when an AI gap analysis completes
    publish:
      operationId: publishGapAnalysisCompleted
      message:
        $ref: '#/components/messages/GapAnalysisCompleted'

  eventzr.taxonomy.suggestion.pending.v1:
    description: Emitted when an AI suggestion is submitted for review
    publish:
      operationId: publishSuggestionPending
      message:
        $ref: '#/components/messages/SuggestionPending'

  eventzr.taxonomy.suggestion.approved.v1:
    description: Emitted when an AI suggestion is approved and applied
    publish:
      operationId: publishSuggestionApproved
      message:
        $ref: '#/components/messages/SuggestionApproved'

  eventzr.taxonomy.cache.invalidate.v1:
    description: Emitted to invalidate cached taxonomy data across services
    publish:
      operationId: publishCacheInvalidate
      message:
        $ref: '#/components/messages/CacheInvalidate'

components:
  messages:
    TaxonomyCreated:
      name: TaxonomyCreated
      title: Taxonomy Created
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyCreatedData'

    TaxonomyUpdated:
      name: TaxonomyUpdated
      title: Taxonomy Updated
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyUpdatedData'

    TaxonomyDeleted:
      name: TaxonomyDeleted
      title: Taxonomy Deleted
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyDeletedData'

    TaxonomyPublished:
      name: TaxonomyPublished
      title: Taxonomy Published
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyPublishedData'

    TaxonomyUnpublished:
      name: TaxonomyUnpublished
      title: Taxonomy Unpublished
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyUnpublishedData'

    TaxonomyRolledBack:
      name: TaxonomyRolledBack
      title: Taxonomy Rolled Back
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyRolledBackData'

    TaxonomyLocked:
      name: TaxonomyLocked
      title: Taxonomy Locked
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyLockedData'

    TaxonomyMerged:
      name: TaxonomyMerged
      title: Taxonomy Merged
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyMergedData'

    TaxonomyCloned:
      name: TaxonomyCloned
      title: Taxonomy Cloned
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/TaxonomyClonedData'

    ItemsUpserted:
      name: ItemsUpserted
      title: Items Upserted
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/ItemsUpsertedData'

    ItemCreated:
      name: ItemCreated
      title: Item Created
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/ItemCreatedData'

    ItemAdded:
      name: ItemAdded
      title: Item Added
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/ItemAddedData'

    ItemDeprecated:
      name: ItemDeprecated
      title: Item Deprecated
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/ItemDeprecatedData'

    ItemTranslated:
      name: ItemTranslated
      title: Item Translated
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/ItemTranslatedData'

    VersionCreated:
      name: VersionCreated
      title: Version Created
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/VersionCreatedData'

    BulkImportCompleted:
      name: BulkImportCompleted
      title: Bulk Import Completed
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/BulkImportCompletedData'

    GapAnalysisCompleted:
      name: GapAnalysisCompleted
      title: Gap Analysis Completed
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/GapAnalysisCompletedData'

    SuggestionPending:
      name: SuggestionPending
      title: Suggestion Pending
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/SuggestionPendingData'

    SuggestionApproved:
      name: SuggestionApproved
      title: Suggestion Approved
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/SuggestionApprovedData'

    CacheInvalidate:
      name: CacheInvalidate
      title: Cache Invalidate
      contentType: application/json
      headers:
        $ref: '#/components/schemas/CloudEventHeaders'
      payload:
        $ref: '#/components/schemas/CacheInvalidateData'

  schemas:
    CloudEventHeaders:
      type: object
      required: [specversion, type, source, id, time, datacontenttype]
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          description: Event type (e.g., taxonomy.created.v1)
        source:
          type: string
          description: Source service URI
          example: /eventzr/taxonomy-svc
        subject:
          type: string
          description: Subject of the event
        id:
          type: string
          format: uuid
          description: Unique event ID
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        tenantid:
          type: string
          nullable: true
          description: Tenant ID (partition key)
        correlationid:
          type: string
          description: Correlation ID for tracing
        causationid:
          type: string
          description: ID of the causing event

    TaxonomyCreatedData:
      type: object
      required: [taxonomyId, tenantId, name, displayName, scope, createdBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        displayName: { type: string }
        scope: { type: string, enum: [platform, tenant] }
        createdBy: { type: string }

    TaxonomyUpdatedData:
      type: object
      required: [taxonomyId, tenantId, name, changedFields, updatedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        changedFields: { type: array, items: { type: string } }
        updatedBy: { type: string }

    TaxonomyDeletedData:
      type: object
      required: [taxonomyId, tenantId, name, deletedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        deletedBy: { type: string }

    TaxonomyPublishedData:
      type: object
      required: [taxonomyId, tenantId, name, version, publishedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        version: { type: integer }
        publishedBy: { type: string }

    TaxonomyUnpublishedData:
      type: object
      required: [taxonomyId, tenantId, name, version, unpublishedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        version: { type: integer }
        unpublishedBy: { type: string }
        reason: { type: string }

    TaxonomyRolledBackData:
      type: object
      required: [taxonomyId, tenantId, name, fromVersion, toVersion, rolledBackBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        fromVersion: { type: integer }
        toVersion: { type: integer }
        rolledBackBy: { type: string }
        reason: { type: string }

    TaxonomyLockedData:
      type: object
      required: [taxonomyId, tenantId, name, lockedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        name: { type: string }
        lockedBy: { type: string }
        reason: { type: string }

    TaxonomyMergedData:
      type: object
      required:
        [
          targetTaxonomyId,
          sourceTaxonomyId,
          tenantId,
          targetName,
          sourceName,
          itemsMerged,
          mergedBy,
        ]
      properties:
        targetTaxonomyId: { type: string }
        sourceTaxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        targetName: { type: string }
        sourceName: { type: string }
        itemsMerged: { type: integer }
        mergedBy: { type: string }

    TaxonomyClonedData:
      type: object
      required:
        [
          originalTaxonomyId,
          clonedTaxonomyId,
          tenantId,
          originalName,
          clonedName,
          itemsCloned,
          clonedBy,
        ]
      properties:
        originalTaxonomyId: { type: string }
        clonedTaxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        originalName: { type: string }
        clonedName: { type: string }
        itemsCloned: { type: integer }
        clonedBy: { type: string }

    ItemsUpsertedData:
      type: object
      required:
        [taxonomyId, tenantId, taxonomyName, itemsCreated, itemsUpdated, totalItems, upsertedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        itemsCreated: { type: integer }
        itemsUpdated: { type: integer }
        totalItems: { type: integer }
        upsertedBy: { type: string }

    ItemCreatedData:
      type: object
      required: [taxonomyId, tenantId, taxonomyName, itemId, itemKey, itemLabel, depth, createdBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        itemId: { type: string }
        itemKey: { type: string }
        itemLabel: { type: string }
        parentKey: { type: string, nullable: true }
        depth: { type: integer }
        createdBy: { type: string }

    ItemAddedData:
      type: object
      required: [taxonomyId, tenantId, taxonomyName, itemId, itemKey, itemLabel, addedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        itemId: { type: string }
        itemKey: { type: string }
        itemLabel: { type: string }
        addedBy: { type: string }

    ItemDeprecatedData:
      type: object
      required: [taxonomyId, tenantId, taxonomyName, itemId, itemKey, deprecatedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        itemId: { type: string }
        itemKey: { type: string }
        deprecationReason: { type: string }
        replacementKey: { type: string }
        deprecatedBy: { type: string }

    ItemTranslatedData:
      type: object
      required:
        [taxonomyId, tenantId, taxonomyName, itemId, itemKey, locale, translatedLabel, translatedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        itemId: { type: string }
        itemKey: { type: string }
        locale: { type: string }
        translatedLabel: { type: string }
        translatedBy: { type: string }

    VersionCreatedData:
      type: object
      required: [taxonomyId, tenantId, taxonomyName, versionId, version, itemCount, createdBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        versionId: { type: string }
        version: { type: integer }
        reason: { type: string }
        itemCount: { type: integer }
        createdBy: { type: string }

    BulkImportCompletedData:
      type: object
      required:
        [
          taxonomyId,
          tenantId,
          taxonomyName,
          importId,
          itemsImported,
          itemsSkipped,
          errors,
          durationMs,
          importedBy,
        ]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        importId: { type: string }
        itemsImported: { type: integer }
        itemsSkipped: { type: integer }
        errors: { type: integer }
        durationMs: { type: integer }
        importedBy: { type: string }

    GapAnalysisCompletedData:
      type: object
      required:
        [
          taxonomyId,
          tenantId,
          taxonomyName,
          analysisId,
          gapsIdentified,
          suggestionsGenerated,
          aiCreditsUsed,
          requestedBy,
        ]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        analysisId: { type: string }
        gapsIdentified: { type: integer }
        suggestionsGenerated: { type: integer }
        aiCreditsUsed: { type: integer }
        requestedBy: { type: string }

    SuggestionPendingData:
      type: object
      required: [tenantId, taxonomyId, taxonomyName, suggestionId, confidence, source]
      properties:
        tenantId: { type: string, nullable: true }
        taxonomyId: { type: string }
        taxonomyName: { type: string }
        suggestionId: { type: string }
        suggestionType: { type: string }
        suggestedKey: { type: string }
        suggestedLabel: { type: string }
        suggestedItem: { type: object }
        confidence: { type: number }
        source: { type: string, enum: [ai, user, import] }
        requestedBy: { type: string }

    SuggestionApprovedData:
      type: object
      required: [taxonomyId, tenantId, taxonomyName, suggestionId, itemKey, itemLabel, approvedBy]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        suggestionId: { type: string }
        itemKey: { type: string }
        itemLabel: { type: string }
        approvedBy: { type: string }

    CacheInvalidateData:
      type: object
      required: [tenantId, cacheKeys, reason]
      properties:
        taxonomyId: { type: string }
        tenantId: { type: string, nullable: true }
        taxonomyName: { type: string }
        cacheKeys: { type: array, items: { type: string } }
        reason: { type: string }
