1// Schema lifecycle: experimental | stable | deprecated
  2@status("experimental")
  3package gemara
  4
  5@go(gemara)
  6
  7// MappingDocument captures the user's intent for how entries in a source artifact relate to entries in a target artifact
  8#MappingDocument: {
  9	// title describes the purpose of this mapping document at a glance
 10	title: string
 11
 12	// metadata provides detailed data about this document
 13	metadata: #Metadata @go(Metadata)
 14	metadata: type: "MappingDocument"
 15	metadata: "mapping-references": [#MappingReference, ...#MappingReference]
 16
 17	// source-reference identifies the artifact being mapped from; must match a mapping-reference id
 18	"source-reference": #ArtifactMapping @go(SourceReference)
 19
 20	// target-reference identifies the artifact being mapped to; must match a mapping-reference id
 21	"target-reference": #ArtifactMapping @go(TargetReference)
 22
 23	// mappings is one or more atomic relationships between entries in the referenced artifacts
 24	mappings: [#_MappingStrict, ...#_MappingStrict] @go(Mappings,type=[]Mapping)
 25
 26	_uniqueMappingIds: {for i, m in mappings {(m.id): i}}
 27
 28	// remarks is prose regarding this mapping document
 29	remarks?: string
 30}
 31
 32// _MappingStrict layers the "target required when not no-match" rule on top of #Mapping
 33#_MappingStrict: {
 34	@go(-)
 35} & #Mapping & {
 36	relationship: #RelationshipType
 37	if relationship != "no-match" {
 38		target: #TypedEntry
 39	}
 40}
 41
 42// Mapping represents an atomic relationship between a source entry and an optional target entry
 43#Mapping: {
 44	// id allows this mapping to be referenced by other elements
 45	id: string
 46
 47	// source identifies the entry being mapped from
 48	source: #TypedEntry @go(Source)
 49
 50	// target identifies the entry being mapped to; absent when relationship is no-match
 51	target?: #TypedEntry @go(Target,optional=nillable)
 52
 53	// relationship describes the nature or purpose of the mapping
 54	relationship: #RelationshipType @go(Relationship)
 55
 56	// strength is the author's estimate of how completely the source entry satisfies the target entry; range 1-10
 57	strength?: int & >=1 & <=10 @go(Strength)
 58
 59	"confidence-level"?: #ConfidenceLevel @go(ConfidenceLevel)
 60
 61	// applicability constrains the contexts in which this mapping holds
 62	applicability?: [string, ...string] @go(Applicability)
 63
 64	// rationale explains why this relationship exists
 65	rationale?: string
 66
 67	// remarks is general prose regarding this mapping
 68	remarks?: string
 69}
 70
 71// RelationshipType enumerates the nature of the mapping between entries.
 72#RelationshipType:
 73	// source fulfills the target's objective
 74	"implements" |
 75	// target fulfills the source's objective (requirements-to-implementation direction)
 76	"implemented-by" |
 77	// source contributes to, but does not fully satisfy, the target
 78	"supports" |
 79	// target contributes to, but does not fully satisfy, the source
 80	"supported-by" |
 81	// source and target express the same intent
 82	"equivalent" |
 83	// source fully contains the target's scope and more
 84	"subsumes" |
 85	// source has no counterpart in the target artifact
 86	"no-match" |
 87	// source and target are related but the nature is unspecified
 88	"relates-to" @go(-)
 89
 90// EntryReference identifies a specific entry within a referenced artifact
 91#TypedEntry: {
 92	// entry-id identifies the specific entry in the referenced artifact
 93	"entry-id": string @go(EntryId)
 94
 95	// entry-type identifies what kind of atomic unit this entry is
 96	"entry-type": #EntryType @go(EntryType)
 97}
 98
 99// EntryType enumerates the atomic units within Gemara artifacts that can participate in mappings
100#EntryType: "Guideline" | "Statement" | "Control" | "AssessmentRequirement" | "Capability" | "Threat" | "Risk" | "Vector" @go(-)
101
102// ConfidenceLevel indicates the evaluator's confidence level in an assessment result.
103#ConfidenceLevel: "Undetermined" | "Low" | "Medium" | "High" @go(-)