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