1// Schema lifecycle: experimental | stable | deprecated
  2@status("experimental")
  3package gemara
  4
  5@go(gemara)
  6
  7// GuidanceCatalog represents a concerted documentation effort to help bring about an optimal future without foreknowledge of the implementation details
  8#GuidanceCatalog: {
  9	#Catalog
 10	metadata: type: "GuidanceCatalog"
 11
 12	// type categorizes this document based on the intent of its contents
 13	type: #GuidanceType @go(GuidanceType)
 14
 15	// front-matter provides introductory text for the document to be used during rendering
 16	"front-matter"?: string @go(FrontMatter) @yaml("front-matter,omitempty")
 17
 18	// guidelines is a list of unique guidelines defined by this catalog
 19	guidelines?: [#Guideline, ...#Guideline] @go(Guidelines)
 20
 21	// exemptions provides information about situations where this guidance is not applicable
 22	exemptions?: [#Exemption, ...#Exemption] @go(Exemptions)
 23
 24	if guidelines != _|_ {
 25		_uniqueGuidelineIds: {for i, g in guidelines {(g.id): i}}
 26		groups: [#Group, ...#Group]
 27	}
 28}
 29
 30// GuidanceType restricts the possible types that a catalog may be listed as
 31#GuidanceType: "Standard" | "Regulation" | "Best Practice" | "Framework" @go(-)
 32
 33// Exemption describes a single scenario where the catalog is not applicable
 34#Exemption: {
 35	// description identifies who or what is exempt from the full guidance
 36	description: string
 37
 38	// reason explains why the exemption is granted
 39	reason: string
 40
 41	// redirect points to alternative guidelines or controls that should be followed instead
 42	redirect?: #MultiEntryMapping @go(Redirect,optional=nillable)
 43}
 44
 45// Guideline provides explanatory context and recommendations for designing optimal outcomes 
 46#Guideline: {
 47	// id allows this entry to be referenced by other elements
 48	id: string
 49
 50	// title describes the contents of this guideline
 51	title: string
 52
 53	// objective is a unified statement of intent, which may encompass multiple situationally applicable statements
 54	objective: string
 55
 56	// group provides an id to the group that this guideline belongs to
 57	group: string @go(Group)
 58
 59	// recommendations is a list of non-binding suggestions to aid in evaluation or enforcement of the guideline
 60	recommendations?: [string, ...string]
 61
 62	// extends is an id for a guideline which this guideline adds to, in this document or elsewhere
 63	extends?: #EntryMapping @go(Extends,optional=nillable)
 64
 65	// applicability specifies the contexts in which this guideline applies
 66	applicability?: [string, ...string] @go(Applicability)
 67
 68	// rationale provides the context for this guideline
 69	rationale?: #Rationale @go(Rationale,optional=nillable)
 70
 71	// statements is a list of structural sub-requirements within a guideline
 72	statements?: [#Statement, ...#Statement] @go(Statements)
 73
 74	// principles documents the relationship between this guideline and one or more principles
 75	"principles"?: [#MultiEntryMapping, ...#MultiEntryMapping] @go(Principles) @yaml("principles,omitempty")
 76
 77	// vector-mappings documents the relationship between this guideline and one or more vectors
 78	"vectors"?: [#MultiEntryMapping, ...#MultiEntryMapping] @go(Vectors) @yaml("vectors,omitempty")
 79
 80	// see-also lists related guideline IDs within the same GuidanceCatalog
 81	"see-also"?: [string, ...string] @go(SeeAlso) @yaml("see-also,omitempty")
 82
 83	// state is the lifecycle state of this guideline
 84	state: #Lifecycle @go(State) @yaml("state,omitempty")
 85
 86	// replaced-by references the guideline that supersedes this one when deprecated or retired
 87	"replaced-by"?: #EntryMapping @go(ReplacedBy,optional=nillable) @yaml("replaced-by,omitempty")
 88
 89	// retired guidelines must not have recommendations
 90	if state == "Retired" {
 91		recommendations?: _|_
 92	}
 93}
 94
 95// Statement represents a structural sub-requirement within a guideline;
 96// They do not increase strictness and all statements within a guideline apply together
 97#Statement: {
 98	// id allows this entry to be referenced by other elements
 99	id: string
100
101	// title describes the contents of this statement
102	title?: string
103
104	// text is the body of this statement
105	text: string
106
107	// recommendations is a list of non-binding suggestions to aid in evaluation or enforcement of the statement
108	recommendations?: [string, ...string]
109}
110
111// Rationale provides a structured way to communicate a guideline author's intent
112#Rationale: {
113	// importance is an explanation of why this guideline matters
114	importance: string
115
116	// goals is a list of outcomes this guideline seeks to achieve
117	goals: [string, ...string]
118}