Source sources.source@1

Generated at from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

Version
1.0.0
Owner
sources
Visibility
first-party
Status
active
Compatibility
backward
Decision
ADR-017
Schema
https://openvibe.network/contracts/sources/source.v1.json

A registered source (roadmap §4.2 B, Wave 14): where it is fetched from and on what terms. Credentials are referenced by environment-variable NAME only. A source's existence is never permission to fetch: robots and terms are verified before it is enabled, and the fetcher re-checks robots.txt on every run.

Fields

FieldTypeRequiredDescriptionConstraints
keystringyes
  • pattern ^[a-z0-9][a-z0-9-]{1,63}$
namestringyes
  • minLength 1
  • maxLength 200
typeenumyes
  • one of "rss", "atom", "sitemap", "jsonld", "api", "manual"
categoryenumyes
  • one of "news", "blog", "reviews", "deals", "coupons", "trade"
homepage_urlstring | null
  • format uri
endpointsarray of objectyes
  • maxItems 20
  • items: no other fields
endpoints[].urlstringyes
  • pattern ^https?://
  • format uri
endpoints[].formatenum
  • one of "json", "xml"
endpoints[].items_pathstring
endpoints[].item_kindstring
  • pattern ^[a-z][a-z0-9_]{1,39}$
endpoints[].fieldsobject
endpoints[].extraobject
authobjectyes
  • no other fields
auth.modeenumyes
  • one of "none", "header", "bearer", "query"
auth.envstringName of the environment variable holding the credential. Never a value.
  • pattern ^SOURCES_CRED_[A-Z0-9_]{2,60}$
auth.headerstring
  • pattern ^[A-Za-z][A-Za-z0-9-]{0,63}$
auth.paramstring
  • pattern ^[A-Za-z0-9_.-]{1,64}$
robots_notestring | null
  • maxLength 2000
terms_notestring | null
  • maxLength 2000
license_notestring | null
  • maxLength 2000
min_interval_msintegeryesRate limit: the least time between two requests to this source (the per-host floor and robots Crawl-delay may raise it).
  • minimum 0
poll_interval_secintegeryes
  • minimum 1
stale_after_secintegeryes
  • minimum 1
max_itemsintegeryes
  • minimum 1
enabledbooleanyes
review_requiredbooleanyesProducts must review what they derive from this source before it can be indexable.
sensitivityenumyes
  • one of "none", "financial", "health", "political", "legal", "adult"
default_indexabilityenumyesWhat a product's indexability gate starts from for content derived from this source.
  • one of "index", "noindex"
search_visibilityenummembers = raw items are indexed in OpenVibe.Search for staff only (never indexable).
  • one of "members", null
healthobject
  • no other fields
health.statusenum
  • one of "healthy", "stale", "failing", "never_fetched", "disabled", "manual"
health.staleboolean
health.last_success_atstring | null
  • format date-time
health.last_run_atstring | null
  • format date-time
health.last_statestring | null
health.consecutive_failuresinteger
  • minimum 0
health.next_due_atstring | null
  • format date-time
health.stale_after_secinteger
created_atstring
  • format date-time
updated_atstring
  • format date-time

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: rss
{
  "key": "nasa-news",
  "name": "NASA news releases",
  "type": "rss",
  "category": "news",
  "homepage_url": "https://www.nasa.gov/",
  "endpoints": [
    {
      "url": "https://www.nasa.gov/news-release/feed/"
    }
  ],
  "auth": {
    "mode": "none"
  },
  "robots_note": "robots.txt allows the feed path (checked 2026-09-23)",
  "terms_note": "US government work; verify before enabling",
  "license_note": null,
  "min_interval_ms": 60000,
  "poll_interval_sec": 3600,
  "stale_after_sec": 172800,
  "max_items": 200,
  "enabled": false,
  "review_required": true,
  "sensitivity": "none",
  "default_indexability": "noindex"
}
Rejected: secret-in-auth
{
  "key": "x-api",
  "name": "X",
  "type": "api",
  "category": "deals",
  "endpoints": [
    {
      "url": "https://example.com/api"
    }
  ],
  "auth": {
    "mode": "bearer",
    "env": "DATABASE_PASSWORD"
  },
  "min_interval_ms": 1000,
  "poll_interval_sec": 60,
  "stale_after_sec": 600,
  "max_items": 10,
  "enabled": false,
  "review_required": false,
  "sensitivity": "none",
  "default_indexability": "noindex"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('sources.source@1', value);   // { valid, errors: [{ path, message }] }