1// SPDX-License-Identifier: Apache-2.0
 2
 3// Schema lifecycle: experimental | stable | deprecated
 4@status("experimental")
 5package gemara
 6
 7@go(gemara)
 8
 9// AuditLog records results from an audit performed against a target resource
10#AuditLog: {
11	#Log
12	metadata: type: "AuditLog"
13
14	// owner defines the RACI roles responsible for managing the audit
15	owner?: #RACI @go(Owner)
16
17	// summary provides the high-level conclusion
18	summary: string
19
20	// criteria defines the acceptable state for the audited resource
21	criteria: [#ArtifactMapping, ...#ArtifactMapping]
22
23	// results records audit results against the criteria
24	results: [#AuditResult, ...#AuditResult] @go(Results,type=[]*AuditResult)
25
26	if results != _|_ {
27		_uniqueResultIds: {for i, r in results {(r.id): i}}
28	}
29}
30
31// ResultType classifies the nature of an audit result
32#ResultType: "Gap" | "Finding" | "Observation" | "Strength" @go(-)
33
34// AuditResult records a single result with supporting evidence and recommendations.
35#AuditResult: {
36	// id uniquely identifies this result
37	id: string
38
39	// title describes this result at a glance
40	title: string
41
42	// type classifies the nature of this result
43	type: #ResultType
44
45	// description explains the result in detail
46	description: string
47
48	// criteria-reference maps this result to specific criteria entries
49	"criteria-reference": #MultiEntryMapping @go(CriteriaReference)
50
51	// evidence records the data sources that support this result
52	evidence?: [#Evidence, ...#Evidence] @go(Evidence)
53
54	// recommendations records corrective actions for this result
55	recommendations?: [#Recommendation, ...#Recommendation] @go(Recommendations)
56}
57
58// Recommendation provides a corrective action for an audit result
59#Recommendation: {
60	// id uniquely identifies this recommendation
61	id?: string
62
63	// text describes the recommended corrective action
64	text: string
65
66	// required indicates whether this recommendation is a mandatory corrective action
67	required: *false | bool
68}
69
70// Evidence records what was cited to support an opinion for a specific activity:
71// raw data for the evaluation layer, evaluation and enforcement artifacts for the audit layer.
72#Evidence: {
73	// id uniquely identifies this evidence
74	id: string
75
76	// type categorizes the kind of evidence
77	type: #EvidenceType
78
79	// collected-at is the timestamp when the evidence was gathered
80	"collected-at": #Datetime @go(CollectedAt)
81
82	// payload is the raw evidence data collected
83	payload?: _ @go(Payload,type=any)
84
85	// description explains what this evidence represents
86	description?: string
87}
88
89// EvidenceType categorizes the kind of evidence. It remains an open enum:
90// recommended values include artifact types already known to Gemara (e.g.
91// EvaluationLog, EnforcementLog) plus categories for common evidence forms.
92#EvidenceType: #ArtifactType | string @go(-)