alibaba / alibaba/UnifiedModel

[RFC] Project Restructuring for Multi-Vendor Ecosystem Participation

Open
#7 9 comments 2 reactions 1 assignee Claimed by @qiansheng91 View on GitHub
bug documentation enhancement rfc-accepted
Dominant language
Go
Stars
383
Forks
60
PR merge metrics
No merged PRs in 30d

Description

### Summary

UModel's architecture — the `GraphStore` interface, `RegisterProvider` pattern, OpenAPI 3.1 contract, and MCP tool schema — is already well-designed for vendor neutrality. However, the current repository layout, default configurations, SDK code generation, and documentation are tightly coupled to a single cloud vendor's product names (SLS, Aliyun Prometheus, Ladybug). This creates an unintentional barrier for contributors from other cloud providers, observability vendors, and enterprise users who want to adopt UModel as a shared semantic layer.

This RFC proposes a series of structural changes to make UModel truly welcoming to multi-vendor participation, without removing any existing functionality.

### Motivation

UModel's stated vision is a "vendor-neutral semantic runtime for enterprise AI, data governance, and operational intelligence." To fulfill this vision, the project needs contributions from across the observability ecosystem — Prometheus users, Grafana users, OpenTelemetry adopters, AWS/GCP/Azure shops, and independent ISVs.

Currently, a first-time contributor who runs `make quickstart` encounters:

- `schemas/core/storage/` containing 4 Alibaba Cloud-specific schemas and only 1 generic one
- `DefaultProviderType = ProviderTypeLadybug` where Ladybug is not publicly available
- SDK code generation producing Alibaba Cloud-specific types by default
- Documentation examples using SLS and Aliyun Prometheus as primary references

These signals, while unintentional, communicate "this is an Alibaba Cloud tool" rather than "this is an industry-wide semantic layer that Alibaba Cloud happens to use."

### Proposed Changes

#### 1. Schema Directory Restructuring

```
schemas/core/storage/
logstore.schema.yaml # Generic log storage
metricstore.schema.yaml # Generic metric storage
prometheus_remote.schema.yaml # Generic Prometheus-compatible storage
external_storage.schema.yaml # Generic external storage (already exists)

schemas/contrib/aliyun/ # Alibaba Cloud extensions
sls_logstore.schema.yaml
sls_metricstore.schema.yaml
sls_entitystore.schema.yaml
aliyun_prometheus.schema.yaml

schemas/contrib/aws/ # Placeholder — call for AWS contributors
schemas/contrib/gcp/ # Placeholder — call for GCP contributors
```

The `contrib/` directory signals: "Your cloud's storage can be a first-class citizen here."

#### 2. Change Default GraphStore Provider

```go
// Current
const DefaultProviderType = ProviderTypeLadybug

// Proposed
const DefaultProviderType = ProviderTypeFileMemory
```

Ladybug provider already uses build tags (`//go:build ladybug`). This change simply makes the default build work without any proprietary dependency, while Ladybug users add `-tags ladybug` explicitly.

#### 3. SDK Code Generation: Exclude Contrib by Default

Add a `--with-contrib` flag to the SDK code generation toolchain. The default `make generate` produces only core schema types. `make generate --with-contrib aliyun` explicitly includes vendor extensions.

#### 4. Documentation: Vendor-Neutral Quickstart Experience

- Replace SLS/Aliyun Prometheus documentation examples with Prometheus (open-source) + Loki + ELK equivalents
- Move Alibaba Cloud-specific examples to `docs/en/contrib/aliyun/`
- Add a `docs/en/contrib/README.md` explaining how to add vendor-specific documentation

#### 5. Add OpenTelemetry Semantic Convention Mapping

New file `docs/en/otel-mapping.md`:

| UModel Concept | OpenTelemetry Equivalent |
|---------------|-------------------------|
| EntitySet | Instrumentation Scope |
| Entity (domain, type, id) | Resource Attributes (service.namespace, service.name, service.instance.id) |
| Relation (topo edge) | Span Link / Service Map Edge |
| Field constraints | Semantic Convention attributes |

This document is the bridge between UModel and the CNCF observability ecosystem.

### Non-Goals

- **Not** removing Alibaba Cloud support. All existing functionality is preserved in `schemas/contrib/aliyun/`.
- **Not** changing any public API, CLI, or MCP contract.
- **Not** proposing governance changes in this RFC (that's a separate discussion).
- **Not** asking Alibaba to open-source Ladybug. The alternative `file.memory` default is sufficient for the open-source distribution.

### Alternatives Considered

**A. Do nothing.** The project continues to grow within the Alibaba Cloud ecosystem but struggles to attract maintainers from other organizations.

**B. Fork into a separate "OpenUModel" project.** Creates fragmentation and loses the Alibaba Cloud engineering resources that are currently the project's greatest strength.

**C. Keep schemas in core but add a naming convention.** `aws_cloudwatch.schema.yaml` and `gcp_cloudlogging.schema.yaml` would sit alongside `sls_logstore.schema.yaml` in `schemas/core/storage/`, making it crowded and harder to tell what's "core" vs "vendor."

### Next Steps

The implementation approach and division of work should be discussed before any PRs are submitted. The changes span specification work, engineering work, and documentation — a collaborative approach where different contributors drive different pieces would be ideal. Looking forward to discussion and feedback.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.