Network Feed Hosting Specification

When a community hosts a news.json-formatted file on its own domain, a Loopback Social bot pulls it every 6 hours and surfaces the items on the banner and public feeds. This document is the operator guide for the self-publishing path (Step 2 Option 1 on the homepage).

End-to-end flow

1. Publish a JSON array on your domain conforming to news.schema.json. Example: https://forum.example.com/loopback.json. To split by language, run two URLs like loopback.ko.json / loopback.en.json.
2. Submit a community registration issue with those URL(s) in the "Network news source" field.
3. After a maintainer merges the registration, aggregate-network.mjs pulls the most recent active items every 6 hours.
4. From then on you just update your own file; the next cycle reflects the change automatically. No further PRs to us.

The banner always displays the origin as a [Community Name] Message prefix, and the same metadata appears in all public RSS/Atom/JSON Feed outputs.

Minimum requirements

• Publicly reachable over HTTPS. The registration form only accepts URLs starting with https://.
• Body must be a JSON array conforming to news.schema.json. The item shape matches Step 3 on the homepage.
• Response ≤ 1 MB, answered within 10 seconds. Overruns cause that URL to be skipped for the cycle.
• 30x redirects are followed automatically.

Item selection rules

• The aggregator considers only items active at the current time (start ≤ now ≤ end), with truthy display.
• Candidates are sorted by start descending (most recently started first).
• Single-string network_url → top-2 from that URL. {ko, en} two-URL split → top-1 each. Maximum 2 items per community.
• An item appearing in both ko and en URLs surfaces once. For accurate dedup, set an explicit id field on the item; otherwise the aggregator hashes start + message.

Source metadata (_source)

Every picked-up item gets the following _source object stamped in automatically. Any _source the community put in the payload is overwritten.

{
  "_source": {
    "community": "kebab-slug",
    "community_name": { "ko": "닷넷데브", "en": ".NET Dev" },
    "community_url": "https://forum.dotnetdev.kr/",
    "source_url": "https://forum.dotnetdev.kr/loopback.json",
    "lang": "ko"
  }
}

The banner runtime reads _source.community_name and prepends a [Community Name] Message prefix automatically. The same info also appears in the _loopback_social extension of the RSS/Atom/JSON Feed outputs so subscribers can identify the origin.

Refresh cadence and caching

• Every 6 hours by cron (0 */6 * * * UTC), plus on docs/communities.json changes, plus manual dispatch.
• The aggregator does not bypass caches, so set whatever Cache-Control you want on your file (recommended: max-age=600 or shorter).
• To reflect a change immediately without waiting for the next cron, a maintainer can trigger "Run workflow" on the aggregate-network.yml workflow.

Failure behavior

• If a single URL fails to fetch (timeout, HTTP error, 1 MB overrun) or fails schema validation, only that URL is skipped — other communities still aggregate normally. One broken source must not block the rest.
• Failures land in the Actions log as ::warning::network aggregator failures: …. Inspect the workflow run log for the exact reason.

Item lifecycle

Items whose end is in the past stay in docs/news.network.json for 30 days so RSS/Atom/JSON Feed subscribers can catch up on recent changes. They are removed automatically afterwards.

Local validation

Check your JSON against the schema before going live:

Copynpx ajv-cli@5 validate \
  -s https://loopback.social/schemas/news.schema.json \
  -d my-news.json \
  --strict=false --all-errors

To run the aggregator against the registered communities yourself:

Copygit clone https://github.com/loopback-social/community-network-banner
cd community-network-banner
npm install --no-save ajv@8
node .github/scripts/aggregate-network.mjs
# → results are written into docs/news.network.json

Related

• news.schema.json — item schema
• communities.schema.json — network_url field definition
• aggregate-network.mjs — aggregator source
• news.network.json — current pickup result