1// Schema lifecycle: experimental | stable | deprecated
 2@status("experimental")
 3package gemara
 4
 5@go(gemara)
 6
 7// ControlCatalog describes a set of related controls and relevant metadata
 8#ControlCatalog: {
 9	#Catalog
10	metadata: type: "ControlCatalog"
11
12	// controls is a list of unique controls defined by this catalog
13	controls?: [#Control, ...#Control] @go(Controls)
14
15	if controls != _|_ {
16		_uniqueControlIds: {for i, c in controls {(c.id): i}}
17		groups: [#Group, ...#Group]
18	}
19}
20
21// Control describes a safeguard or countermeasure with a clear objective and assessment requirements
22#Control: {
23	// id allows this entry to be referenced by other elements
24	id: string
25
26	// title describes the purpose of this control at a glance
27	title: string
28
29	// objective is a unified statement of intent, which may encompass multiple situationally applicable requirements
30	objective: string
31
32	// group references by id a catalog group that this control belongs to
33	group: string @go(Group)
34
35	// assessment-requirements is a list of requirements that must be verified to confirm the control objective has been met
36	"assessment-requirements": [#AssessmentRequirement, ...#AssessmentRequirement] @go(AssessmentRequirements)
37
38	// guidelines documents relationships between this control and Layer 1 guideline artifacts
39	guidelines?: [#MultiEntryMapping, ...#MultiEntryMapping] @go(Guidelines)
40
41	// threats documents relationships between this control and Layer 2 threat artifacts
42	threats?: [#MultiEntryMapping, ...#MultiEntryMapping] @go(Threats)
43
44	// state is the lifecycle state of this control
45	state: #Lifecycle @go(State) @yaml("state,omitempty")
46
47	// replaced-by references the control that supersedes this one when deprecated or retired
48	"replaced-by"?: #EntryMapping @go(ReplacedBy,optional=nillable) @yaml("replaced-by,omitempty")
49}
50
51// AssessmentRequirement describes a tightly scoped, verifiable condition that must be satisfied and confirmed by an evaluator
52#AssessmentRequirement: {
53	// id allows this entry to be referenced by other elements
54	id: string
55
56	// text is the body of the requirement, typically written as a MUST condition
57	text: string
58
59	// applicability is a list of strings describing the situations where this text functions as a requirement for its parent control
60	applicability: [string, ...string]
61
62	// recommendation provides readers with non-binding suggestions to aid in evaluation or enforcement of the requirement
63	recommendation?: string
64
65	// state is the lifecycle state of this assessment requirement
66	state: #Lifecycle @go(State) @yaml("state,omitempty")
67
68	// replaced-by references the assessment requirement that supersedes this one when deprecated or retired
69	"replaced-by"?: #EntryMapping @go(ReplacedBy,optional=nillable) @yaml("replaced-by,omitempty")
70
71	// retired assessment requirements must not have a recommendation
72	if state == "Retired" {
73		recommendation?: _|_
74	}
75}