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