Skip to content

Resource Opinion v1

Source schema: doc/schemas/resource-opinion.v1.schema.json

Machine-readable schema for the content body of an Agora record expressing a participant's opinion about a resource. The enclosing agora-record.v1 envelope carries identity, authorship, topic routing, and the canonical record/about subject reference; this schema validates only the content body. The schema is intentionally open (additionalProperties: true); consumers MAY extend it with kind-specific namespaced keys of the form <kind>/<field> validated by a separate overlay schema (e.g. rumor-opinion.overlay.v1). See proposal 026 §Kind-specific extensions.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: resource-opinion.v1 Content-level discriminator for consumers that inspect the payload outside its Agora envelope.
opinion/text no string Human-authored opinion text. Renderers MUST treat this value as untrusted input and escape appropriately before display. Optional only when opinion/rating is present — every opinion MUST carry at least one of opinion/text or opinion/rating. Relational fields (opinion/in-reply-to, opinion/see-also, opinion/related) are additive context and do NOT substitute for the opinion's own substance.
opinion/rating no integer Optional rating on a 1..5 scale where 1 is the weakest and 5 is the strongest positive assessment. The value 0 is the explicit 'no rating' marker; absence of the field has the same meaning. Consumers MUST NOT silently translate ratings to a different scale (e.g. a reputation signal) without an explicit mapping.
opinion/tags no array Optional loose tags. Tags are not a closed taxonomy.
opinion/lang no string Optional BCP 47 language tag for opinion/text.
opinion/subject-kind no string Optional soft discriminator naming the kind of subject this opinion is about (e.g. rumor, gps-location, public-person, ean, url). Consumers MAY use this value to select a kind-specific overlay schema and interpret namespaced extension keys (e.g. rumor/credibility). It does not replace record/about in the enclosing envelope; it is a hint for payload-level routing.
opinion/in-reply-to no string Optional record/id of another opinion to which this opinion is a direct reply. Gives the opinion conversational context; consumers MAY thread replies by following this link. The referenced opinion SHOULD itself be a resource-opinion.v1 record, but consumers MUST tolerate dangling references (the referent may be unreachable at read time).
opinion/related no array Optional list of record/id values of other opinions related to this one (for example: prior takes the author has seen, opinions that inspired or corroborate this one, opinions the author is explicitly contrasting with). The relation is intentionally loose; stronger semantics belong in overlay fields or in a dedicated opinion-link schema.
opinion/see-also no array Optional list of related opinable objects the reader may want to look at alongside this opinion. Each entry is a 2-element vector [kind, id]. Unlike opinion/related, entries here are NOT restricted to opinions — they point at the underlying objects themselves (a URL, a rumor record, a resource URN, a person identity).
## Field Semantics

schema

  • Required: yes
  • Shape: const: resource-opinion.v1

Content-level discriminator for consumers that inspect the payload outside its Agora envelope.

opinion/text

  • Required: no
  • Shape: string

Human-authored opinion text. Renderers MUST treat this value as untrusted input and escape appropriately before display. Optional only when opinion/rating is present — every opinion MUST carry at least one of opinion/text or opinion/rating. Relational fields (opinion/in-reply-to, opinion/see-also, opinion/related) are additive context and do NOT substitute for the opinion's own substance.

opinion/rating

  • Required: no
  • Shape: integer

Optional rating on a 1..5 scale where 1 is the weakest and 5 is the strongest positive assessment. The value 0 is the explicit 'no rating' marker; absence of the field has the same meaning. Consumers MUST NOT silently translate ratings to a different scale (e.g. a reputation signal) without an explicit mapping.

opinion/tags

  • Required: no
  • Shape: array

Optional loose tags. Tags are not a closed taxonomy.

opinion/lang

  • Required: no
  • Shape: string

Optional BCP 47 language tag for opinion/text.

opinion/subject-kind

  • Required: no
  • Shape: string

Optional soft discriminator naming the kind of subject this opinion is about (e.g. rumor, gps-location, public-person, ean, url). Consumers MAY use this value to select a kind-specific overlay schema and interpret namespaced extension keys (e.g. rumor/credibility). It does not replace record/about in the enclosing envelope; it is a hint for payload-level routing.

opinion/in-reply-to

  • Required: no
  • Shape: string

Optional record/id of another opinion to which this opinion is a direct reply. Gives the opinion conversational context; consumers MAY thread replies by following this link. The referenced opinion SHOULD itself be a resource-opinion.v1 record, but consumers MUST tolerate dangling references (the referent may be unreachable at read time).

opinion/related

  • Required: no
  • Shape: array

Optional list of record/id values of other opinions related to this one (for example: prior takes the author has seen, opinions that inspired or corroborate this one, opinions the author is explicitly contrasting with). The relation is intentionally loose; stronger semantics belong in overlay fields or in a dedicated opinion-link schema.

opinion/see-also

  • Required: no
  • Shape: array

Optional list of related opinable objects the reader may want to look at alongside this opinion. Each entry is a 2-element vector [kind, id]. Unlike opinion/related, entries here are NOT restricted to opinions — they point at the underlying objects themselves (a URL, a rumor record, a resource URN, a person identity).