# S-UI Subscription Formats Explained: Link vs JSON vs Clash

> Understand S_UI subscription formats: Link, JSON, and Clash. Discover which format best suits your proxy client needs for efficient configuration.

- Repository: [Alireza Ahmadi/s-ui](https://github.com/alireza0/s-ui)
- Tags: deep-dive
- Published: 2026-05-22

---

**S-UI provides three distinct subscription formats—Link, JSON, and Clash—each optimized for different proxy clients, ranging from simple URI lists to full Sing-Box configurations.**

The [alireza0/s-ui](https://github.com/alireza0/s-ui) subscription service generates user-specific proxy configurations through a unified backend that formats data differently based on the target client ecosystem. Understanding these S-UI subscription formats ensures you select the appropriate output for your specific proxy application, whether you are running Sing-Box, Clash-Meta, or a basic V2Ray client.

## The Three Subscription Formats

S-UI serves subscription data from the `/sub/` endpoint (default port `2096` as defined in [`service/setting.go`](https://github.com/alireza0/s-ui/blob/main/service/setting.go)) in three mutually exclusive representations. Each format is generated by specialized service logic within the repository.

### Link Format

The **Link** format returns a plain-text file where each line contains a single proxy URI. These URIs follow standard schemes such as `vmess://`, `trojan://`, or `shadowsocks://`, making the format universally compatible with any client that imports "URL-list" subscriptions.

According to the source code in [`sub/linkService.go`](https://github.com/alireza0/s-ui/blob/main/sub/linkService.go), the `LinkService.GetLinks` method constructs this output. The implementation optionally enriches responses with client metadata via `addClientInfo`, but the core output remains strictly newline-separated proxy URLs without additional JSON structure or routing rules.

### JSON Format (Sing-Box)

The **JSON** format emits a complete Sing-Box-compatible configuration object containing fully populated `inbounds`, `outbounds`, routing rules, and DNS settings. This is the most comprehensive format, preserving every advanced option including TLS parameters, transport configurations, and protocol-specific settings.

In [`sub/jsonService.go`](https://github.com/alireza0/s-ui/blob/main/sub/jsonService.go), the `JsonService.GetJson` method merges user outbound links into the `defaultJson` base template. This process constructs a runnable configuration file that Sing-Box can consume directly without further modification.

### Clash Format

The **Clash** format produces a JSON structure compatible with Clash, Clash-Meta, and Clash-X clients. While it uses JSON syntax like the Sing-Box format, it specifically includes a `proxies` array and `proxy-groups` selectors required by the Clash ecosystem.

Notably, this format is generated by the same `JsonService.GetJson` function when the request includes `format=clash`. The method actively filters the Sing-Box configuration, stripping fields that Clash does not recognize (such as specific `mtls` settings or certain `transport` options) while retaining only Clash-compatible proxy definitions and group structures.

## Technical Comparison: Data Structure and Compatibility

When choosing between S-UI subscription formats, consider three primary technical distinctions:

**Data Richness**
- **JSON** carries the complete feature set: custom DNS servers, route rules, and inbound listeners.
- **Clash** maintains full proxy object definitions but drops Sing-Box-specific extensions.
- **Link** provides only the connection URI, containing zero metadata about routing or DNS.

**Client Compatibility**
- Use **Link** for mobile applications and lightweight clients that expect simple URI imports.
- Use **JSON** exclusively for Sing-Box deployments requiring advanced routing logic.
- Use **Clash** when connecting to Clash-based clients that rely on proxy group selectors.

**Payload Size**
- **Link** files scale linearly with outbound count (one line per proxy) but remain text-compact.
- **JSON** files are the largest due to complete object hierarchies for every configuration aspect.
- **Clash** files occupy a middle ground, containing structured proxy objects plus group definitions.

## Accessing Subscription Formats via API

S-UI exposes all formats through the same HTTP endpoint, differentiating output via the `format` query parameter. The following commands demonstrate fetching a subscription named `mySub` from a server running on `HOST:2096`:

```bash

# Link format (default behavior)

curl -s http://HOST:2096/sub/mySub > subscription.txt

# Sing-Box JSON format

curl -s "http://HOST:2096/sub/mySub?format=json" > sing-box.json

# Clash-compatible format

curl -s "http://HOST:2096/sub/mySub?format=clash" > clash.json

```

The Link response contains only URI strings (e.g., `vmess://eyJhZGQiOi...`), while the JSON responses return structured configuration objects appropriate for their respective clients.

## Core Implementation Architecture

The subscription system relies on two primary service files:

- **[`sub/linkService.go`](https://github.com/alireza0/s-ui/blob/main/sub/linkService.go)**: Implements `LinkService.GetLinks` for URI generation and optional client info injection.
- **[`sub/jsonService.go`](https://github.com/alireza0/s-ui/blob/main/sub/jsonService.go)**: Houses `JsonService.GetJson` for both Sing-Box and Clash JSON generation, utilizing the `defaultJson` template as a foundation.

The service configuration in [`service/setting.go`](https://github.com/alireza0/s-ui/blob/main/service/setting.go) defines the default subscription path (`/sub/`) and listening port (`2096`), as referenced in the project's [`README.md`](https://github.com/alireza0/s-ui/blob/main/README.md) feature documentation.

## Summary

- **Link format** provides minimalist, newline-separated proxy URIs suitable for universal client import, implemented in [`sub/linkService.go`](https://github.com/alireza0/s-ui/blob/main/sub/linkService.go).
- **JSON format** delivers complete Sing-Box configurations with full routing and DNS support via `JsonService.GetJson` in [`sub/jsonService.go`](https://github.com/alireza0/s-ui/blob/main/sub/jsonService.go).
- **Clash format** filters the Sing-Box output into Clash-compatible structures with `proxies` arrays and `proxy-groups`, sacrificing Sing-Box-specific features for Clash ecosystem compatibility.
- All formats share the same `/sub/` endpoint and backend user management logic, differing only in the final serialization layer.

## Frequently Asked Questions

### Which S-UI subscription format should I use with Sing-Box?

Use the **JSON** format. As implemented in [`sub/jsonService.go`](https://github.com/alireza0/s-ui/blob/main/sub/jsonService.go), this output provides the complete configuration structure—including `inbounds`, `outbounds`, and routing rules—that Sing-Box requires to function. The Link format would require manual configuration of routing logic, while the Clash format strips Sing-Box-specific features.

### Why does the Clash format lack some transport options?

The **Clash** format intentionally filters out Sing-Box-specific fields because the Clash ecosystem does not recognize them. When `JsonService.GetJson` receives `format=clash`, it strips advanced parameters like custom `mtls` configurations and certain `transport` settings, retaining only the subset of fields defined in the Clash schema to ensure client compatibility.

### Can I use the Link format with Clash clients?

Yes, most modern Clash variants (including Clash-Meta) can import the **Link** format, but with significant limitations. While Clash can parse individual proxy URIs from the plain-text list, you lose the benefit of `proxy-groups` and automatic selectors that the **Clash** JSON format provides. For full Clash functionality, use the dedicated Clash format endpoint.

### How do I retrieve my subscription via command line?

Use `curl` to request the specific format via the `/sub/` endpoint. The default request returns Link format, while appending `?format=json` or `?format=clash` returns the respective configuration types. Ensure you target port `2096` (or your configured subscription port defined in [`service/setting.go`](https://github.com/alireza0/s-ui/blob/main/service/setting.go)) and include your subscription name in the path.