1// SPDX-License-Identifier: Apache-2.0
 2
 3// Schema lifecycle: experimental | stable | deprecated
 4@status("stable")
 5package gemara
 6
 7@go(gemara)
 8
 9// EvaluationLog contains the results of evaluating a set of Layer 2 controls.
10#EvaluationLog: {
11	#Log
12	metadata: type: "EvaluationLog"
13	// result is the aggregate outcome across all evaluations in this log
14	result: #Result
15	evaluations: [#ControlEvaluation, ...#ControlEvaluation] @go(Evaluations,type=[]*ControlEvaluation)
16}
17
18// ControlEvaluation contains the results of evaluating a single Layer 5 control.
19#ControlEvaluation: {
20	name:    string
21	result:  #Result
22	message: string
23	control: #EntryMapping
24	"assessment-logs": [#AssessmentLog, ...#AssessmentLog] @go(AssessmentLogs,type=[]*AssessmentLog)
25	// Enforce that control reference and the assessments' references match
26	// This formulation uses the control's reference if the assessment doesn't include a reference
27	"assessment-logs": [...{
28		requirement: "reference-id": (control."reference-id")
29	}]
30	// Require start timestamp on assessments that actually executed
31	"assessment-logs": [#_AssessmentLogStrict, ...#_AssessmentLogStrict]
32}
33
34// _AssessmentLogStrict layers the "start required unless unexecuted" rule on top of #AssessmentLog
35#_AssessmentLogStrict: {
36	@go(-)
37} & #AssessmentLog & {
38	result: #Result
39	if result != "Not Run" && result != "Unknown" && result != "Not Applicable" {
40		start: #Datetime
41	}
42}
43
44// AssessmentLog contains the results of executing a single assessment procedure for a control requirement.
45#AssessmentLog: {
46	// Requirement should map to the assessment requirement for this assessment.
47	requirement: #EntryMapping
48	// Plan maps to the policy assessment plan being executed.
49	plan?: #EntryMapping @go(Plan,optional=nillable)
50	// Description provides a summary of the assessment procedure.
51	description: string
52	// Result is the overall outcome of the assessment procedure, matching the result of the last step that was run.
53	result: #Result
54	// Message provides additional context about the assessment result.
55	message: string
56	// Applicability is elevated from the Layer 2 Assessment Requirement to aid in execution and reporting.
57	applicability: [string, ...string] @go(Applicability,type=[]string)
58	// Steps are sequential actions taken as part of the assessment, which may halt the assessment if a failure occurs.
59	steps: [#AssessmentStep, ...#AssessmentStep]
60	// Steps-executed is the number of steps that were executed as part of the assessment.
61	"steps-executed"?: int @go(StepsExecuted)
62	// Start is the timestamp when the assessment began.
63	// Assessments that never executed have no start time to record.
64	start?: #Datetime
65
66	// End is the timestamp when the assessment concluded.
67	end?: #Datetime
68	// Recommendation provides guidance on how to address a failed assessment.
69	recommendation?: string
70	// ConfidenceLevel indicates the evaluator's confidence level in this specific assessment result.
71	"confidence-level"?: #ConfidenceLevel @go(ConfidenceLevel)
72	// Evidence records the raw data cited to support this assessment's opinion.
73	evidence?: [#Evidence, ...#Evidence] @go(Evidence)
74}
75
76#AssessmentStep: string @go(-)
77
78#Result: "Not Run" | "Passed" | "Failed" | "Needs Review" | "Not Applicable" | "Unknown" @go(-)