diff --git a/paths/evaluate/evaluate.yml b/paths/evaluate/evaluate.yml index ea197b2..12ae98f 100644 --- a/paths/evaluate/evaluate.yml +++ b/paths/evaluate/evaluate.yml @@ -366,6 +366,28 @@ post: - feedbackId: "fb-2" title: "Overall structure" message: "The overall structure of your answer is clear and easy to follow." + mathExampleResponse: + summary: Example feedback response for a MATH submission with case matching + value: + - feedbackId: "fb-math-1" + title: "Correct, matched expected case" + message: "Your answer matches the expected simplified form." + awardedPoints: 3 + response: + latex: "x+y" + sympy: "x + y" + matchedCase: 0 + target: + artefactType: "MATH" + format: "latex" + - feedbackId: "fb-math-2" + title: "No matching case" + message: "We parsed your answer but it didn't match any of the known cases." + awardedPoints: 0 + response: + latex: "x-y" + sympy: "x - y" + matchedCase: null "202": $ref: "./responses/202-Accepted.yml" "400": diff --git a/paths/evaluate/schemas/EvaluateRequest.yml b/paths/evaluate/schemas/EvaluateRequest.yml index 044d459..7663078 100644 --- a/paths/evaluate/schemas/EvaluateRequest.yml +++ b/paths/evaluate/schemas/EvaluateRequest.yml @@ -34,7 +34,9 @@ properties: preSubmissionFeedback: description: > Optional settings for pre-submission feedback (non-final). When enabled, - the service should avoid committing or finalizing grades. + the service should avoid committing or finalizing grades. The resulting + preview content is returned via the response Feedback items' `response` + field. type: - object - "null" diff --git a/paths/evaluate/schemas/Feedback.yml b/paths/evaluate/schemas/Feedback.yml index d1d293a..f5fdbc3 100644 --- a/paths/evaluate/schemas/Feedback.yml +++ b/paths/evaluate/schemas/Feedback.yml @@ -1,8 +1,9 @@ type: object description: > A single feedback item produced for the submission. It may include - suggested actions, optional points, optional criterion linkage, and - optional targeting into the submission. + suggested actions, optional points, optional criterion linkage, optional + targeting into the submission, optional normalized representation(s) of + the submission, and an optional matched-case index. properties: feedbackId: type: string @@ -42,3 +43,26 @@ properties: description: Optional target reference inside the submission. allOf: - $ref: "./FeedbackTarget.yml" + response: + type: + - object + - "null" + description: > + Optional normalized representation(s) of the submission as interpreted + by the service (e.g., a parsed or simplified rendering), keyed by + format — for example { latex: "x+y", sympy: "x + y" }. Also used to + carry pre-submission preview content when the request's + preSubmissionFeedback.enabled was set to true. + allOf: + - $ref: "../../shared/schemas/FormattedContent.yml" + matchedCase: + type: + - integer + - "null" + format: int32 + description: > + Optional index into a service-defined list of matching cases (e.g., a + Lambda Feedback-style "cases" list supplied under the request's + configuration object), when the service supports such a mechanism. + Null if no case matched. This is a provider-specific convention and is + not a formally defined construct in this spec. diff --git a/paths/evaluate/schemas/PreSubmissionFeedback.yml b/paths/evaluate/schemas/PreSubmissionFeedback.yml index 69abd63..b2302b4 100644 --- a/paths/evaluate/schemas/PreSubmissionFeedback.yml +++ b/paths/evaluate/schemas/PreSubmissionFeedback.yml @@ -1,5 +1,9 @@ type: object -description: Optional configuration for pre-submission feedback runs. +description: > + Optional configuration for pre-submission feedback runs. This only toggles + the mode; the actual preview content (e.g., normalized representations of + the submission) is returned in the /evaluate response, via each feedback + item's `response` field (see Feedback.yml) — not on this schema. required: - enabled additionalProperties: true diff --git a/paths/shared/schemas/FormattedContent.yml b/paths/shared/schemas/FormattedContent.yml new file mode 100644 index 0000000..087af1e --- /dev/null +++ b/paths/shared/schemas/FormattedContent.yml @@ -0,0 +1,9 @@ +type: + - object + - "null" +description: > + A set of representations of the same underlying content, keyed by an + arbitrary format id (e.g. "latex", "sympy", "formatted", "ast"). The + set of keys is service-defined and not enumerated by this spec. +additionalProperties: + type: string