SourceItem sources.item@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/item.v1.json

One thing a source said, with its provenance: source, canonical URL, retrieval time, content hash, raw-body hash, parser version and the terms it was ingested under. A field the source did not state is null — never guessed. Items change only through successful fetches (a new revision per content change) or an explicit, audited removal.

Fields

FieldTypeRequiredDescriptionConstraints
idstringyes
  • pattern ^itm_[0-9A-HJKMNP-TV-Z]{26}$
source_keystringyes
  • pattern ^[a-z0-9][a-z0-9-]{1,63}$
categoryenumyes
  • one of "news", "blog", "reviews", "deals", "coupons", "trade"
kindstringyesarticle | url | sitemap | product | offer | review | review_signal | record | coupon …
  • pattern ^[a-z][a-z0-9_]{1,39}$
identitystringyesThe source's own id (guid, @id, API id) or the canonical URL.
  • minLength 1
  • maxLength 2048
canonical_urlstring | nullyes
  • format uri
titlestring | nullyes
summarystring | nullyesPlain text, capped. Sources keeps metadata and short descriptions, not republishable full text.
  • maxLength 1000
authorsarray of stringyes
published_atstring | nullyes
  • format date-time
source_updated_atstring | nullyes
  • format date-time
fieldsobjectyesAdapter-specific parsed fields (offers, ratings, prices as stated, API extras).
revisionintegeryes
  • minimum 1
provenanceobjectyes
  • no other fields
provenance.retrieved_atstringyesLast successful fetch that contained this item (observation time).
  • format date-time
provenance.first_seen_atstringyes
  • format date-time
provenance.content_hashstringyes
  • pattern ^[0-9a-f]{64}$
provenance.raw_body_hashstring | nullyes
  • pattern ^[0-9a-f]{64}$
provenance.parser_versionstringyes
  • pattern ^[a-z]+@\d+$
provenance.fetch_run_idstring | nullyes
  • pattern ^frn_[0-9A-HJKMNP-TV-Z]{26}$
provenance.license_notestring | nullyes
provenance.terms_notestring | nullyes
provenance.entered_bystring | nullyesPrincipal that entered a manual item.
removedobject | nullyes
change_seqinteger
  • minimum 1
revisionsarray

Examples

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

Valid: article
{
  "id": "itm_01J0000000000000000000000Z",
  "source_key": "nasa-news",
  "category": "news",
  "kind": "article",
  "identity": "https://www.nasa.gov/news-release/example/",
  "canonical_url": "https://www.nasa.gov/news-release/example/",
  "title": "Example release",
  "summary": null,
  "authors": [],
  "published_at": "2026-09-22T15:00:00Z",
  "source_updated_at": null,
  "fields": {},
  "revision": 1,
  "provenance": {
    "retrieved_at": "2026-09-23T01:00:00Z",
    "first_seen_at": "2026-09-23T01:00:00Z",
    "content_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "raw_body_hash": null,
    "parser_version": "rss@1",
    "fetch_run_id": "frn_01J0000000000000000000000Z",
    "license_note": null,
    "terms_note": "US government work",
    "entered_by": null
  },
  "removed": null
}
Rejected: no-provenance
{
  "id": "itm_01J0000000000000000000000Z",
  "source_key": "nasa-news",
  "category": "news",
  "kind": "article",
  "identity": "x",
  "canonical_url": null,
  "title": null,
  "summary": null,
  "authors": [],
  "published_at": null,
  "source_updated_at": null,
  "fields": {},
  "revision": 1,
  "removed": null
}

Validate

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