[RFC] Project Restructuring for Multi-Vendor Ecosystem Participation

[Alyyyyyy]

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

// 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.

[qiansheng91]

Thanks for putting this RFC together. The problem statement is sharp, and the direction matches what I see in the repository today: the architecture is already designed for vendor-neutral participation, but parts of the repository still send a more Alibaba Cloud-specific signal than intended.

Overall, I agree with the goal: UnifiedModel should read as an industry-level semantic layer that Alibaba Cloud also uses, not as an Alibaba Cloud-only tool.

Before we move into implementation PRs, I'd like to settle a few details in this issue so we do not end up with a half-old / half-new repository structure.

1. Schema Directory Restructuring

This is the largest-impact change.

Moving schema paths can affect SDK codegen output, documentation snippets, example manifests, and any downstream users that reference schema paths or schema URLs directly.

A few questions:

• What migration window do you propose? For example: temporary aliases/symlinks, a make migrate-schema-paths helper, or a hard cut documented in the changelog?
• For naming, I'm open to contrib/, but I'd also like to discuss vendor/. contrib/ signals extension ecosystem participation, while vendor/ can read more neutral in the cloud/provider context, though it may also be confused with vendored dependencies in some OSS projects.
• I would avoid empty aws/ and gcp/ placeholder directories for now. They tend to become stale. My preference is to add a schemas/contrib/README.md first, explaining how to contribute a vendor pack, and create provider directories only when real schemas are added.

2. Default GraphStore

I agree with changing the public default away from local.ladybug.

One clarification from the current repo state: make dev already defaults to file.memory, and make quickstart currently runs with memory. However, the Go DefaultProviderType is still ProviderTypeLadybug, and some docs/help text still reflect that older assumption.

That is a real UX issue and can be fixed independently of the larger RFC.

Besides changing the constant, we should align:

• cmd/umodel-server and cmd/umodel-mcp flag help text
• related docs
• tests that assume the old default
• any quickstart/dev documentation that describes the default provider path

If useful, I can take this as a small first maintainer-side PR.

3. SDK Codegen and Contrib Types

The --with-contrib direction makes sense.

Two design points need to be decided before implementation:

• Should make generate continue emitting Aliyun types for one compatibility window, with deprecation notes, before switching to core-only generation?
• Where should generated contrib types live? For example, under a contrib package path in the existing module, or as a separate generated module/package?

I want to avoid breaking downstream Go/Java/Python consumers without a clear migration path.

4. Vendor-Neutral Documentation

I strongly support moving SLS / Aliyun Prometheus examples under docs/{en,zh}/contrib/aliyun/.

One request: let's not delete the existing examples before replacement OSS examples exist. A documentation tree that says "see the SLS example" after the example has been removed would be worse than the current state.

Please propose whether you prefer:

1. one PR that moves the current Aliyun examples and adds OSS replacements in the same change, or
2. two PRs: first move existing examples into contrib, then add Prometheus OSS / Loki / ELK equivalents.

Also, any documentation change needs to keep English and Chinese docs aligned: docs/en/** and docs/zh/**.

5. OpenTelemetry Mapping

This is probably the lowest-risk, highest-signal first step.

The mapping table is a good start, but I'd like the document to include at least one complete example: an instrumented service represented as OTel resource/span/log signals, and the corresponding UModel entities and relations.

That would make the document operational, not just terminological.

Suggested PR Order

I'd suggest a slightly different order from the RFC, moving low-risk / high-signal changes first:

1. OpenTelemetry mapping document
2. Default GraphStore + CLI/help/docs alignment
3. SDK codegen flag with backward-compatible defaults
4. Schema restructuring with an explicit migration plan
5. Documentation reorganization + OSS replacement examples

This keeps the most invasive schema migration last, after the project already reads more clearly as a multi-vendor semantic layer.

If you can reply here with your proposal for the schema migration window, the naming choice (contrib vs vendor), and whether the documentation move should be one PR or split into move-first / replace-next PRs, I'd label this RFC as rfc-accepted and we can start with the OTel mapping PR in the revised sequence.

Thanks again. This is exactly the kind of structural feedback the project needs at this stage.

[Alyyyyyy]

Thanks for the thorough review. The revised PR order — low-risk, high-signal items first — makes sense.

On the three open questions:

1. Naming: contrib/ over vendor/. OpenTelemetry and Prometheus both use contrib/ for community extensions. Consistency with CNCF conventions lowers the learning curve for new contributors. vendor/ carries a conflicting meaning in Go (vendored dependencies), which could confuse contributors coming from the SDK codegen path. Agree on skipping empty placeholder directories — a schemas/contrib/README.md explaining how to contribute a vendor pack is a better invitation.

2. Migration window: one-release soft transition. Symlinks at old paths with deprecation notices for one release cycle, then a hard cut documented in the changelog. Same pattern OpenTelemetry used for the HTTP semantic convention stabilization.

3. Documentation: two PRs. Move existing Aliyun examples into docs/{en,zh}/contrib/aliyun/ first, then add OSS replacement examples in a follow-up PR. Easier to review and keeps en/zh naturally aligned.

On the OTel mapping document — a specification-level mapping with a worked example is a good first step. Happy to collaborate on that with everyone.

Once the above is settled, looking forward to the rfc-accepted label and getting started.

[qiansheng91]

Thanks for the follow-up. I agree with the overall direction and with the revised implementation sequence.

A few decisions and one clarification from my side:

1. Schema layering

I agree with moving Alibaba Cloud-specific schemas under schemas/contrib/aliyun/.

I also agree that we should not create empty aws/ or gcp/ placeholder directories yet. A schemas/contrib/README.md that explains how to contribute vendor packs is the better first step. Provider directories should be added when real schemas are contributed.

2. GraphStore default

I want to clarify one point about Ladybug.

The local.ladybug provider here refers to LadybugDB/ladybug, which is an open-source graph database, not an Alibaba Cloud-only or proprietary backend. So we should avoid describing Ladybug as unavailable, vendor-private, or Alibaba-only.

That said, I agree with changing the default OSS path away from local.ladybug. The reason is setup friction, not vendor ownership: local.ladybug requires an explicit build tag and a local Ladybug runtime, while memory and file.memory provide a zero-friction path for new users and contributors.

The desired positioning should be:

• memory: quickstart and disposable local demos
• file.memory: default local development and persistent OSS path
• local.ladybug: optional open-source Ladybug-backed provider for users who explicitly enable it

So I support updating the default constant, CLI help text, MCP help text, and docs accordingly, while keeping Ladybug as a fully supported provider.

3. SDK codegen

I agree with the --with-contrib direction. We should still keep a compatibility window so existing downstream users are not broken abruptly. The exact package layout for generated contrib types should be decided before implementation.

4. Documentation

I agree with the two-PR approach:

1. first move existing Aliyun examples into docs/{en,zh}/contrib/aliyun/
2. then add OSS replacement examples such as Prometheus, Loki, and ELK

English and Chinese docs should stay aligned.

5. OpenTelemetry mapping

I agree this should be the first implementation PR. The mapping should include a complete worked example, not only a terminology table.

With the Ladybug clarification above, I am comfortable accepting this RFC and starting with the OpenTelemetry mapping PR.

[Alyyyyyy]

PR 1 (OTel mapping document) submitted at #14.

This is a lightweight discussion draft — a concept bridge rather than a schema design. Prepared by CAICT as a strawman proposal for community discussion. An extended version with worked examples is available for any future workshop.

@qiansheng91 — looking forward to the GraphStore PR (step 2). Happy to coordinate on steps 3-5 once the sequence is rolling.