OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(** References extension for JSON Feed items.
2
3 This implements the references extension that allows items to cite sources.
4 Each reference represents a cited resource with optional DOI and CiTO annotations.
5
6 @see <https://github.com/egonw/JSONFeed-extensions/blob/main/references.md> References Extension Specification
7 @see <https://purl.archive.org/spar/cito> Citation Typing Ontology *)
8
9
10(** The type representing a reference to a cited source. *)
11type t
12
13
14(** {1 Construction} *)
15
16(** [create ~url ?doi ?cito ()] creates a reference.
17
18 @param url Unique URL for the reference (required).
19 A URL based on a persistent unique identifier (like DOI) is recommended.
20 @param doi Digital Object Identifier for the reference
21 @param cito Citation Typing Ontology intent annotations
22
23 {b Examples:}
24 {[
25 (* Simple reference with just a URL *)
26 let ref1 = Reference.create
27 ~url:"https://doi.org/10.5281/zenodo.16755947"
28 ()
29
30 (* Reference with DOI *)
31 let ref2 = Reference.create
32 ~url:"https://doi.org/10.5281/zenodo.16755947"
33 ~doi:"10.5281/zenodo.16755947"
34 ()
35
36 (* Reference with CiTO annotations *)
37 let ref3 = Reference.create
38 ~url:"https://doi.org/10.5281/zenodo.16755947"
39 ~doi:"10.5281/zenodo.16755947"
40 ~cito:[`CitesAsRecommendedReading; `UsesMethodIn]
41 ()
42
43 (* Reference with custom CiTO term *)
44 let ref4 = Reference.create
45 ~url:"https://example.com/paper"
46 ~cito:[`Other "customIntent"]
47 ()
48 ]} *)
49val create :
50 url:string ->
51 ?doi:string ->
52 ?cito:Cito.t list ->
53 unit ->
54 t
55
56
57(** {1 Accessors} *)
58
59(** [url t] returns the reference's URL. *)
60val url : t -> string
61
62(** [doi t] returns the reference's DOI, if set. *)
63val doi : t -> string option
64
65(** [cito t] returns the reference's CiTO annotations, if set. *)
66val cito : t -> Cito.t list option
67
68
69(** {1 Comparison} *)
70
71(** [equal a b] tests equality between two references.
72
73 References are considered equal if they have the same URL. *)
74val equal : t -> t -> bool
75
76
77(** {1 Pretty Printing} *)
78
79(** [pp ppf t] pretty prints a reference to the formatter.
80
81 {b Example output:}
82 {v https://doi.org/10.5281/zenodo.16755947 [DOI: 10.5281/zenodo.16755947] v} *)
83val pp : Format.formatter -> t -> unit