Snowplow Data Pipeline Governance

naftiko: "1.0.0-alpha1"

info:
  label: "Snowplow Data Pipeline Governance"
  description: >-
    Unified workflow capability for governing Snowplow behavioral data pipelines.
    Provides data engineers, analytics engineers, and data product managers with
    programmatic control over the data structure lifecycle (schema authoring,
    validation, deployment), data product (tracking plan) management, and event
    specification governance. Ensures data quality through schema validation
    before production deployment.
  tags:
    - Analytics Platform
    - Behavioral Data
    - Data Engineering
    - Data Governance
    - Event Tracking
    - Schema Management
    - Snowplow
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SNOWPLOW_JWT_TOKEN: SNOWPLOW_JWT_TOKEN
      SNOWPLOW_ORG_ID: SNOWPLOW_ORG_ID

capability:
  consumes:
    - import: snowplow-console
      location: ./shared/console-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: snowplow-governance-api
      description: "Unified REST API for Snowplow data pipeline governance and schema management."
      resources:
        - path: /v1/data-structures
          name: data-structures
          description: "Manage Snowplow event schemas"
          operations:
            - method: GET
              name: list-data-structures
              description: "List Data Structures"
              call: "snowplow-console.list-data-structures"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/data-structures/{hash}
          name: data-structure
          description: "Get a specific event schema"
          operations:
            - method: GET
              name: get-data-structure
              description: "Get Data Structure"
              call: "snowplow-console.get-data-structure"
              with:
                dataStructureHash: "rest.hash"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/data-structures/{hash}/deployments
          name: data-structure-deployments
          description: "View deployment history for an event schema"
          operations:
            - method: GET
              name: get-deployments
              description: "Get Data Structure Deployments"
              call: "snowplow-console.get-data-structure-deployments"
              with:
                dataStructureHash: "rest.hash"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/schema-validations
          name: schema-validations
          description: "Validate event schemas before deployment"
          operations:
            - method: POST
              name: validate-schema
              description: "Validate Data Structure"
              call: "snowplow-console.validate-data-structure"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/schema-deployments
          name: schema-deployments
          description: "Deploy event schemas to registry environments"
          operations:
            - method: POST
              name: deploy-schema
              description: "Deploy Data Structure"
              call: "snowplow-console.deploy-data-structure"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/data-products
          name: data-products
          description: "Manage tracking plans (data products)"
          operations:
            - method: GET
              name: list-data-products
              description: "List Data Products"
              call: "snowplow-console.list-data-products"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-data-product
              description: "Create Data Product"
              call: "snowplow-console.create-data-product"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/data-products/{id}
          name: data-product
          description: "Get a specific tracking plan"
          operations:
            - method: GET
              name: get-data-product
              description: "Get Data Product"
              call: "snowplow-console.get-data-product"
              with:
                dataProductId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: snowplow-governance-mcp
      transport: http
      description: "MCP server for AI-assisted Snowplow data pipeline governance and schema lifecycle management."
      tools:
        - name: list-data-structures
          description: "List all Snowplow event schemas (data structures) in the organization"
          hints:
            readOnly: true
            openWorld: false
          call: "snowplow-console.list-data-structures"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-data-structure
          description: "Get details of a specific Snowplow event schema by its SHA-256 hash"
          hints:
            readOnly: true
            openWorld: false
          call: "snowplow-console.get-data-structure"
          with:
            dataStructureHash: "tools.dataStructureHash"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-data-structure-deployments
          description: "Get deployment history for a Snowplow event schema across VALIDATED, DEV, and PROD environments"
          hints:
            readOnly: true
            openWorld: false
          call: "snowplow-console.get-data-structure-deployments"
          with:
            dataStructureHash: "tools.dataStructureHash"
          outputParameters:
            - type: object
              mapping: "$."

        - name: validate-data-structure
          description: "Validate a Snowplow JSON event schema before deploying to the registry"
          hints:
            readOnly: false
            destructive: false
          call: "snowplow-console.validate-data-structure"
          outputParameters:
            - type: object
              mapping: "$."

        - name: deploy-data-structure
          description: "Deploy a Snowplow event schema to a registry environment (VALIDATED, DEV, or PROD)"
          hints:
            readOnly: false
            destructive: false
          call: "snowplow-console.deploy-data-structure"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-data-products
          description: "List all Snowplow data products (tracking plans) with their event specifications"
          hints:
            readOnly: true
            openWorld: false
          call: "snowplow-console.list-data-products"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-data-product
          description: "Get details of a specific Snowplow data product (tracking plan)"
          hints:
            readOnly: true
            openWorld: false
          call: "snowplow-console.get-data-product"
          with:
            dataProductId: "tools.dataProductId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-data-product
          description: "Create a new Snowplow data product (tracking plan) for organizing event specifications"
          hints:
            readOnly: false
            destructive: false
          call: "snowplow-console.create-data-product"
          outputParameters:
            - type: object
              mapping: "$."