OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Citation Typing Ontology (CiTO) intent annotations.
7
8 CiTO provides a structured vocabulary for describing the nature of
9 citations. This module implements support for CiTO annotations as used in
10 the references extension.
11
12 @see <https://purl.archive.org/spar/cito> Citation Typing Ontology
13 @see <https://sparontologies.github.io/cito/current/cito.html>
14 CiTO Specification *)
15
16type t =
17 [ `Cites (** The base citation property *)
18 | (* Factual citation intents *)
19 `CitesAsAuthority
20 (** Cites as authoritative source *)
21 | `CitesAsDataSource (** Cites as origin of data *)
22 | `CitesAsEvidence (** Cites for factual evidence *)
23 | `CitesForInformation (** Cites as information source *)
24 | `UsesDataFrom (** Uses data from cited work *)
25 | `UsesMethodIn (** Uses methodology from cited work *)
26 | `UsesConclusionsFrom (** Applies conclusions from cited work *)
27 | (* Agreement/disagreement *)
28 `AgreesWith
29 (** Concurs with cited statements *)
30 | `DisagreesWith (** Rejects cited statements *)
31 | `Confirms (** Validates facts in cited work *)
32 | `Refutes (** Disproves cited statements *)
33 | `Disputes (** Contests without definitive refutation *)
34 | (* Critical engagement *)
35 `Critiques
36 (** Analyzes and finds fault *)
37 | `Qualifies (** Places conditions on statements *)
38 | `Corrects (** Fixes errors in cited work *)
39 | `Updates (** Advances understanding beyond cited work *)
40 | `Extends (** Builds upon cited facts *)
41 | (* Rhetorical/stylistic *)
42 `Parodies
43 (** Imitates for comic effect *)
44 | `Plagiarizes (** Uses without acknowledgment *)
45 | `Derides (** Expresses contempt *)
46 | `Ridicules (** Mocks cited work *)
47 | (* Document relationships *)
48 `Describes
49 (** Characterizes cited entity *)
50 | `Documents (** Records information about source *)
51 | `CitesAsSourceDocument (** Cites as foundational source *)
52 | `CitesAsMetadataDocument (** Cites containing metadata *)
53 | `Compiles (** Uses to create new work *)
54 | `Reviews (** Examines cited statements *)
55 | `Retracts (** Formally withdraws *)
56 | (* Support/context *)
57 `Supports
58 (** Provides intellectual backing *)
59 | `GivesSupportTo (** Provides support to citing entity *)
60 | `ObtainsSupportFrom (** Obtains backing from cited work *)
61 | `GivesBackgroundTo (** Provides context *)
62 | `ObtainsBackgroundFrom (** Obtains context from cited work *)
63 | (* Exploratory *)
64 `SpeculatesOn
65 (** Theorizes without firm evidence *)
66 | `CitesAsPotentialSolution (** Offers possible resolution *)
67 | `CitesAsRecommendedReading (** Suggests as further reading *)
68 | `CitesAsRelated (** Identifies as thematically connected *)
69 | (* Quotation/excerpting *)
70 `IncludesQuotationFrom
71 (** Incorporates direct quotes *)
72 | `IncludesExcerptFrom (** Uses non-quoted passages *)
73 | (* Dialogue *)
74 `RepliesTo
75 (** Responds to cited statements *)
76 | `HasReplyFrom (** Evokes response *)
77 | (* Linking *)
78 `LinksTo
79 (** Provides URL hyperlink *)
80 | (* Shared attribution *)
81 `SharesAuthorWith
82 (** Common authorship *)
83 | `SharesJournalWith (** Published in same journal *)
84 | `SharesPublicationVenueWith (** Published in same venue *)
85 | `SharesFundingAgencyWith (** Funded by same agency *)
86 | `SharesAuthorInstitutionWith (** Authors share affiliation *)
87 | (* Extensibility *)
88 `Other of string
89 (** Custom or future CiTO term *) ]
90(** CiTO citation intent annotation.
91
92 Represents the intent or nature of a citation using the Citation Typing
93 Ontology. Each variant corresponds to a specific CiTO property. The [`Other]
94 variant allows for custom or future CiTO terms not yet included in this
95 library.
96
97 {b Categories:}
98 - Factual: Citing for data, methods, evidence, or information
99 - Critical: Agreement, disagreement, correction, or qualification
100 - Rhetorical: Style-based citations (parody, ridicule, etc.)
101 - Relational: Document relationships and compilations
102 - Support: Providing or obtaining backing and context
103 - Exploratory: Speculation and recommendations
104 - Quotation: Direct quotes and excerpts
105 - Dialogue: Replies and responses
106 - Sharing: Common attributes between works *)
107
108(** {1 Conversion} *)
109
110val of_string : string -> t
111(** [of_string s] converts a CiTO term string to its variant representation.
112
113 Recognized CiTO terms are converted to their corresponding variants.
114 Unrecognized terms are wrapped in [`Other].
115
116 The comparison is case-insensitive for standard CiTO terms but preserves the
117 original case in [`Other] variants.
118
119 {b Examples:}
120 {[
121 of_string "cites" (* returns `Cites *) of_string "usesMethodIn"
122 (* returns `UsesMethodIn *) of_string
123 "citesAsRecommendedReading" (* returns `CitesAsRecommendedReading *)
124 of_string "customTerm" (* returns `Other "customTerm" *)
125 ]} *)
126
127val to_string : t -> string
128(** [to_string t] converts a CiTO variant to its canonical string
129 representation.
130
131 Standard CiTO terms use their official CiTO local names (camelCase).
132 [`Other] variants return the wrapped string unchanged.
133
134 {b Examples:}
135 {[
136 to_string `Cites (* returns "cites" *) to_string `UsesMethodIn
137 (* returns "usesMethodIn" *) to_string (`Other "customTerm")
138 (* returns "customTerm" *)
139 ]} *)
140
141(** {1 Comparison} *)
142
143val equal : t -> t -> bool
144(** [equal a b] tests equality between two CiTO annotations.
145
146 Two annotations are equal if they represent the same CiTO term. For [`Other]
147 variants, string comparison is case-sensitive. *)
148
149(** {1 Jsont Type} *)
150
151val jsont : t Jsont.t
152(** Declarative JSON type for CiTO annotations.
153
154 Maps CiTO intent strings to the corresponding variants. Unknown intents are
155 mapped to [`Other s]. *)
156
157(** {1 Pretty Printing} *)
158
159val pp : Format.formatter -> t -> unit
160(** [pp ppf t] pretty prints a CiTO annotation to the formatter.
161
162 {b Example output:}
163 {v citesAsRecommendedReading v} *)