Merge pull request #190 from layer5io/issue/887-canonical-quiz-json

leecalcote · web-flow · commit 75bdc9fb9623 · 2026-05-07T14:55:37.000-05:00
fix: emit canonical academy quiz JSON
diff --git a/README.md b/README.md
@@ -69,6 +69,22 @@ the build can emit warnings or break shared assumptions for other content.
 Shared theme assets, icons, and reusable partials should stay in
 academy-theme itself rather than in a consuming org repository.
 
+## Quiz JSON contract
+
+Quiz JSON emitted by the `test` layouts is normalized toward the
+`meshery/schemas` academy Quiz contract. The generated JSON now uses
+canonical quiz/question field names, numeric `timeLimit`, hyphenated question
+types, and UUIDs for page, parent, question, and option IDs.
+
+Authors can still keep front matter ergonomic:
+
+- page, question, and option `id` values may stay short slugs;
+- legacy snake_case quiz keys such as `pass_percentage`, `time_limit`,
+  `max_attempts`, `correct_answer`, and `is_correct` are still accepted in
+  front matter during the transition;
+- emitted UUIDs are derived deterministically from the content file path plus
+  the authored ID, so repeated builds produce stable values.
+
 ## ID Validation
 
 The theme checks publishable root Academy content during Hugo builds and emits
diff --git a/archetypes/final-test.md b/archetypes/final-test.md
@@ -1,69 +1,70 @@
 ---
 title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 final: true # Indicates that this test is the final exam and must be completed to complete the course , module or section
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   # NOTE: The 'marks' field must be a positive number (greater than 0). Negative or zero values will cause a build error.
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
   - id: "q4"
     text: "What are the purposes of the 'defer' keyword in Go? (Select all that apply)"
-    type: "multiple_answers"
+    type: "multiple-answers"
     marks: 2
     explanation: "The defer keyword is commonly used to delay function execution until the surrounding function returns, often used for cleanup tasks like closing files."
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---
diff --git a/archetypes/optional-test.md b/archetypes/optional-test.md
@@ -1,69 +1,70 @@
 ---
 title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 is_optional: true # Indicates that this test is optional and does not need to be completed to take the final exam
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   # NOTE: The 'marks' field must be a positive number (greater than 0). Negative or zero values will cause a build error.
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
   - id: "q4"
     text: "What are the purposes of the 'defer' keyword in Go? (Select all that apply)"
-    type: "multiple_answers"
+    type: "multiple-answers"
     marks: 2
     explanation: "The defer keyword is commonly used to delay function execution until the surrounding function returns, often used for cleanup tasks like closing files."
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---
diff --git a/archetypes/test.md b/archetypes/test.md
@@ -1,49 +1,50 @@
 ---
 title: 'test'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
-max_attempts: 3 # Maximum number of attempts allowed
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
+maxAttempts: 3 # Maximum number of attempts allowed
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
@@ -55,14 +56,14 @@ questions:
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---
diff --git a/layouts/partials/academy/derive-uuid.html b/layouts/partials/academy/derive-uuid.html
@@ -0,0 +1,13 @@
+{{- $scope := trim (printf "%v" .scope) " \n\r\t" -}}
+{{- $name := trim (printf "%v" .name) " \n\r\t" -}}
+{{- $digest := lower (sha1 (printf "academy-theme:%s:%s" $scope $name)) -}}
+{{- $variantSource := substr $digest 16 1 -}}
+{{- $variant := "b" -}}
+{{- if in "0123" $variantSource -}}
+  {{- $variant = "8" -}}
+{{- else if in "4567" $variantSource -}}
+  {{- $variant = "9" -}}
+{{- else if in "89ab" $variantSource -}}
+  {{- $variant = "a" -}}
+{{- end -}}
+{{- printf "%s-%s-5%s-%s%s-%s" (substr $digest 0 8) (substr $digest 8 4) (substr $digest 13 3) $variant (substr $digest 17 3) (substr $digest 20 12) -}}
diff --git a/layouts/partials/academy/normalize-id.html b/layouts/partials/academy/normalize-id.html
@@ -0,0 +1,10 @@
+{{- $value := trim (printf "%v" .value) " \n\r\t" -}}
+{{- $scope := trim (printf "%v" .scope) " \n\r\t" -}}
+{{- if eq $value "" -}}
+  {{- $value = $scope -}}
+{{- end -}}
+{{- if gt (len (findRE `(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$` $value)) 0 -}}
+  {{- lower $value -}}
+{{- else -}}
+  {{- partial "academy/derive-uuid.html" (dict "scope" $scope "name" $value) -}}
+{{- end -}}
diff --git a/layouts/partials/id.html b/layouts/partials/id.html
@@ -1,6 +1,3 @@
-{{- $id := .Params.id -}}
-{{- if $id -}}
-  {{- $id -}}
-{{- else -}}
-  {{- .RelPermalink | md5 -}}
-{{- end -}}
+{{- $id := .Params.id | default .RelPermalink -}}
+{{- $scope := or .File.Path .RelPermalink -}}
+{{- partial "academy/normalize-id.html" (dict "value" $id "scope" $scope) -}}
diff --git a/layouts/partials/test/normalize-question-option.html b/layouts/partials/test/normalize-question-option.html
@@ -0,0 +1,10 @@
+{{- $option := .option -}}
+{{- $index := .index -}}
+{{- $questionScope := printf "%v" .questionScope -}}
+{{- $optionKey := trim (printf "%v" (or $option.id (printf "option-%d" (add $index 1)))) " \n\r\t" -}}
+
+{{- return (dict
+  "id" (partial "academy/normalize-id.html" (dict "value" $optionKey "scope" (printf "%s#option:%s" $questionScope $optionKey)))
+  "text" (printf "%v" (or $option.text ""))
+  "isCorrect" (or $option.isCorrect $option.is_correct false)
+) -}}
diff --git a/layouts/partials/test/normalize-question.html b/layouts/partials/test/normalize-question.html
@@ -0,0 +1,70 @@
+{{- $question := .question -}}
+{{- $index := .index -}}
+{{- $quizFilePath := printf "%v" .filePath -}}
+{{- $questionKey := trim (printf "%v" (or $question.id (printf "question-%d" (add $index 1)))) " \n\r\t" -}}
+{{- $questionScope := printf "%s#question:%s" $quizFilePath $questionKey -}}
+{{- $questionType := lower (replace (printf "%v" (or $question.type "single-answer")) "_" "-") -}}
+{{- $options := slice -}}
+{{- $correctOptionIds := slice -}}
+{{- $optionIdMap := dict -}}
+
+{{- range $optionIndex, $option := ($question.options | default (slice)) -}}
+  {{- $optionKey := trim (printf "%v" (or $option.id (printf "option-%d" (add $optionIndex 1)))) " \n\r\t" -}}
+  {{- $canonicalOption := partial "test/normalize-question-option.html" (dict
+    "index" $optionIndex
+    "option" $option
+    "questionScope" $questionScope
+  ) -}}
+  {{- $options = $options | append $canonicalOption -}}
+  {{- $optionIdMap = merge $optionIdMap (dict $optionKey $canonicalOption.id) -}}
+  {{- if $canonicalOption.isCorrect -}}
+    {{- $correctOptionIds = $correctOptionIds | append $canonicalOption.id -}}
+  {{- end -}}
+{{- end -}}
+
+{{- $correctAnswer := trim (printf "%v" (or $question.correctAnswer $question.correct_answer "")) " \n\r\t" -}}
+{{- if eq $correctAnswer "" -}}
+  {{- if eq $questionType "multiple-answers" -}}
+    {{- $correctAnswer = delimit $correctOptionIds "," -}}
+  {{- else if gt (len $correctOptionIds) 0 -}}
+    {{- $correctAnswer = index $correctOptionIds 0 -}}
+  {{- end -}}
+{{- else if or (eq $questionType "multiple-answers") (eq $questionType "single-answer") -}}
+  {{- $normalizedAnswers := slice -}}
+  {{- range (split $correctAnswer ",") -}}
+    {{- $answer := trim . " \n\r\t" -}}
+    {{- if ne $answer "" -}}
+      {{- if isset $optionIdMap $answer -}}
+        {{- $normalizedAnswers = $normalizedAnswers | append (index $optionIdMap $answer) -}}
+      {{- else -}}
+        {{- $normalizedAnswers = $normalizedAnswers | append $answer -}}
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+  {{- if eq $questionType "multiple-answers" -}}
+    {{- $correctAnswer = delimit $normalizedAnswers "," -}}
+  {{- else if gt (len $normalizedAnswers) 0 -}}
+    {{- $correctAnswer = index $normalizedAnswers 0 -}}
+  {{- else -}}
+    {{- $correctAnswer = "" -}}
+  {{- end -}}
+{{- end -}}
+
+{{- $canonicalQuestion := dict
+  "id" (partial "academy/normalize-id.html" (dict "value" $questionKey "scope" $questionScope))
+  "text" (printf "%v" (or $question.text ""))
+  "type" $questionType
+  "marks" (int (or $question.marks 0))
+  "explanation" (printf "%v" (or $question.explanation ""))
+  "caseSensitive" (or $question.caseSensitive $question.case_sensitive false)
+  "options" $options
+  "correctAnswer" $correctAnswer
+-}}
+
+{{- if or (eq $questionType "multiple-answers") (eq $questionType "single-answer") $question.multipleAnswers $question.multiple_answers -}}
+  {{- $canonicalQuestion = merge $canonicalQuestion (dict
+    "multipleAnswers" (or $question.multipleAnswers $question.multiple_answers (eq $questionType "multiple-answers"))
+  ) -}}
+{{- end -}}
+
+{{- return $canonicalQuestion -}}
diff --git a/layouts/partials/test/single.html b/layouts/partials/test/single.html
