1// SPDX-License-Identifier: Apache-2.0
 2
 3// Schema lifecycle: experimental | stable | deprecated
 4@gemara(status="stable")
 5package gemara
 6
 7@go(gemara)
 8
 9// Entity represents a human or tool
10#Entity: {
11	// id uniquely identifies the entity and allows this entry to be referenced by other elements
12	id: string
13
14	// name is the name of the entity
15	name: string
16
17	// type specifies the type of entity interacting in the workflow
18	type: #EntityType
19
20	// version is the version of the entity (for tools; if applicable)
21	version?: string
22
23	// description provides additional context about the entity
24	description?: string
25
26	// uri is a general URI for the entity information.
27	// Any URI scheme is accepted (e.g. https, file, oci, s3, arn) so entities
28	// hosted outside http(s) can be referenced.
29	uri?: =~"^[a-zA-Z][a-zA-Z0-9+.-]*:[^\\s]+$"
30}
31
32// Actor represents an entity (human or tool) that performs actions in evaluations
33#Actor: {
34	#Entity
35
36	// contact is contact information for the actor
37	contact?: #Contact @go(Contact)
38}
39
40// Resource represents an entity that exists in the system and can be evaluated
41#Resource: {
42	#Entity
43
44	// environment describes where the resource exists (e.g., production, staging, development, specific region)
45	environment?: string @go(Environment)
46
47	// owner is the contact information for the person or group responsible for managing or owning this resource
48	owner?: #Contact @go(Owner)
49}
50
51// EntityType specifies what entity is interacting in the workflow
52#EntityType: "Human" | "Software" | "Software Assisted" @go(-)
53
54// Contact is the contact information for a person or group
55#Contact: {
56	// name is the preferred descriptor for the contact entity
57	name: string
58
59	// affiliation is the organization with which the contact entity is associated, such as a team, school, or employer
60	affiliation?: string @go(Affiliation,type=*string)
61
62	// email is the preferred email address to reach the contact
63	email?: #Email @go(Email,type=*Email)
64
65	// social is a social media handle or other profile for the contact, such as GitHub
66	social?: string @go(Social,type=*string)
67}
68
69// Email represents a validated email address pattern
70#Email: =~"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"
71
72// RACI defines the roles responsible for managing an artifact
73#RACI: {
74	// responsible identifies the entities responsible for executing work to manage or mitigate the artifact
75	responsible: [#Contact, ...#Contact]
76
77	// accountable identifies the entity ultimately accountable for the outcome
78	accountable: [#Contact, ...#Contact]
79
80	// consulted identifies entities whose input is required when assessing or responding to the artifact
81	consulted?: [#Contact, ...#Contact]
82
83	// informed identifies entities that should be notified about changes to the artifact status
84	informed?: [#Contact, ...#Contact]
85}