mindat_rs/models/
references.rs

1//! Reference (bibliography) types for the Mindat API.
2//!
3//! These endpoints expose Mindat's literature/reference database: the
4//! references themselves plus supporting lookup tables (authors, citations,
5//! types, languages, ISBN/DDC/LCC classifications, etc.).
6
7use serde::{Deserialize, Serialize};
8
9use super::serde_helpers::{deserialize_i64, deserialize_optional_i32, deserialize_optional_i64};
10
11/// A bibliographic reference (`/references/`).
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct Reference {
14    /// Reference ID.
15    #[serde(deserialize_with = "deserialize_i64")]
16    pub ref_id: i64,
17    /// Historical ID.
18    #[serde(default, deserialize_with = "deserialize_optional_i64")]
19    pub ref_his_id: Option<i64>,
20    /// Entry date.
21    #[serde(default)]
22    pub ref_entrydate: Option<String>,
23    /// Edit date.
24    #[serde(default)]
25    pub ref_editdate: Option<String>,
26    /// Raw (unformatted) reference text.
27    #[serde(default)]
28    pub ref_rawtext: Option<String>,
29    /// HTML-formatted reference text.
30    #[serde(default)]
31    pub ref_htmltext: Option<String>,
32    /// Reference type ID (see [`ReferenceType`]).
33    #[serde(default, deserialize_with = "deserialize_optional_i32")]
34    pub ref_type: Option<i32>,
35    /// Access level.
36    #[serde(default, deserialize_with = "deserialize_optional_i32")]
37    pub ref_access: Option<i32>,
38    /// Title.
39    #[serde(default)]
40    pub ref_title: Option<String>,
41    /// Journal name.
42    #[serde(default)]
43    pub ref_journal: Option<String>,
44    /// Publication year.
45    #[serde(default, deserialize_with = "deserialize_optional_i32")]
46    pub ref_year: Option<i32>,
47    /// End year (for a range).
48    #[serde(default, deserialize_with = "deserialize_optional_i32")]
49    pub ref_year_to: Option<i32>,
50    /// Month.
51    #[serde(default, deserialize_with = "deserialize_optional_i32")]
52    pub ref_month: Option<i32>,
53    /// Day.
54    #[serde(default, deserialize_with = "deserialize_optional_i32")]
55    pub ref_day: Option<i32>,
56    /// Series number.
57    #[serde(default, deserialize_with = "deserialize_optional_i32")]
58    pub ref_series: Option<i32>,
59    /// Volume (as text).
60    #[serde(default)]
61    pub ref_volume: Option<String>,
62    /// Volume (as integer).
63    #[serde(default, deserialize_with = "deserialize_optional_i32")]
64    pub ref_volume_int: Option<i32>,
65    /// Issue (as text).
66    #[serde(default)]
67    pub ref_issue: Option<String>,
68    /// Issue (as integer).
69    #[serde(default, deserialize_with = "deserialize_optional_i32")]
70    pub ref_issue_int: Option<i32>,
71    /// First page (as integer).
72    #[serde(default, deserialize_with = "deserialize_optional_i32")]
73    pub ref_pagefrom: Option<i32>,
74    /// Last page (as integer).
75    #[serde(default, deserialize_with = "deserialize_optional_i32")]
76    pub ref_pageto: Option<i32>,
77    /// First page (as text).
78    #[serde(default)]
79    pub ref_pagefrom_txt: Option<String>,
80    /// Last page (as text).
81    #[serde(default)]
82    pub ref_pageto_txt: Option<String>,
83    /// Publisher.
84    #[serde(default)]
85    pub ref_publisher: Option<String>,
86    /// Place of publication.
87    #[serde(default)]
88    pub ref_place: Option<String>,
89    /// URL.
90    #[serde(default)]
91    pub ref_url: Option<String>,
92    /// File URL.
93    #[serde(default)]
94    pub ref_file_url: Option<String>,
95    /// DOI.
96    #[serde(default)]
97    pub ref_doi: Option<String>,
98    /// Other fields (free text).
99    #[serde(default)]
100    pub ref_other_fields: Option<String>,
101    /// Notes.
102    #[serde(default)]
103    pub ref_notes: Option<String>,
104    /// Deleted-by user ID.
105    #[serde(default, deserialize_with = "deserialize_optional_i32")]
106    pub ref_deleted_by: Option<i32>,
107    /// Issue title.
108    #[serde(default)]
109    pub ref_issuetitle: Option<String>,
110    /// Edition.
111    #[serde(default, deserialize_with = "deserialize_optional_i32")]
112    pub ref_edition: Option<i32>,
113    /// Parent reference ID.
114    #[serde(default, deserialize_with = "deserialize_optional_i64")]
115    pub ref_parent: Option<i64>,
116    /// Part.
117    #[serde(default, deserialize_with = "deserialize_optional_i32")]
118    pub ref_part: Option<i32>,
119    /// Replaced-by reference ID.
120    #[serde(default, deserialize_with = "deserialize_optional_i64")]
121    pub ref_replaced_by: Option<i64>,
122    /// ISBN.
123    #[serde(default)]
124    pub ref_isbn: Option<String>,
125    /// Abstract.
126    #[serde(default)]
127    pub ref_abstract: Option<String>,
128    /// Last automatic download date.
129    #[serde(default)]
130    pub ref_lastautodl: Option<String>,
131    /// Top-level flag.
132    #[serde(default, deserialize_with = "deserialize_optional_i32")]
133    pub ref_toplevel: Option<i32>,
134    /// Journal (transliterated).
135    #[serde(default)]
136    pub ref_journal_t: Option<String>,
137    /// Title (transliterated).
138    #[serde(default)]
139    pub ref_title_t: Option<String>,
140}
141
142/// An author linked to a reference (`/reference-authors/`).
143#[derive(Debug, Clone, Serialize, Deserialize)]
144pub struct ReferenceAuthor {
145    /// Author-link ID.
146    #[serde(deserialize_with = "deserialize_i64")]
147    pub ra_id: i64,
148    /// Reference ID.
149    #[serde(default, deserialize_with = "deserialize_optional_i64")]
150    pub ra_ref_id: Option<i64>,
151    /// Author name.
152    #[serde(default)]
153    pub ra_name: Option<String>,
154    /// Author type (e.g. author vs. editor).
155    #[serde(default)]
156    pub ra_type: Option<serde_json::Value>,
157}
158
159/// A de-duplicated author name (`/reference-authors-unique/`).
160#[derive(Debug, Clone, Serialize, Deserialize)]
161pub struct ReferenceAuthorUnique {
162    /// Unique-author ID.
163    #[serde(deserialize_with = "deserialize_i64")]
164    pub rau_id: i64,
165    /// Author name.
166    #[serde(default)]
167    pub rau_text: Option<String>,
168}
169
170/// A citation linking a reference to a mineral/locality/photo (`/reference-citations/`).
171#[derive(Debug, Clone, Serialize, Deserialize)]
172pub struct ReferenceCitation {
173    /// Citation ID.
174    #[serde(deserialize_with = "deserialize_i64")]
175    pub rc_id: i64,
176    /// Historical ID.
177    #[serde(default, deserialize_with = "deserialize_optional_i64")]
178    pub rc_his_id: Option<i64>,
179    /// Reference ID.
180    #[serde(default, deserialize_with = "deserialize_optional_i64")]
181    pub rc_ref_id: Option<i64>,
182    /// Reference-part ID.
183    #[serde(default, deserialize_with = "deserialize_optional_i64")]
184    pub rc_rp_id: Option<i64>,
185    /// Citation date.
186    #[serde(default)]
187    pub rc_date: Option<String>,
188    /// Creation date.
189    #[serde(default)]
190    pub rc_date_created: Option<String>,
191    /// Mineral ID cited.
192    #[serde(default, deserialize_with = "deserialize_optional_i64")]
193    pub rc_min: Option<i64>,
194    /// Locality ID cited.
195    #[serde(default, deserialize_with = "deserialize_optional_i64")]
196    pub rc_loc: Option<i64>,
197    /// Article ID cited.
198    #[serde(default, deserialize_with = "deserialize_optional_i64")]
199    pub rc_article: Option<i64>,
200    /// Photo ID cited.
201    #[serde(default, deserialize_with = "deserialize_optional_i64")]
202    pub rc_photo: Option<i64>,
203    /// Glossary ID cited.
204    #[serde(default, deserialize_with = "deserialize_optional_i64")]
205    pub rc_glossary: Option<i64>,
206    /// Entry ID.
207    #[serde(default, deserialize_with = "deserialize_optional_i64")]
208    pub rc_entryid: Option<i64>,
209    /// First page.
210    #[serde(default, deserialize_with = "deserialize_optional_i32")]
211    pub rc_pagefrom: Option<i32>,
212    /// Last page.
213    #[serde(default, deserialize_with = "deserialize_optional_i32")]
214    pub rc_pageto: Option<i32>,
215    /// Citation number.
216    #[serde(default, deserialize_with = "deserialize_optional_i32")]
217    pub rc_citationno: Option<i32>,
218    /// Comments.
219    #[serde(default)]
220    pub rc_comments: Option<String>,
221    /// Deleted-by user ID.
222    #[serde(default, deserialize_with = "deserialize_optional_i32")]
223    pub rc_deletedby: Option<i32>,
224    /// Citation type.
225    #[serde(default)]
226    pub rc_type: Option<serde_json::Value>,
227    /// Unique key.
228    #[serde(default, deserialize_with = "deserialize_optional_i64")]
229    pub rc_ukey: Option<i64>,
230}
231
232/// A reference type (`/reference-types/`).
233#[derive(Debug, Clone, Serialize, Deserialize)]
234pub struct ReferenceType {
235    /// Type ID.
236    #[serde(deserialize_with = "deserialize_i64")]
237    pub rt_id: i64,
238    /// Type code.
239    #[serde(default)]
240    pub rt_code: Option<String>,
241    /// Type name.
242    #[serde(default)]
243    pub rt_name: Option<String>,
244    /// Important flag.
245    #[serde(default, deserialize_with = "deserialize_optional_i32")]
246    pub rt_important: Option<i32>,
247}
248
249/// A reference language (`/reference-languages/`).
250#[derive(Debug, Clone, Serialize, Deserialize)]
251pub struct ReferenceLanguage {
252    /// Language-link ID.
253    #[serde(deserialize_with = "deserialize_i64")]
254    pub rl_id: i64,
255    /// Reference ID.
256    #[serde(default, deserialize_with = "deserialize_optional_i64")]
257    pub rl_ref_id: Option<i64>,
258    /// ISO language code.
259    #[serde(default)]
260    pub rl_iso: Option<String>,
261    /// Minor-language flag.
262    #[serde(default, deserialize_with = "deserialize_optional_i32")]
263    pub rl_minor: Option<i32>,
264}
265
266/// A reference classification entry (`/reference-classify/`).
267#[derive(Debug, Clone, Serialize, Deserialize)]
268pub struct ReferenceClassify {
269    /// Classification ID.
270    #[serde(deserialize_with = "deserialize_i64")]
271    pub rc_id: i64,
272    /// Reference ID.
273    #[serde(default, deserialize_with = "deserialize_optional_i64")]
274    pub rc_ref_id: Option<i64>,
275    /// Classification type.
276    #[serde(default)]
277    pub rc_type: Option<serde_json::Value>,
278    /// Classification value.
279    #[serde(default)]
280    pub rc_value: Option<String>,
281}
282
283/// A Dewey Decimal Classification entry (`/reference-ddc/`).
284#[derive(Debug, Clone, Serialize, Deserialize)]
285pub struct ReferenceDdc {
286    /// DDC code.
287    #[serde(default)]
288    pub ddc_code: String,
289    /// DDC title.
290    #[serde(default)]
291    pub ddc_title: Option<String>,
292}
293
294/// A Library of Congress Classification entry (`/reference-lcc/`).
295#[derive(Debug, Clone, Serialize, Deserialize)]
296pub struct ReferenceLcc {
297    /// LCC code.
298    #[serde(default)]
299    pub lcc_code: String,
300    /// LCC title.
301    #[serde(default)]
302    pub lcc_title: Option<String>,
303}
304
305/// An ISBN entry (`/reference-isbn/`).
306#[derive(Debug, Clone, Serialize, Deserialize)]
307pub struct ReferenceIsbn {
308    /// ISBN.
309    #[serde(default)]
310    pub ri_isbn: String,
311    /// Series.
312    #[serde(default)]
313    pub ri_series: Option<String>,
314    /// Publisher.
315    #[serde(default)]
316    pub ri_publisher: Option<String>,
317    /// Year.
318    #[serde(default, deserialize_with = "deserialize_optional_i32")]
319    pub ri_year: Option<i32>,
320    /// Title.
321    #[serde(default)]
322    pub ri_title: Option<String>,
323}
324
325/// A supplementary reference-extra entry (`/reference-extra/`).
326#[derive(Debug, Clone, Serialize, Deserialize)]
327pub struct ReferenceExtra {
328    /// Extra ID.
329    #[serde(deserialize_with = "deserialize_i64")]
330    pub re_id: i64,
331    /// Code.
332    #[serde(default)]
333    pub re_code: Option<String>,
334    /// Text.
335    #[serde(default)]
336    pub re_text: Option<String>,
337}
338
339/// Builder for `/references/` query parameters.
340#[derive(Debug, Clone, Default)]
341pub struct ReferencesQuery {
342    /// Free-text search.
343    pub q: Option<String>,
344    /// Filter by reference type ID.
345    pub ref_type: Option<i32>,
346    /// Filter by title.
347    pub ref_title: Option<String>,
348    /// Filter by journal.
349    pub ref_journal: Option<String>,
350    /// Filter by publisher.
351    pub ref_publisher: Option<String>,
352    /// Filter by DOI.
353    pub ref_doi: Option<String>,
354    /// Filter by ISBN.
355    pub ref_isbn: Option<String>,
356    /// Filter by a set of IDs.
357    pub id_in: Option<Vec<i64>>,
358    /// Minimum ID (range).
359    pub id_range_min: Option<i64>,
360    /// Maximum ID (range).
361    pub id_range_max: Option<i64>,
362    /// Ordering field.
363    pub ordering: Option<String>,
364    /// Fields to include.
365    pub fields: Option<String>,
366    /// Fields to omit.
367    pub omit: Option<String>,
368    /// Page number.
369    pub page: Option<i32>,
370    /// Page size.
371    pub page_size: Option<i32>,
372}
373
374impl ReferencesQuery {
375    /// Create a new empty query.
376    pub fn new() -> Self {
377        Self::default()
378    }
379
380    /// Free-text search across references.
381    pub fn search(mut self, q: impl Into<String>) -> Self {
382        self.q = Some(q.into());
383        self
384    }
385
386    /// Filter by title.
387    pub fn title(mut self, title: impl Into<String>) -> Self {
388        self.ref_title = Some(title.into());
389        self
390    }
391
392    /// Filter by journal.
393    pub fn journal(mut self, journal: impl Into<String>) -> Self {
394        self.ref_journal = Some(journal.into());
395        self
396    }
397
398    /// Filter by DOI.
399    pub fn doi(mut self, doi: impl Into<String>) -> Self {
400        self.ref_doi = Some(doi.into());
401        self
402    }
403
404    /// Filter by reference type ID.
405    pub fn ref_type(mut self, ref_type: i32) -> Self {
406        self.ref_type = Some(ref_type);
407        self
408    }
409
410    /// Set page number.
411    pub fn page(mut self, page: i32) -> Self {
412        self.page = Some(page);
413        self
414    }
415
416    /// Set page size.
417    pub fn page_size(mut self, size: i32) -> Self {
418        self.page_size = Some(size);
419        self
420    }
421}
422
423/// Builder for `/reference-citations/` query parameters.
424#[derive(Debug, Clone, Default)]
425pub struct ReferenceCitationsQuery {
426    /// Filter by cited mineral ID.
427    pub rc_min: Option<i64>,
428    /// Filter by cited locality ID.
429    pub rc_loc: Option<i64>,
430    /// Filter by cited photo ID.
431    pub rc_photo: Option<i64>,
432    /// Filter by cited article ID.
433    pub rc_article: Option<i64>,
434    /// Filter by reference ID.
435    pub rc_ref_id: Option<i64>,
436    /// Filter by entry ID.
437    pub rc_entryid: Option<i64>,
438    /// Filter by citation type.
439    pub rc_type: Option<i32>,
440    /// Ordering field.
441    pub ordering: Option<String>,
442    /// Page number.
443    pub page: Option<i32>,
444    /// Page size.
445    pub page_size: Option<i32>,
446}
447
448impl ReferenceCitationsQuery {
449    /// Create a new empty query.
450    pub fn new() -> Self {
451        Self::default()
452    }
453
454    /// Filter to citations of a given mineral.
455    pub fn mineral(mut self, mineral_id: i64) -> Self {
456        self.rc_min = Some(mineral_id);
457        self
458    }
459
460    /// Filter to citations of a given locality.
461    pub fn locality(mut self, locality_id: i64) -> Self {
462        self.rc_loc = Some(locality_id);
463        self
464    }
465
466    /// Filter to citations of a given reference.
467    pub fn reference(mut self, ref_id: i64) -> Self {
468        self.rc_ref_id = Some(ref_id);
469        self
470    }
471
472    /// Set page number.
473    pub fn page(mut self, page: i32) -> Self {
474        self.page = Some(page);
475        self
476    }
477
478    /// Set page size.
479    pub fn page_size(mut self, size: i32) -> Self {
480        self.page_size = Some(size);
481        self
482    }
483}
mindat_rs/models/references.rs

mindat_rs/models/
references.rs
