1use std::{collections::BTreeMap, error::Error, fmt};
2
3use serde::{Deserialize, Deserializer, Serialize, de};
4use serde_json::Value;
5
6use crate::RepertoireSide;
7
8const CURRENT_SCHEMA_VERSION: u64 = 1;
9
10type Extensions = BTreeMap<String, Value>;
11
12#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
18#[serde(rename_all = "camelCase")]
19pub struct CourseMetadata {
20 #[serde(default, skip_serializing_if = "Option::is_none")]
21 pub schema_version: Option<u64>,
22 #[serde(default, skip_serializing_if = "Option::is_none")]
23 pub course: Option<CourseInfo>,
24 #[serde(default, skip_serializing_if = "Vec::is_empty")]
25 pub chapters: Vec<ChapterMetadata>,
26 #[serde(default, skip_serializing_if = "Vec::is_empty")]
27 pub classifications: Vec<CurriculumClassification>,
28 #[serde(default, skip_serializing_if = "Vec::is_empty")]
29 pub tags: Vec<String>,
30 #[serde(default, skip_serializing_if = "Option::is_none")]
31 pub repertoire: Option<RepertoireSettings>,
32 #[serde(default, skip_serializing_if = "Option::is_none")]
33 pub lichess: Option<LichessMetadata>,
34 #[serde(flatten)]
35 pub extensions: Extensions,
36}
37
38impl CourseMetadata {
39 pub fn from_json(json: &str) -> Result<Self, MetadataError> {
41 let value: Value = serde_json::from_str(json).map_err(MetadataError::Json)?;
42 let version = value.get("schemaVersion");
43 match version {
44 None => {}
45 Some(Value::Number(number)) if number.as_u64() == Some(CURRENT_SCHEMA_VERSION) => {}
46 Some(Value::Number(number)) => {
47 return Err(MetadataError::UnsupportedSchemaVersion(number.to_string()));
48 }
49 Some(_) => {
50 return Err(MetadataError::Invalid(
51 "schemaVersion must be a positive integer".into(),
52 ));
53 }
54 }
55
56 let metadata: Self = serde_json::from_value(value).map_err(MetadataError::Json)?;
57 metadata.validate()?;
58 Ok(metadata)
59 }
60
61 #[must_use]
63 pub const fn is_legacy(&self) -> bool {
64 self.schema_version.is_none()
65 }
66
67 #[must_use]
69 pub fn repertoire_side(&self) -> Option<RepertoireSide> {
70 self.repertoire.as_ref().map(|settings| settings.side)
71 }
72
73 fn validate(&self) -> Result<(), MetadataError> {
74 if self.is_legacy() {
75 return Ok(());
76 }
77
78 let course = self.course.as_ref().ok_or_else(|| {
79 MetadataError::Invalid("schema version 1 requires a course object".into())
80 })?;
81 require_text("course.id", &course.id)?;
82 require_text("course.title", &course.title)?;
83
84 if self.chapters.is_empty() {
85 return Err(MetadataError::Invalid(
86 "schema version 1 requires at least one chapter".into(),
87 ));
88 }
89
90 let mut chapter_ids = std::collections::BTreeSet::new();
91 for chapter in &self.chapters {
92 require_text("chapters[].id", &chapter.id)?;
93 require_text("chapters[].title", &chapter.title)?;
94 if !chapter_ids.insert(&chapter.id) {
95 return Err(MetadataError::Invalid(format!(
96 "duplicate chapter id {:?}",
97 chapter.id
98 )));
99 }
100 }
101
102 for classification in &self.classifications {
103 require_text("classifications[].scheme", &classification.scheme)?;
104 require_text("classifications[].level", &classification.level)?;
105 require_text("classifications[].authority", &classification.authority)?;
106 }
107
108 if let Some(lichess) = &self.lichess {
109 require_text("lichess.studyId", &lichess.study_id)?;
110 for (chapter_id, mapping) in &lichess.chapters {
111 if !chapter_ids.contains(chapter_id) {
112 return Err(MetadataError::Invalid(format!(
113 "Lichess mapping references unknown chapter {chapter_id:?}"
114 )));
115 }
116 require_text("lichess.chapters[].id", &mapping.id)?;
117 }
118 }
119
120 match course.kind {
121 CourseKind::Repertoire if self.repertoire.is_none() => Err(MetadataError::Invalid(
122 "a repertoire course requires repertoire settings".into(),
123 )),
124 CourseKind::ProblemSet if self.repertoire.is_some() => Err(MetadataError::Invalid(
125 "problem-set courses cannot contain repertoire settings".into(),
126 )),
127 _ => Ok(()),
128 }
129 }
130}
131
132fn require_text(field: &str, value: &str) -> Result<(), MetadataError> {
133 if value.trim().is_empty() {
134 Err(MetadataError::Invalid(format!("{field} cannot be empty")))
135 } else {
136 Ok(())
137 }
138}
139
140#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
141#[serde(rename_all = "camelCase")]
142pub struct CourseInfo {
143 pub id: String,
144 pub title: String,
145 pub kind: CourseKind,
146 #[serde(default, skip_serializing_if = "Option::is_none")]
147 pub description: Option<String>,
148 #[serde(default, skip_serializing_if = "Option::is_none")]
149 pub language: Option<String>,
150 #[serde(default, skip_serializing_if = "Option::is_none")]
151 pub source: Option<SourceAttribution>,
152 #[serde(flatten)]
153 pub extensions: Extensions,
154}
155
156#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
157#[serde(rename_all = "kebab-case")]
158pub enum CourseKind {
159 Repertoire,
160 ProblemSet,
161}
162
163#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
164#[serde(rename_all = "camelCase")]
165pub struct SourceAttribution {
166 #[serde(default, skip_serializing_if = "Option::is_none")]
167 pub url: Option<String>,
168 #[serde(default, skip_serializing_if = "Option::is_none")]
169 pub attribution: Option<String>,
170 #[serde(default, skip_serializing_if = "Option::is_none")]
171 pub license: Option<String>,
172 #[serde(flatten)]
173 pub extensions: Extensions,
174}
175
176#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
177#[serde(rename_all = "camelCase")]
178pub struct ChapterMetadata {
179 pub id: String,
180 pub title: String,
181 #[serde(default, skip_serializing_if = "Option::is_none")]
182 pub description: Option<String>,
183 #[serde(flatten)]
184 pub extensions: Extensions,
185}
186
187#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
188#[serde(rename_all = "camelCase")]
189pub struct CurriculumClassification {
190 pub scheme: String,
191 pub level: String,
192 #[serde(default, skip_serializing_if = "Option::is_none")]
193 pub lesson: Option<String>,
194 #[serde(default, skip_serializing_if = "Option::is_none")]
195 pub theme: Option<String>,
196 pub authority: String,
197 #[serde(default, skip_serializing_if = "Option::is_none")]
198 pub status: Option<String>,
199 #[serde(default, skip_serializing_if = "Option::is_none")]
200 pub confidence: Option<String>,
201 #[serde(flatten)]
202 pub extensions: Extensions,
203}
204
205#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
206#[serde(rename_all = "camelCase")]
207pub struct RepertoireSettings {
208 #[serde(deserialize_with = "deserialize_repertoire_side")]
209 pub side: RepertoireSide,
210 #[serde(flatten)]
211 pub extensions: Extensions,
212}
213
214fn deserialize_repertoire_side<'de, D>(deserializer: D) -> Result<RepertoireSide, D::Error>
215where
216 D: Deserializer<'de>,
217{
218 let side = String::deserialize(deserializer)?;
219 if side.eq_ignore_ascii_case("white") {
220 Ok(RepertoireSide::White)
221 } else if side.eq_ignore_ascii_case("black") {
222 Ok(RepertoireSide::Black)
223 } else {
224 Err(de::Error::unknown_variant(&side, &["White", "Black"]))
225 }
226}
227
228#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
229#[serde(rename_all = "camelCase")]
230pub struct LichessMetadata {
231 pub study_id: String,
232 #[serde(default)]
233 pub chapters: BTreeMap<String, LichessChapter>,
234 #[serde(flatten)]
235 pub extensions: Extensions,
236}
237
238#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
239pub struct LichessChapter {
240 pub id: String,
241 #[serde(flatten)]
242 pub extensions: Extensions,
243}
244
245#[derive(Debug)]
246pub enum MetadataError {
247 Json(serde_json::Error),
248 UnsupportedSchemaVersion(String),
249 Invalid(String),
250}
251
252impl fmt::Display for MetadataError {
253 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
254 match self {
255 Self::Json(error) => write!(formatter, "invalid course metadata JSON: {error}"),
256 Self::UnsupportedSchemaVersion(version) => {
257 write!(
258 formatter,
259 "unsupported course metadata schema version {version}"
260 )
261 }
262 Self::Invalid(message) => formatter.write_str(message),
263 }
264 }
265}
266
267impl Error for MetadataError {
268 fn source(&self) -> Option<&(dyn Error + 'static)> {
269 match self {
270 Self::Json(error) => Some(error),
271 Self::UnsupportedSchemaVersion(_) | Self::Invalid(_) => None,
272 }
273 }
274}
275
276#[cfg(test)]
277mod tests {
278 use serde_json::json;
279
280 use super::{CourseKind, CourseMetadata, MetadataError};
281 use crate::RepertoireSide;
282
283 const VERSIONED_REPERTOIRE: &str = r#"{
284 "schemaVersion": 1,
285 "course": {
286 "id": "synthetic-black-repertoire",
287 "title": "Synthetic Black Repertoire",
288 "kind": "repertoire",
289 "source": {
290 "url": "https://example.invalid/synthetic",
291 "attribution": "Synthetic fixture",
292 "license": "CC0-1.0"
293 }
294 },
295 "chapters": [{"id": "defence", "title": "Example Defence"}],
296 "repertoire": {"side": "Black"},
297 "lichess": {
298 "studyId": "study-001",
299 "chapters": {"defence": {"id": "chapter-001"}}
300 }
301 }"#;
302
303 const SYNTHETIC_PROBLEM_SET: &str = r#"{
304 "schemaVersion": 1,
305 "course": {
306 "id": "synthetic-problems",
307 "title": "Synthetic Problems",
308 "kind": "problem-set",
309 "source": {
310 "url": "https://example.invalid/synthetic",
311 "attribution": "Synthetic fixture",
312 "license": "CC0-1.0"
313 }
314 },
315 "chapters": [{"id": "mate-in-one", "title": "Mate in One"}],
316 "problemSet": {
317 "problems": [{
318 "id": "synthetic-mate",
319 "sourceId": "synthetic",
320 "chapterId": "mate-in-one",
321 "start": {"fen": "7k/5Q2/6K1/8/8/8/8/8 b - - 0 1"},
322 "objective": {"kind": "checkmate", "moves": 1}
323 }]
324 }
325 }"#;
326
327 #[test]
328 fn parses_and_validates_versioned_repertoire_metadata() {
329 let metadata =
330 CourseMetadata::from_json(VERSIONED_REPERTOIRE).expect("synthetic fixture is valid");
331
332 assert!(!metadata.is_legacy());
333 assert_eq!(metadata.repertoire_side(), Some(RepertoireSide::Black));
334 assert_eq!(metadata.chapters[0].id, "defence");
335 assert_eq!(
336 metadata
337 .lichess
338 .as_ref()
339 .expect("lichess mappings")
340 .chapters["defence"]
341 .id,
342 "chapter-001"
343 );
344 }
345
346 #[test]
347 fn accepts_existing_unversioned_python_metadata() {
348 let metadata = CourseMetadata::from_json(r#"{"repertoire":{"side":"bLaCk"}}"#)
349 .expect("legacy metadata remains supported");
350
351 assert!(metadata.is_legacy());
352 assert_eq!(metadata.repertoire_side(), Some(RepertoireSide::Black));
353 }
354
355 #[test]
356 fn rejects_unsupported_versions_with_a_specific_error() {
357 let error = CourseMetadata::from_json(r#"{"schemaVersion":2}"#)
358 .expect_err("version 2 is not supported");
359
360 assert!(
361 matches!(error, MetadataError::UnsupportedSchemaVersion(version) if version == "2")
362 );
363 }
364
365 #[test]
366 fn validates_required_fields_and_unique_chapters() {
367 let error = CourseMetadata::from_json(
368 r#"{
369 "schemaVersion": 1,
370 "course": {"id":"course", "title":"Course", "kind":"repertoire"},
371 "chapters": [
372 {"id":"same", "title":"One"},
373 {"id":"same", "title":"Two"}
374 ],
375 "repertoire": {"side":"White"}
376 }"#,
377 )
378 .expect_err("duplicate chapter identifiers are ambiguous");
379
380 assert_eq!(error.to_string(), "duplicate chapter id \"same\"");
381 }
382
383 #[test]
384 fn rejects_lichess_mappings_for_undeclared_chapters() {
385 let error = CourseMetadata::from_json(
386 r#"{
387 "schemaVersion": 1,
388 "course": {"id":"course", "title":"Course", "kind":"repertoire"},
389 "chapters": [{"id":"declared", "title":"Declared"}],
390 "repertoire": {"side":"White"},
391 "lichess": {
392 "studyId":"study",
393 "chapters":{"missing":{"id":"chapter"}}
394 }
395 }"#,
396 )
397 .expect_err("publishing mappings must use stable declared chapter ids");
398
399 assert_eq!(
400 error.to_string(),
401 "Lichess mapping references unknown chapter \"missing\""
402 );
403 }
404
405 #[test]
406 fn future_problem_set_keeps_position_and_integer_objective_extensions() {
407 let metadata = CourseMetadata::from_json(SYNTHETIC_PROBLEM_SET)
408 .expect("synthetic fixture fits the common envelope");
409
410 assert_eq!(
411 metadata.course.as_ref().expect("course").kind,
412 CourseKind::ProblemSet
413 );
414 let problems = &metadata.extensions["problemSet"]["problems"];
415 assert_eq!(
416 problems[0]["start"]["fen"],
417 json!("7k/5Q2/6K1/8/8/8/8/8 b - - 0 1")
418 );
419 assert_eq!(problems[0]["objective"]["moves"], json!(1));
420
421 let round_trip = serde_json::to_value(&metadata).expect("metadata serializes");
422 assert_eq!(round_trip["problemSet"]["problems"], *problems);
423 }
424}