feat(schema): Add approval events

[xibz]

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

[sol-duara]

LGTM

[davidB]

No comments, on the purpose, only on the format (I comment once each "case", not each time the case is present).
Before merging, do not forget to add the json samples as part of the conformance.

[davidB]

IMHO, the "$comment" (json draft-07) should be replaced by "description".
https://json-schema.org/understanding-json-schema/reference/metadata

they ($comments) are useful for leaving notes to future editors of a JSON schema, but should not be used to communicate to users of the schema.

from https://json-schema.org/understanding-json-schema/reference/comments

[davidB]

Every xxxUrl should have format uri or uri-reference

            "uri": {
              "type": "string",
              "minLength": 1,
              "format": "uri-reference"
            },

For consistency, I'm also in favor to rename the suffix Uri (IIRC, I open a ticket to rename the renaiming viewUrl & ticketURI.

[davidB]

FYI, we didn't agree on removing subject.source (as I asked).
So it is missing

[afrittoli]

#252

[afrittoli]

If we agree to make that change in v0.6 we could do that first.

[xibz]

Actually, I forgot to include it for only closed.

I think we need consensus on this.

[davidB]

I didn't find urn format in the json-schema.

Just:

Note also that the "uuid" format is for plain UUIDs, not UUIDs in URNs. An example is "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". For UUIDs as URNs, use the "uri" format, with a "pattern" regular expression of "^urn:uuid:" to indicate the URI scheme and URN namespace.

https://json-schema.org/draft/2020-12/json-schema-validation#name-resource-identifiers

As it's unusual, SDK and implementation, may need some custom adaption.

[xibz]

Looks like urn is covered by uri with pattern matching in json schema

[davidB]

change enum'values to lowercase, like in other schemas.

[xibz]

We should update the linter to enforce lower case enum values, then. Is it lower case, camel case, snake case or what?