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