1// SPDX-License-Identifier: Apache-2.0
 2
 3// Schema lifecycle: experimental | stable | deprecated
 4@gemara(status="stable")
 5
 6package gemara
 7
 8// MappingReference represents a reference to an external document with full metadata.
 9#MappingReference: {
10	// id identifies this mapping reference within the artifact and, when url
11	// is absent, the referenced artifact's metadata.id.
12	id: string
13
14	// title describes the purpose of this mapping reference at a glance
15	title: string
16
17	// version is the version identifier of the artifact being mapped to
18	version: string
19
20	// description is prose regarding the artifact's purpose or content
21	description?: string
22
23	// url is the path where the artifact may be retrieved; preferably responds with Gemara-compatible YAML/JSON.
24	// Any URI scheme is accepted (e.g. https, file, oci, s3, arn) so evidence can be
25	// addressed wherever it actually lives.
26	url?: =~"^[a-zA-Z][a-zA-Z0-9+.-]*:[^\\s]+$"
27}
28
29// ArtifactMapping represents a mapping to an external artifact or artifact entry
30#ArtifactMapping: {
31	// reference-id identifies an element from a MappingReference in the artifact's metadata
32	"reference-id": string @go(ReferenceId)
33
34	// remarks is prose regarding the mapped artifact or the mapping relationship
35	remarks?: string
36}
37
38// MultiEntryMapping represents a mapping to an external reference with one or more entries.
39#MultiEntryMapping: {
40	// top-level reference to the MappingReference entry
41	#ArtifactMapping
42
43	// entries is a list of mapping entries
44	entries: [#ArtifactMapping, ...#ArtifactMapping] @go(Entries)
45}
46
47// EntryMapping represents how a specific entry maps to a MappingReference.
48#EntryMapping: {
49	// reference-id is the id for a MappingReference entry in the artifact's metadata
50	"reference-id": string @go(ReferenceId)
51
52	// entry-id is the identifier being mapped to in the referenced artifact
53	"entry-id": string @go(EntryId)
54
55	// remarks is prose describing the mapping relationship
56	remarks?: string
57}
58
59// EvidenceMapping identifies the source from which evidence was collected.
60// reference-id names the MappingReference; coordinate or entry-id gives
61// specificity within it; digest pins the observed content at collection time.
62#EvidenceMapping: {
63	// reference-id ties this evidence to a mapping-reference in the artifact's metadata
64	"reference-id": string @go(ReferenceId)
65
66	// coordinate is the precise location within the stream identified by reference-id
67	// (e.g. an API path, file path, or JSON path expression). May be combined with
68	// entry-id to identify a sub-location within that entry's output.
69	coordinate?: string
70
71	// entry-id identifies a specific entry within a referenced Gemara artifact.
72	// May be combined with coordinate to identify a sub-location within that entry's output.
73	"entry-id"?: string @go(EntryId)
74
75	// digest is a cryptographic hash of the observed content at collection time; format: algorithm:encoded (e.g. sha256:abc123...)
76	digest?: =~"^[a-z0-9]+(?:[+._-][a-z0-9]+)*:[a-zA-Z0-9=_-]+$"
77
78	// remarks is prose regarding this evidence reference
79	remarks?: string
80}