Skip to content

Commit c73c136

Browse files
xibzxibz
committed
feat(schema): Add approval events
Introduces three new event types to model the lifecycle of an approval request in a CI/CD pipeline or workflow. Many CI/CD systems require a formal decision point before execution can continue, like a deployment to production, a release cut, or a regulated change proceeding through a pipeline. The decision may come from a human approver, an automated policy engine, an external compliance system, or any other entity capable of authorizing progression. There is currently no canonical CDEvents representation for this pattern, leaving teams to model approvals through customData or out of band mechanisms with no shared traversal or governance model. **approval.created**: emitted when an approval request is initiated. Captures the requestor and references to the approval details and the resource being gated. **approval.updated**: emitted when a non-terminal decision is recorded or when the resource target of the approval changes. Supports flows where multiple decisions may be recorded before a terminal state is reached, whether from humans, automated systems, or a combination. **approval.closed**: emitted when the approval reaches a terminal state. Captures the final decision, the responder, and the terminal status: Approved, Rejected, Cancelled, or Expired. All three events share a common core: - `approvalDetailsUrl`: reference URL to the approval request page - `resourceTargetUrl`: reference URL to the resource being gated approval.created adds: - `requestor`: the entity that initiated the approval request approval.updated and approval.closed add: - `responder`: the entity that recorded a decision (URN format) - `decision`: the decision selected by the responder approval.closed additionally adds: - `status`: example terminal state: approved, rejected, cancelled, expired - Deployment gates requiring sign-off before production rollout - Automated policy checks that must authorize pipeline progression - Regulated change management pipelines requiring auditable approval records - Multistage release workflows where approvals gate progression between environments - Compliance workflows requiring documented authorization before sensitive operations - External system integrations where a thirdparty tool must approve before execution continues
1 parent 75c261b commit c73c136

4 files changed

Lines changed: 409 additions & 0 deletions

File tree

‎schemas/_defs/approval.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"$id": "cdevents/_defs/approval",
3+
"term": "Approval",
4+
"definition": "A formal decision point in a pipeline or workflow where an identifiable entitym, human or automated, makes an accountable authorization decision that determines whether execution continues. Unlike an evaluation, an approval requires a responder whose decision could have gone differently and can be attributed and audited. An approval has a lifecycle: it is created, may receive one or more non-terminal decisions, and is eventually resolved into a terminal state.",
5+
"notes": [
6+
"An approval is distinct from the resource it gates, and references the resource via resourceTargetUrl but does not describe it. Use the appropriate event type for the resource itself.",
7+
"A single approval may receive multiple decisions before reaching a terminal state, supporting both human approver flows and automated policy engines.",
8+
"The responder may be a human identity, an automated system, or any external entity capable of authorizing progression."
9+
],
10+
"examples": [
11+
"A deployment gate requiring human sign-off before a production rollout proceeds",
12+
"An automated policy engine authorizing a pipeline to continue after a compliance check",
13+
"A regulated change management gate requiring auditable authorization before a release",
14+
"A maintenance window system authorizing a deployment to proceed when the window opens",
15+
"An external compliance system that must approve before a sensitive operation executes"
16+
],
17+
"counterExamples": [
18+
"A unit test suite asserting code correctness before a build proceeds",
19+
"An automated linter check that blocks a pull request",
20+
"A readiness probe or health check that gates a rollout",
21+
"A budget threshold check that must be satisfied before a resource is provisioned"
22+
]
23+
}

‎schemas/approvalclosed.json‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://cdevents.dev/0.6.0-draft/schema/approval-closed-event",
4+
"x-cdevents-semantics": {
5+
"subject": "cdevents/_defs/approval"
6+
},
7+
"properties": {
8+
"context": {
9+
"properties": {
10+
"specversion": {
11+
"type": "string",
12+
"minLength": 1
13+
},
14+
"id": {
15+
"type": "string",
16+
"minLength": 1
17+
},
18+
"source": {
19+
"type": "string",
20+
"minLength": 1,
21+
"format": "uri-reference"
22+
},
23+
"type": {
24+
"type": "string",
25+
"enum": [
26+
"dev.cdevents.approval.closed.0.1.0"
27+
],
28+
"default": "dev.cdevents.approval.closed.0.1.0"
29+
},
30+
"timestamp": {
31+
"type": "string",
32+
"format": "date-time"
33+
},
34+
"schemaUri": {
35+
"type": "string",
36+
"minLength": 1,
37+
"format": "uri"
38+
},
39+
"chainId": {
40+
"type": "string",
41+
"minLength": 1
42+
},
43+
"links": {
44+
"$ref": "links/embeddedlinksarray"
45+
},
46+
},
47+
"additionalProperties": false,
48+
"type": "object",
49+
"required": [
50+
"specversion",
51+
"id",
52+
"source",
53+
"type",
54+
"timestamp"
55+
]
56+
},
57+
"subject": {
58+
"properties": {
59+
"id": {
60+
"type": "string",
61+
"minLength": 1
62+
},
63+
"content": {
64+
"properties": {
65+
"approvalDetailsUrl": {
66+
"type": "string",
67+
"minLength": 1,
68+
"$comment": "Reference URL to the approval request in the originating system. Consumers with appropriate access can retrieve the full approval context, history, and decisions from this URL. This provides the canonical location of the approval record."
69+
},
70+
"resourceTargetUrl": {
71+
"type": "string",
72+
"minLength": 1,
73+
"$comment": "Reference URL to the resource whose progression is gated by this approval. The approval does not describe the resource, but the URL allows consumers to retrieve resource information directly from the system that owns it."
74+
},
75+
"responder": {
76+
"type": "string",
77+
"format": "urn",
78+
"$comment": "URN identifying the entity that recorded this decision. May be a human identity, a service account, or an automated system."
79+
},
80+
"decision": {
81+
"type": "string",
82+
"$comment": "The final decision recorded by the responder that resolved this approval."
83+
},
84+
"status": {
85+
"type": "string",
86+
"enum": [
87+
"Approved",
88+
"Rejected",
89+
"Cancelled",
90+
"Expired"
91+
],
92+
"$comment": "The terminal state of the approval. Approved is an authorized to proceed. Rejected is explicitly denied. Cancelled is withdrawn before resolution. Expired is no decision was reached within the allowed time."
93+
}
94+
},
95+
"additionalProperties": false,
96+
"type": "object",
97+
"required": [
98+
"approvalDetailsUrl",
99+
"resourceTargetUrl",
100+
"responder",
101+
"decision",
102+
"status"
103+
]
104+
}
105+
},
106+
"additionalProperties": false,
107+
"type": "object",
108+
"required": [
109+
"id",
110+
"content"
111+
]
112+
},
113+
"customData": {
114+
"oneOf": [
115+
{
116+
"type": "object"
117+
},
118+
{
119+
"type": "string",
120+
"contentEncoding": "base64"
121+
}
122+
]
123+
},
124+
"customDataContentType": {
125+
"type": "string"
126+
}
127+
},
128+
"additionalProperties": false,
129+
"type": "object",
130+
"required": [
131+
"context",
132+
"subject"
133+
]
134+
}

‎schemas/approvalcreated.json‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://cdevents.dev/0.6.0-draft/schema/approval-created-event",
4+
"x-cdevents-semantics": {
5+
"subject": "cdevents/_defs/approval"
6+
},
7+
"properties": {
8+
"context": {
9+
"properties": {
10+
"specversion": {
11+
"type": "string",
12+
"minLength": 1
13+
},
14+
"id": {
15+
"type": "string",
16+
"minLength": 1
17+
},
18+
"source": {
19+
"type": "string",
20+
"minLength": 1,
21+
"format": "uri-reference"
22+
},
23+
"type": {
24+
"type": "string",
25+
"enum": [
26+
"dev.cdevents.approval.created.0.1.0"
27+
],
28+
"default": "dev.cdevents.approval.created.0.1.0"
29+
},
30+
"timestamp": {
31+
"type": "string",
32+
"format": "date-time"
33+
},
34+
"schemaUri": {
35+
"type": "string",
36+
"minLength": 1,
37+
"format": "uri"
38+
},
39+
"chainId": {
40+
"type": "string",
41+
"minLength": 1
42+
},
43+
"links": {
44+
"$ref": "links/embeddedlinksarray"
45+
},
46+
},
47+
"additionalProperties": false,
48+
"type": "object",
49+
"required": [
50+
"specversion",
51+
"id",
52+
"source",
53+
"type",
54+
"timestamp"
55+
]
56+
},
57+
"subject": {
58+
"properties": {
59+
"id": {
60+
"type": "string",
61+
"minLength": 1
62+
},
63+
"source": {
64+
"type": "string",
65+
"minLength": 1,
66+
"format": "uri-reference"
67+
},
68+
"content": {
69+
"properties": {
70+
"approvalDetailsUrl": {
71+
"type": "string",
72+
"minLength": 1,
73+
"$comment": "Reference URL to the approval request in the originating system. Consumers with appropriate access can retrieve the full approval context, history, and decisions from this URL. This provides the canonical location of the approval record."
74+
},
75+
"resourceTargetUrl": {
76+
"type": "string",
77+
"minLength": 1,
78+
"$comment": "Reference URL to the resource whose progression is gated by this approval. The approval does not describe the resource, but the URL allows consumers to retrieve resource information directly from the system that owns it."
79+
},
80+
"requestor": {
81+
"type": "string",
82+
"format": "urn",
83+
"minLength": 1,
84+
"$comment": "URN identifying the entity that initiated the approval request. May be a human identity, a service account, or an automated system. Format must be a valid URN."
85+
}
86+
},
87+
"additionalProperties": false,
88+
"type": "object",
89+
"required": [
90+
"approvalDetailsUrl",
91+
"resourceTargetUrl",
92+
"requestor"
93+
]
94+
}
95+
},
96+
"additionalProperties": false,
97+
"type": "object",
98+
"required": [
99+
"id",
100+
"content"
101+
]
102+
},
103+
"customData": {
104+
"oneOf": [
105+
{
106+
"type": "object"
107+
},
108+
{
109+
"type": "string",
110+
"contentEncoding": "base64"
111+
}
112+
]
113+
},
114+
"customDataContentType": {
115+
"type": "string"
116+
}
117+
},
118+
"additionalProperties": false,
119+
"type": "object",
120+
"required": [
121+
"context",
122+
"subject"
123+
]
124+
}

0 commit comments

Comments
 (0)