(** References extension for JSON Feed items.

    This implements the references extension that allows items to cite sources.
    Each reference represents a cited resource with optional DOI and CiTO annotations.

    @see <https://github.com/egonw/JSONFeed-extensions/blob/main/references.md> References Extension Specification
    @see <https://purl.archive.org/spar/cito> Citation Typing Ontology *)


(** The type representing a reference to a cited source. *)
type t


(** {1 Construction} *)

(** [create ~url ?doi ?cito ()] creates a reference.

    @param url Unique URL for the reference (required).
               A URL based on a persistent unique identifier (like DOI) is recommended.
    @param doi Digital Object Identifier for the reference
    @param cito Citation Typing Ontology intent annotations

    {b Examples:}
    {[
      (* Simple reference with just a URL *)
      let ref1 = Reference.create
        ~url:"https://doi.org/10.5281/zenodo.16755947"
        ()

      (* Reference with DOI *)
      let ref2 = Reference.create
        ~url:"https://doi.org/10.5281/zenodo.16755947"
        ~doi:"10.5281/zenodo.16755947"
        ()

      (* Reference with CiTO annotations *)
      let ref3 = Reference.create
        ~url:"https://doi.org/10.5281/zenodo.16755947"
        ~doi:"10.5281/zenodo.16755947"
        ~cito:[`CitesAsRecommendedReading; `UsesMethodIn]
        ()

      (* Reference with custom CiTO term *)
      let ref4 = Reference.create
        ~url:"https://example.com/paper"
        ~cito:[`Other "customIntent"]
        ()
    ]} *)
val create :
  url:string ->
  ?doi:string ->
  ?cito:Cito.t list ->
  unit ->
  t


(** {1 Accessors} *)

(** [url t] returns the reference's URL. *)
val url : t -> string

(** [doi t] returns the reference's DOI, if set. *)
val doi : t -> string option

(** [cito t] returns the reference's CiTO annotations, if set. *)
val cito : t -> Cito.t list option


(** {1 Comparison} *)

(** [equal a b] tests equality between two references.

    References are considered equal if they have the same URL. *)
val equal : t -> t -> bool


(** {1 Pretty Printing} *)

(** [pp ppf t] pretty prints a reference to the formatter.

    {b Example output:}
    {v https://doi.org/10.5281/zenodo.16755947 [DOI: 10.5281/zenodo.16755947] v} *)
val pp : Format.formatter -> t -> unit