数据结构管理工具

模式存储库示例

用于管理的演示存储库 扫雪机 数据结构使用 扫雪机CLI 和 扫雪机MCP，通过以下方式自动生成代码 雪型.

仓库结构

data-structures/
  common/
    user.yaml              # Entity: user context
  content/
    article.yaml           # Entity: article context
    author.yaml            # Entity: author context
    paywall_view.yaml      # Event: user hits a paywall
  commerce/
    product.yaml           # Entity: product context
    add_to_cart.yaml       # Event: user adds item to cart

scripts/
  clean-generated.mjs      # Post-generation cleanup script

snowtype.config.json        # Snowtype configuration
package.json

模式按域组织：

• 普通/ --跨域使用的共享实体（如用户）
• 内容/ --文章和作者实体，以及与内容相关的活动
• 商业/ --产品实体和电子商务活动

架构格式

所有模式都遵循 Snowplow CLI数据结构格式:

• apiVersion: v1, resourceType: data-structure
• meta.schemaType 要么 entity （附于事件的上下文）或 event （可追踪的动作）
• data.self.version 用途 SchemaVer (MODEL-REVISION-ADDITION)

使用SchemaVer进行版本控制

Snowplow使用三部分版本控制方案：

CI/CD工作流程

PR验证(validate-schemas.yml)

对每个接触到的pull请求运行 data-structures/**。使用Snowplow CLI验证所有模式，在合并之前捕获结构错误。

生成和发布(generate-and-release.yml)

运行推送 main.使用Snowtype从模式生成类型安全的TypeScript跟踪函数，然后将其作为GitHub Release工件发布。

工作流程包括一个清理步骤(scripts/clean-generated.mjs)从Snowtype输出中删除不正确的函数——实体模式只能得到 create* 函数和事件模式只能获得 track* 功能。

演示：模式版本凹凸

要练习SchemaVer版本控制，请执行以下操作：

ADDITION凸起（编辑更改） --更新 product.yaml:

1. 改变 self.version 从 1-0-0 到 1-0-1
2. 改进字段描述（无结构变化）
3. 验证： snowplow-cli validate data-structures --data-structures-path ./data-structures

型号颠簸（断裂变化） --更新 add_to_cart.yaml:

1. 添加一个新的必填字段（例如。 cartId 随着 type: string, format: uuid)
2. 添加 cartId 到 required 数组
3. 改变 self.version 从 1-0-0 到 2-0-0 （必填字段=中断更改）
4. 验证以确认架构在结构上有效

注： Snowplow CLI对已部署的注册表强制执行版本沿袭。在没有BDP控制台的仅本地上下文中，您将看到 "Version 1-0-0 not deployed. Cannot skip versions"这是意料之中的——结构验证仍然通过。在真实的工作流程中， 1-0-0 将首先部署。

本地开发

# Install dependencies
npm install

# Validate schemas (requires snowplow-cli)
snowplow-cli validate data-structures --data-structures-path ./data-structures

# Generate tracking code and clean up
npm run build