پروتکل Feedio RSS (JSON)

پروتکل اشتراک مبتنی بر JSON برای فیدهای ویدیویی.

1. Overview

Feedio RSS is a JSON-based subscription protocol for video feeds. Unlike XML RSS/Atom, it natively includes items, creator metadata, and app-oriented fields (cover, duration, platform identifiers, deep links).

2. Transport & Versioning

SHOULD be served over HTTPS. Recommended Content-Type: application/feedio+json; charset=utf-8.

Version field: feedio_version (e.g. "1.0"). Backward compatibility: new fields must not break existing semantics; clients MUST ignore unknown fields.

3. Top-Level Structure

Field	Type	Required	Description
feedio_version	string	Yes	Protocol version
type	string	Yes	Must be "feed"
generated_at	string (ISO8601)	Yes	Generation timestamp
source	object	Yes	Source metadata
items	array<Item>	Yes	Items list (paged)
paging	object	No	Paging info
extensions	object	No	Vendor extensions

4. Source Object

Field	Type	Required	Description
id	string	Yes	Stable unique source id
title	string	Yes	Source title
feed_url	string (url)	Yes	Feed URL (this endpoint)
site_url	string (url)	No	Site/channel URL
icon_url	string (url)	No	Source icon (e.g. 64×64 or 128×128)
avatar_url	string (url)	No	Avatar URL
description	string	No	Source description
language	string	No	BCP-47 language tag
categories	array<string>	No	Topic categories
update_hint	object	No	Update hints (frequency/cache)

5. Item Object (Video)

Field	Type	Required	Description
id	string	Yes	Stable unique item id. Prefer guid or link hash.
title	string	Yes	Title
url	string (url)	Yes	Playback or landing page URL
published_at	string (ISO8601)	Yes	Publish time
source_id	string	Yes	Owning source id
summary	string	No	Short summary/description
cover	object	No	Cover metadata
media	object	No	Media info (duration/type/etc.)
creator	object<CreatorRef>	No	Creator (publisher). If missing, follow is unavailable.
deeplink	object	No	Deep link info (optional)
actions_hint	object	No	Action capability hints

5.1 cover object

Field	Type	Required	Description
url	string (url)	Yes	Cover image URL
width	number	No	Width in px
height	number	No	Height in px
blurhash	string	No	Blurhash placeholder (optional)

5.2 media object

Field	Type	Required	Description
url	string (url)	No	Direct video stream URL (e.g. .mp4) for in-app playback
type	string	No	e.g. "video"
duration_ms	number	No	Duration in ms
mime	string	No	MIME type
has_audio	boolean	No	Has audio
formats	array<object>	No	Optional format list

6. Creator Object

Field	Type	Required	Description
id	string	Yes	Stable creator id
name	string	Yes	Display name
profile_url	string (url)	No	Profile URL
avatar_url	string (url)	No	Avatar URL
platform	string	No	Platform id (e.g. youtube)

Item.creator MAY be a minimal reference (id+name); other fields are optional.

7. Actions Hint

Actions Hint indicates whether Like/Save/Later/Follow are permitted. Follow is usually available only when creator exists. Clients may ignore this and assume Like/Save/Later are allowed by default.

Example object:

{
  "can_like": true,
  "can_save": true,
  "can_later": true,
  "can_follow_creator": true
}

Field definitions:

can_like (boolean, optional): Whether Like is allowed
can_save (boolean, optional): Whether Save is allowed
can_later (boolean, optional): Whether Later is allowed
can_follow_creator (boolean, optional): Whether Follow is allowed (usually creator exists)

8. Paging

Field	Type	Required	Description
cursor	string	No	Current cursor
next_cursor	string	No	Next cursor
has_more	boolean	No	Has more

9. Dedup & Stability Rules

Item.id MUST be stable and unique. Prefer original guid; otherwise use a normalized URL hash.
published_at SHOULD be ISO8601 (UTC or with offset).
Clients MUST ignore unknown fields; servers MUST maintain backward compatibility.

10. Import & Share Formats

This section is not part of the Feed document itself but is used for unified QR scan and Scheme import.

Use Case	Format	Example
Single feed URL	Plain URL	https://example.com/feedio.json
Scheme import (single)	feedio://import?url=<encoded>	feedio://import?url=https%3A%2F%2Fexample.com%2Ffeedio.json
Scheme import (multiple)	feedio://import?urls=<comma>	feedio://import?urls=https%3A%2F%2Fa.com%2Ff.json,https%3A%2F%2Fb.com%2Ff.json

11. Example

{
  "feedio_version": "1.0",
  "type": "feed",
  "generated_at": "2026-02-21T12:00:00Z",
  "source": {
    "id": "source_tech_daily",
    "title": "Tech Daily",
    "feed_url": "https://example.com/feedio/tech-daily.json",
    "icon_url": "https://example.com/icons/tech-daily.png",
    "description": "Daily tech news and deep dives."
  },
  "items": [
    {
      "id": "item_20260221_001",
      "title": "AI Chips Explained in 8 Minutes",
      "url": "https://example.com/watch/ai-chips",
      "published_at": "2026-02-21T08:30:00Z",
      "source_id": "source_tech_daily",
      "cover": {
        "url": "https://example.com/covers/ai-chips.jpg"
      },
      "media": {
        "url": "https://example.com/videos/ai-chips.mp4",
        "type": "video",
        "duration_ms": 480000
      },
      "creator": {
        "id": "creator_jane_doe",
        "name": "Jane Doe"
      },
      "actions_hint": {
        "can_like": true,
        "can_save": true,
        "can_later": true,
        "can_follow_creator": true
      }
    }
  ],
  "paging": {
    "next_cursor": "c1",
    "has_more": true
  }
}

12. Client Requirements

If Item.creator is missing, Follow Creator must be unavailable (hidden/disabled).
Like/Save/Later are client-side actions (optionally synced) and do not require feed write-back.
Save and Later must be independent; an item can be in both.