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