1// SPDX-License-Identifier: Apache-2.0
 2
 3// Schema lifecycle: experimental | stable | deprecated
 4@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	url?: =~"^(https?|file)://[^\\s]+$"
25}
26
27// ArtifactMapping represents a mapping to an external artifact or artifact entry
28#ArtifactMapping: {
29	// reference-id identifies an element from a MappingReference in the artifact's metadata
30	"reference-id": string @go(ReferenceId)
31
32	// remarks is prose regarding the mapped artifact or the mapping relationship
33	remarks?: string
34}
35
36// MultiEntryMapping represents a mapping to an external reference with one or more entries.
37#MultiEntryMapping: {
38	// top-level reference to the MappingReference entry
39	#ArtifactMapping
40
41	// entries is a list of mapping entries
42	entries: [#ArtifactMapping, ...#ArtifactMapping] @go(Entries)
43}
44
45// EntryMapping represents how a specific entry maps to a MappingReference.
46#EntryMapping: {
47	// reference-id is the id for a MappingReference entry in the artifact's metadata
48	"reference-id": string @go(ReferenceId)
49
50	// entry-id is the identifier being mapped to in the referenced artifact
51	"entry-id": string @go(EntryId)
52
53	// remarks is prose describing the mapping relationship
54	remarks?: string
55}
56
57// EvidenceMapping identifies the source from which evidence was collected.
58// reference-id names the MappingReference; coordinate or entry-id gives
59// specificity within it; digest pins the observed content at collection time.
60#EvidenceMapping: {
61	// reference-id ties this evidence to a mapping-reference in the artifact's metadata
62	"reference-id": string @go(ReferenceId)
63
64	// coordinate is the precise location within the stream identified by reference-id
65	// (e.g. an API path, file path, or JSON path expression).
66	// Do not set if entry-id is set.
67	coordinate?: string
68
69	// entry-id identifies a specific entry within a referenced Gemara artifact.
70	// Do not set if coordinate is set.
71	"entry-id"?: string @go(EntryId)
72
73	// digest is a cryptographic hash of the observed content at collection time; format: algorithm:encoded (e.g. sha256:abc123...)
74	digest?: =~"^[a-z0-9]+(?:[+._-][a-z0-9]+)*:[a-zA-Z0-9=_-]+$"
75
76	// remarks is prose regarding this evidence reference
77	remarks?: string
78}