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// Policy represents a policy document with metadata, contacts, scope, imports, implementation plan, risks, and adherence requirements.
 10#Policy: {
 11	title:    string
 12	metadata: #Metadata
 13	metadata: type: "Policy"
 14	contacts:               #RACI
 15	scope:                  #Scope
 16	imports:                #Imports
 17	"implementation-plan"?: #ImplementationPlan @go(ImplementationPlan)
 18	risks?:                 #Risks
 19	adherence:              #Adherence
 20}
 21
 22// Scope defines what is included and excluded from policy applicability.
 23#Scope: {
 24	in:   #Dimensions
 25	out?: #Dimensions
 26}
 27
 28// Dimensions specify the applicability criteria for a policy
 29#Dimensions: {
 30	// technologies is an optional list of technology categories or services
 31	technologies?: [string, ...string]
 32	// geopolitical is an optional list of geopolitical regions
 33	geopolitical?: [string, ...string]
 34	// sensitivity is an optional list of data classification levels
 35	sensitivity?: [string, ...string]
 36	// users is an optional list of user roles
 37	users?: [string, ...string]
 38	groups?: [string, ...string]
 39}
 40
 41// Imports defines external policies, controls, and guidelines required by this policy.
 42#Imports: {
 43	policies?: [#ArtifactMapping, ...#ArtifactMapping]
 44	catalogs?: [#CatalogImport, ...#CatalogImport]
 45	guidance?: [#GuidanceImport, ...#GuidanceImport]
 46}
 47
 48// ImplementationPlan defines when and how the policy becomes active.
 49#ImplementationPlan: {
 50	"notification-process"?: string                 @go(NotificationProcess)
 51	"evaluation-timeline":   #ImplementationDetails @go(EvaluationTimeline)
 52	"enforcement-timeline":  #ImplementationDetails @go(EnforcementTimeline)
 53}
 54
 55// ImplementationDetails specifies the timeline for policy implementation.
 56#ImplementationDetails: {
 57	start: #Datetime
 58	end?:  #Datetime
 59	notes: string
 60}
 61
 62// Risks defines mitigated and accepted risks addressed by this policy.
 63#Risks: {
 64	// Mitigated risks only need reference-id and risk-id (no justification required)
 65	mitigated?: [#MitigatedRisk, ...#MitigatedRisk]
 66	// Accepted risks require rationale (justification) and may include scope. Controls addressing these risks are implicitly identified through threat mappings.
 67	accepted?: [#AcceptedRisk, ...#AcceptedRisk]
 68}
 69
 70// MitigatedRisk represents a risk addressed by the policy
 71#MitigatedRisk: {
 72	// id allows this mitigated risk entry to be referenced by accepted risks
 73	id: string
 74
 75	// risk references the risk being mitigated
 76	risk: #EntryMapping
 77}
 78
 79// AcceptedRisk documents a risk the organization has chosen to accept,
 80// optionally linking it to a mitigated risk when the acceptance covers
 81// residual risk after partial mitigation.
 82#AcceptedRisk: {
 83	// id allows this accepted risk entry to be referenced
 84	id: string
 85
 86	// target-id optionally links this acceptance to a mitigated risk entry
 87	"target-id"?: string
 88
 89	// risk references the risk being accepted
 90	risk: #EntryMapping
 91
 92	// scope defines where the risk acceptance applies
 93	scope?: #Scope
 94
 95	// justification explains why the risk is accepted
 96	justification?: string
 97}
 98
 99// Adherence defines evaluation methods, assessment plans, enforcement methods, and non-compliance notifications.
100#Adherence: {
101	"evaluation-methods"?: [#AcceptedMethod & {type: #EvaluationMethodType}, ...#AcceptedMethod & {type: #EvaluationMethodType}] @go(EvaluationMethods)
102	"assessment-plans"?: [#AssessmentPlan, ...#AssessmentPlan] @go(AssessmentPlans)
103	"enforcement-methods"?: [#AcceptedMethod & {type: #EnforcementMethodType}, ...#AcceptedMethod & {type: #EnforcementMethodType}] @go(EnforcementMethods)
104	"non-compliance"?: string @go(NonCompliance)
105}
106
107// AssessmentPlan defines how a specific assessment requirement is evaluated.
108#AssessmentPlan: {
109	id:               string
110	"requirement-id": string @go(RequirementId)
111	frequency:        string
112	"evaluation-methods": [#AcceptedMethod & {type: #EvaluationMethodType}, ...#AcceptedMethod & {type: #EvaluationMethodType}] @go(EvaluationMethods)
113	"evidence-requirements"?: string @go(EvidenceRequirements)
114	parameters?: [#Parameter, ...#Parameter]
115}
116
117// AcceptedMethod defines a method for evaluation or enforcement.
118#AcceptedMethod: {
119	id:           string
120	type:         #MethodType
121	mode:         #ModeType
122	required:     *false | bool
123	description?: string
124	executor?:    #Actor
125}
126
127#ModeType:              "Manual" | "Automated"                           @go(-)
128#MethodType:            "Behavioral" | "Intent" | "Remediation" | "Gate" @go(-)
129#EvaluationMethodType:  "Intent" | "Behavioral"                          @go(-)
130#EnforcementMethodType: "Gate" | "Remediation"                           @go(-)
131
132// Parameter defines a configurable parameter for assessment or enforcement activities.
133#Parameter: {
134	id:          string
135	label:       string
136	description: string
137	"accepted-values"?: [string, ...string] @go(AcceptedValues)
138}
139
140// GuidanceImport defines how to import guidance documents with optional exclusions and constraints.
141#GuidanceImport: {
142	"reference-id": string @go(ReferenceId)
143	exclusions?: [string, ...string]
144	// Constraints allow policy authors to define ad hoc minimum requirements (e.g., "review at least annually").
145	constraints?: [#Constraint, ...#Constraint]
146}
147
148// CatalogImport defines how to import control catalogs with optional exclusions, constraints, and assessment requirement modifications.
149#CatalogImport: {
150	"reference-id": string @go(ReferenceId)
151	exclusions?: [string, ...string]
152	constraints?: [#Constraint, ...#Constraint]
153	"assessment-requirement-modifications"?: [#AssessmentRequirementModifier, ...#AssessmentRequirementModifier] @go(AssessmentRequirementModifications)
154}
155
156// Constraint defines a prescriptive requirement that applies to a specific guidance or control.
157#Constraint: {
158	// Unique ID for this constraint to enable Layer 5/6 tracking
159	id: string
160	// Links to the specific Guidance or Control being constrained
161	"target-id": string @go(TargetId)
162	// The prescriptive requirement/constraint text
163	text: string
164}
165
166// AssessmentRequirementModifier allows organizations to customize assessment requirements based on how an organization wants to gather evidence for the objective.
167#AssessmentRequirementModifier: {
168	id:                       string
169	"target-id":              string   @go(TargetId)
170	"modification-type":      #ModType @go(ModificationType)
171	"modification-rationale": string   @go(ModificationRationale)
172	// The updated text of the assessment requirement
173	text?: string
174	// The updated applicability of the assessment requirement
175	applicability?: [string, ...string]
176	// The updated recommendation for the assessment requirement
177	recommendation?: string
178}
179
180// ModType defines the type of modification to the assessment requirement.
181#ModType: "Add" | "Modify" | "Remove" | "Replace" | "Override" @go(-)