Skip to content

Commit 4eab4a0

Browse files
xibzxibz
committed
lint fixes and adding registry
Signed-off-by: xibz <bjp@apple.com>
1 parent ff03821 commit 4eab4a0

7 files changed

Lines changed: 78 additions & 25 deletions

File tree

‎.spellcheck-en-custom.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ rolledback
5656
runtime
5757
sbom
5858
schemaUri
59+
schemas
5960
schemauri
6061
specversion
6162
src

‎PROVIDERS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
The canonical registry of known `provider` values is [`schemas/registry/providers.json`](schemas/registry/providers.json). SDKs MUST use this list as the default for provider validation. See the [Provider Validation](links.md#provider-validation) section in `links.md` for the full SDK validation requirements.
44

5-
To register a provider, open a pull request adding an entry to the enum in [`schemas/registry/providers.json`](schemas/registry/providers.json). Provider identifiers MUST be lowercase, start with a letter, and contain only alphanumeric characters and hyphens. Once merged, the value is considered stable and MUST NOT be renamed.
5+
To register a provider, open a pull request adding an entry to the `enum` in [`schemas/registry/providers.json`](schemas/registry/providers.json). Provider identifiers MUST be lowercase, start with a letter, and contain only alphanumeric characters and hyphens. Once merged, the value is considered stable and MUST NOT be renamed.

‎links.md‎

Lines changed: 37 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -680,7 +680,9 @@ covering fan-out scenarios where one action triggers work across several systems
680680

681681
### CDEvents Domain IDs
682682

683-
`domainId` values are URNs following this format:
683+
`domainId` values are URIs following this format:
684+
685+
The `cdevents:` scheme prefix was chosen deliberately. The original design used a URN (`urn:`), but URN namespaces require formal registration — for example, `urn:github:...` would need to be registered by GitHub, and `urn:jira:...` by Atlassian. Using `urn:cdevents:...` for everything would raise the question of why a URN is needed at all if CDEvents is acting as the sole authority. A URI with a `cdevents:` scheme avoids these registry obligations while remaining a valid, parseable identifier under RFC 3986.
684686

685687
```
686688
cdevents:v0:<provider>:<provider-id>:<namespace>:<groups>:<type>:<resource id>
@@ -694,7 +696,7 @@ Segment values MUST reflect the exact canonical form as the value appears in the
694696

695697
| Segment | Required | Description |
696698
|---------------|----------|----------------------------------------------------------------------------------------------------------------|
697-
| `version` | yes | The version of the `domainId` URN format (currently `v0`). This allows the format to evolve without breaking existing consumers. |
699+
| `version` | yes | The version of the `domainId` URI format (currently `v0`). This allows the format to evolve without breaking existing consumers. |
698700
| `provider` | no | A governed identifier for the tool or system type that owns the resource. When present, MUST match a known provider defined in [PROVIDERS.md](PROVIDERS.md). Free-form values are not permitted — without a governed list, the same tool would be referenced as `gh`, `github`, `GitHub`, etc., making cross-system queries unreliable. |
699701
| `provider-id` | no | Identifies who owns and where a specific instance of the provider is running. This is entirely company or org-defined — CDEvents does not govern, assign, or interpret this value. It exists solely to distinguish between two instances of the same tool owned or operated by different teams or organizations (e.g. org A's internal GitHub Enterprise vs org B's). Producers and consumers within an organization MUST agree on the value out of band. MUST be URL-encoded when present. |
700702
| `namespace` | no | The top-level organizational unit within the provider's data model (e.g., a GitHub org, a Jira workspace). Producer-defined; not governed by CDEvents. MUST be URL-encoded when present. |
@@ -725,18 +727,39 @@ The `type` segment is a governed field. Producers MUST use one of the following
725727
values. This ensures interoperability — consumers can match and query by `type`
726728
without handling variations like `pull_request`, `PR`, or `pullrequest`.
727729

728-
| Type | Description | `resource id` example |
729-
|---------------|------------------------------------------------------------------------------------|-------------------------------|
730-
| `pr` | A pull or merge request | `42` (PR number) |
731-
| `commit` | A source code commit | `abc123def456` (commit SHA) |
732-
| `issue` | An issue or ticket in a tracking system | `1234` (issue number) |
733-
| `branch` | A source code branch | `main`, `feature/my-branch` |
734-
| `tag` | A source code tag or release | `v1.2.3` |
735-
| `definition` | A named, reusable pipeline or workflow template | `my-pipeline` |
736-
| `execution` | A single run of a build, pipeline, workflow, or deployment | `789` (run number) |
737-
| `artifact` | A build artifact (binary, container image, package, etc.). The resource id SHOULD be a [PURL](https://github.com/package-url/purl-spec), URL-encoded. | `pkg%3Adocker%2Fmyapp%401.0.0` |
738-
| `environment` | A target deployment environment | `production`, `staging` |
739-
| `alert` | A monitoring or observability alert | `98765` (alert ID) |
730+
Most types are concrete and singular — `pr`, `commit`, `issue`, `branch`, `tag`,
731+
`artifact`, `environment`, `alert`, and `execution` each represent a single,
732+
unambiguous concept. If subtypes are added to these in the future (e.g.
733+
`execution.stage`), the bare type retains its original meaning and existing URNs
734+
remain valid — there is no migration cost.
735+
736+
`definition` is treated differently. A bare `definition` could mean "a workflow
737+
definition" today, but if `definition.policy` or `definition.infrastructure` were
738+
added later, bare `definition` would become underspecified — consumers could no
739+
longer tell which kind of definition was intended without provider knowledge. To
740+
avoid this migration problem, `definition` is an abstract parent type that MUST
741+
NOT be used directly. Producers MUST always use a concrete subtype such as
742+
`definition.workflow`. New subtypes SHOULD follow the `definition.<kind>` naming
743+
convention and be proposed for addition to this list.
744+
745+
`execution` specifically refers to a top-level run — a pipeline execution, workflow
746+
run, or build. Sub-level concepts such as stages, jobs, and steps are either
747+
covered by CDEvents events via `contextId` (if the system emits CDEvents) or are
748+
out of scope for `domainId`.
749+
750+
| Type | Description | `resource id` example |
751+
|------------------------|----------------------------------------------------------------------------------------------------------------|-------------------------------|
752+
| `pr` | A pull or merge request | `42` (PR number) |
753+
| `commit` | A source code commit | `abc123def456` (commit SHA) |
754+
| `issue` | An issue or ticket in a tracking system | `1234` (issue number) |
755+
| `branch` | A source code branch | `main`, `feature/my-branch` |
756+
| `tag` | A source code tag or release | `v1.2.3` |
757+
| `definition` | Abstract parent. MUST NOT be used directly — use a concrete subtype. | — |
758+
| `definition.workflow` | An automation or pipeline definition — any template that describes a sequence of steps to be executed (e.g. a GitHub Actions workflow file, a CircleCI pipeline config, a Jenkinsfile). | `.github%2Fworkflows%2Fci.yml` |
759+
| `execution` | A top-level run of a pipeline, workflow, or build. Always refers to the top-level execution — stages, jobs, and steps are out of scope. | `789` (run number) |
760+
| `artifact` | A build artifact (binary, container image, package, etc.). The resource id SHOULD be a [PURL](https://github.com/package-url/purl-spec), URL-encoded. | `pkg%3Adocker%2Fmyapp%401.0.0` |
761+
| `environment` | A target deployment environment | `production`, `staging` |
762+
| `alert` | A monitoring or observability alert | `98765` (alert ID) |
740763

741764
If a resource does not fit any of the above types, it SHOULD be proposed for
742765
addition to this list before using a custom value.

‎schemas/links/embeddedlinkrelation.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"minLength": 1
2222
},
2323
"domainId": {
24-
"$ref": "domainid.json"
24+
"$ref": "https://cdevents.dev/0.6.0-draft/schema/links/domainid"
2525
}
2626
},
2727
"anyOf": [

‎schemas/links/linkrelation.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
"minLength": 1
3131
},
3232
"domainId": {
33-
"$ref": "domainid.json"
33+
"$ref": "https://cdevents.dev/0.6.0-draft/schema/links/domainid"
3434
}
3535
},
3636
"anyOf": [
@@ -47,7 +47,7 @@
4747
"minLength": 1
4848
},
4949
"domainId": {
50-
"$ref": "domainid.json"
50+
"$ref": "https://cdevents.dev/0.6.0-draft/schema/links/domainid"
5151
}
5252
},
5353
"anyOf": [

‎schemas/registry/providers.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://cdevents.dev/0.6.0-draft/schema/links/providers",
4+
"description": "Registry of known CDEvents domainId provider identifiers. Known providers are listed below. To register a new provider, submit a pull request adding an entry to the enum and the PROVIDERS.md table.",
5+
"type": "string",
6+
"pattern": "^[a-z][a-z0-9-]*$",
7+
"enum": [
8+
"artifactory",
9+
"argo",
10+
"bitbucket",
11+
"circleci",
12+
"datadog",
13+
"docker",
14+
"gitea",
15+
"github",
16+
"gitlab",
17+
"grafana",
18+
"jenkins",
19+
"jira",
20+
"linear",
21+
"nexus",
22+
"pagerduty",
23+
"tekton"
24+
]
25+
}

‎tools/validate.js‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ const EXAMPLES_FOLDER = join(ROOT, "conformance");
3030
const SCHEMAS_FOLDER = join(ROOT, "schemas");
3131
const EMBEDDED_LINKS_SCHEMAS_PATTERN = join(
3232
ROOT,
33-
"schemas/links/embedded*.json",
33+
"schemas/links/*.json",
3434
);
3535

3636
// Helper function to load JSON file
@@ -54,7 +54,7 @@ function createAjv() {
5454
return ajv;
5555
}
5656

57-
// Load embedded links schemas
57+
// Load links schemas for use as references
5858
function loadEmbeddedLinksSchemas() {
5959
const schemas = [];
6060
const files = globSync(EMBEDDED_LINKS_SCHEMAS_PATTERN);
@@ -78,9 +78,8 @@ function testSchemas() {
7878
for (const schemaFile of eventSchemaFiles) {
7979
try {
8080
const ajv = createAjv();
81-
// Add embedded links schemas as references
82-
for (const embeddedSchema of embeddedLinksSchemas) {
83-
ajv.addSchema(embeddedSchema);
81+
for (const schema of embeddedLinksSchemas) {
82+
ajv.addSchema(schema);
8483
}
8584
const schema = loadJSON(schemaFile);
8685
ajv.compile(schema);
@@ -97,6 +96,11 @@ function testSchemas() {
9796
for (const schemaFile of linkSchemaFiles) {
9897
try {
9998
const ajv = createAjv();
99+
for (const refSchema of embeddedLinksSchemas) {
100+
if (!refSchema.$id?.includes("/links/link")) {
101+
ajv.addSchema(refSchema);
102+
}
103+
}
100104
const schema = loadJSON(schemaFile);
101105
ajv.compile(schema);
102106
} catch (error) {
@@ -109,8 +113,8 @@ function testSchemas() {
109113
numSchemas += 1;
110114
try {
111115
const ajv = createAjv();
112-
for (const embeddedSchema of embeddedLinksSchemas) {
113-
ajv.addSchema(embeddedSchema);
116+
for (const schema of embeddedLinksSchemas) {
117+
ajv.addSchema(schema);
114118
}
115119
const customSchema = loadJSON(join(ROOT, "custom/schema.json"));
116120
ajv.compile(customSchema);

0 commit comments

Comments
 (0)