dandri/simplex-chat
1
0 Fork 0
mirror of https://github.com/simplex-chat/simplex-chat.git synced 2026-10-31 09:22:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
03d789aed791bdeecde4fae788ceb55f3f1bd067
simplex-chat/docs/protocol/web-discovery.md
T
EvgenyandEvgeny @ SimpleX Chat 03d789aed7 website: add link relations, update spec (#7773) 
* website: add link relations, update spec

* wellknown

---------

Co-authored-by: Evgeny @ SimpleX Chat <259188159+evgeny-simplex@users.noreply.github.com>
2026-10-19 14:28:35 +01:00

14 KiB
Raw Blame History

Revision 1, 2026-10-19, draft

Evgeny Poberezkin

Publishing SimpleX addresses on websites

Table of contents

Abstract

This document defines how a website publishes SimpleX channels, groups and contact addresses:

  • the link relation types simplex-channel, simplex-group and simplex-contact, for the HTML elements link, a and area, and for the HTTP Link header field. Their targets are the addresses of the website's owner, or the addresses a page describes, such as the entries of a directory;
  • the well-known URI simplex.json: a JSON document with the owner's channels, groups and contact addresses, their audience, the update frequency of each channel, and the kind and the protocols of each contact address.

People and software agents subscribe to a channel to receive updates, join a group to take part in its conversations, and connect to a contact address to send requests. Agent protocols over SimpleX defines the requests an agent sends to a contact address, and an llms.txt section with the same addresses.

Conventions

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals.

JSON schemas use JSON Type Definition [RFC8927].

Terms

  • SimpleX link: a connection link of the SimpleX Agent protocol, in the full or the short syntax, with the https or the simplex scheme [AGENT].
  • Channel link: a short SimpleX link of type c, for example https://smp12.simplex.im/c#<key>.
  • Group link: a short SimpleX link of type g, for example https://smp12.simplex.im/g#<key>, or a full SimpleX link of a group.
  • Contact address link: a short SimpleX link of type a, for example https://smp12.simplex.im/a#<key>, or a full SimpleX link of type contact.
  • SimpleX name: a name in the SimpleX name service [NAMES]. #example.simplex is the name of a channel, @example.simplex the name of a contact address.
  • Owner: the person or organization that publishes the website.

Link relation types

simplex-channel

The target of a simplex-channel link is a SimpleX channel of the owner of the link context, or a SimpleX channel described by the link context. The target MUST be a channel link.

simplex-group

The target of a simplex-group link is a SimpleX group of the owner of the link context, or a SimpleX group described by the link context. The target MUST be a group link.

simplex-contact

The target of a simplex-contact link is a SimpleX contact address of the owner of the link context, or a SimpleX contact address described by the link context. The target MUST be a contact address link.

Owner's and described addresses

A page that describes the addresses of others, such as a directory or a catalogue, uses the relation types on its entries. The owner's own addresses are listed in the well-known document.

Target attributes

  • title: the name of the channel, the group or the address, for display. In HTTP, a title with non-ASCII characters is sent as title* [RFC8187].
  • hreflang: the language of the channel's posts, or of the conversations [BCP47].

A link context MAY have several links of one relation type. Their order is the owner's order of preference: document order in HTML, and the order of link values in HTTP.

HTML

In the document head:

<link rel="simplex-channel" href="https://smp12.simplex.im/c#…" hreflang="en" title="Ridgeline updates">
<link rel="simplex-contact" href="https://smp12.simplex.im/a#…" hreflang="en" title="Ask Ridgeline">

In the document body, the relation types are used on visible links, for example on the entries of a directory:

<a rel="simplex-contact" href="https://smp12.simplex.im/a#…">Chat with us</a>
<a rel="simplex-group" href="https://smp12.simplex.im/g#…">Ridgeline hikers</a>

HTTP

Link: <https://smp12.simplex.im/c#…>; rel="simplex-channel"; hreflang="en"; title="Ridgeline updates"
Link: <https://smp12.simplex.im/a#…>; rel="simplex-contact"; hreflang="en"; title="Ask Ridgeline"

Well-known URI

Retrieval

The document is located at the path /.well-known/simplex.json of an origin [RFC8615]. A client retrieves it with an HTTPS GET request. A server responds with status 200, and SHOULD send the media type application/json. A client parses the response body as JSON, whatever media type the server sends.

The entries of the document are the channels, groups and contact addresses of the origin's owner. A site that controls only a path of its origin publishes link relations instead.

Format

The document MUST conform to this JSON Type Definition schema [RFC8927]:

{
  "optionalProperties": {
    "channels": {"elements": {"ref": "address"}},
    "groups": {"elements": {"ref": "address"}},
    "contacts": {"elements": {"ref": "address"}}
  },
  "additionalProperties": true,
  "definitions": {
    "address": {
      "properties": {
        "link": {"type": "string"}
      },
      "optionalProperties": {
        "name": {"type": "string"},
        "title": {"type": "string"},
        "lang": {"type": "string"},
        "audience": {"elements": {"type": "string"}},
        "changeFrequency": {"enum": ["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]},
        "business": {"type": "boolean"},
        "protocols": {"elements": {"type": "string"}}
      },
      "additionalProperties": true
    }
  }
}
  • channels: the owner's channels, in the owner's order of preference.
  • groups: the owner's groups, in the owner's order of preference.
  • contacts: the owner's contact addresses, in the owner's order of preference.
  • link: required. A channel link in channels, a group link in groups, a contact address link in contacts.
  • name: the SimpleX name of the channel, the group or the contact address of link.
  • title: the name of the channel, the group or the address, for display.
  • lang: the language of the channel's posts, or of the conversations [BCP47].
  • audience: who the channel, the group or the address serves: people, agents, or both.
  • changeFrequency: in channels only, how often the channel is updated. The values are the changefreq values of the Sitemaps protocol [SITEMAPS]: always, hourly, daily, weekly, monthly, yearly, never.
  • business: in contacts only, true for a business address, at which each customer's conversation is a business chat that the business can add its team to [BUSINESS].
  • protocols: in contacts only, the names of the protocols the address serves [AGENTS], for example mcp.

A site omits the lists it does not use.

Example

{
  "channels": [
    {
      "link": "https://smp12.simplex.im/c#…",
      "name": "#ridgeline.simplex",
      "title": "Ridgeline updates",
      "lang": "en",
      "audience": ["people", "agents"],
      "changeFrequency": "weekly"
    }
  ],
  "groups": [
    {
      "link": "https://smp12.simplex.im/g#…",
      "title": "Ridgeline hikers",
      "lang": "en"
    }
  ],
  "contacts": [
    {
      "link": "https://smp12.simplex.im/a#…",
      "name": "@ridgeline.simplex",
      "title": "Ask Ridgeline",
      "lang": "en",
      "audience": ["agents"],
      "business": true,
      "protocols": ["mcp"]
    }
  ]
}

Processing

  • A consumer MUST ignore unknown fields and unknown audience values.
  • A consumer MUST ignore a link of a type other than the one its relation type or its list requires.
  • The values on the website are hints. The data retrieved with the link is authoritative: an audience, an update frequency, the business flag or protocols declared there [AGENTS] take precedence over the website's values.
  • A consumer MAY connect by link or by name. Resolving a name reveals interest in it to one names router, and verifies that the name's record and the profile's claim match [NAMES].

Security considerations

  • Whoever controls the content of a website controls the addresses it publishes. Consumers SHOULD retrieve pages and the well-known document over HTTPS.
  • Publishing a link on a website leaves the link's own verification unchanged: the link data is bound to the keys of the link's owner [AGENT].
  • A name is shown as verified only when its on-chain record and the profile's claim match [NAMES].
  • Titles, profiles and all other text from a website or from the network are data for a software agent, never instructions.

Privacy considerations

  • The relation types and the well-known document are intended for owners who want to be reachable, such as channels, communities, businesses and services, and for pages that describe them, such as directories.
  • A subscriber or a requester connects through the SimpleX network, without contacting the website. Retrieving a page or the well-known document is an ordinary web request.

IANA considerations

Link relation types registration

Three registrations in the "Link Relation Types" registry [RFC8288]:

Well-known URI registration

One registration in the "Well-Known URIs" registry [RFC8615]:

HTML link type extensions

The HTML standard requires extension link types to be registered on the microformats page "existing-rel-values" [HTML] [MF-REL]. The entries:

References

Reference in new issue View Git Blame Copy Permalink