Offer notification proto schema as download

.github/workflows/update-proto-docs.yml

@@ -46,7 +46,10 @@ jobs:
     - name: Create Pull Request
       uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
       with:
-        add-paths: "docs/reference/schemas/*.md"
+        add-paths: |
+          docs/reference/notifications/schema.md
+          docs/reference/notifications/notification.proto
+          docs/reference/policies/schema.md
         branch: update-proto-docs
         body: "Updates Protobuf documentation."
         commit-message: Update proto docs

.markdownlint-cli2.yaml

@@ -34,7 +34,10 @@ globs:
 ignores:
 - "docs/includes/**"
 - "docs/reference/configuration/properties.md"
-- "docs/reference/schemas/**"
+- "docs/reference/notifications/schema.md"
+- "docs/reference/notifications/schema.md.tmpl"
+- "docs/reference/policies/schema.md"
+- "docs/reference/policies/schema.md.tmpl"
 - "existing-docs/**"
 - "site/**"
 - "node_modules/**"

.vale.ini

@@ -30,7 +30,9 @@ BasedOnStyles = Vale, Google, write-good, DependencyTrack
 # Ignore generated reference files.
 [docs/reference/configuration/properties.md]
 BasedOnStyles =
-[docs/reference/schemas/*.md]
+[docs/reference/notifications/schema.md]
+BasedOnStyles =
+[docs/reference/policies/schema.md]
 BasedOnStyles =
 
 # Tutorials use "we" voice and "will" to set expectations per Diataxis convention.

Makefile

@@ -97,15 +97,17 @@ generate-config-docs:
 
 generate-proto-docs:
 	@docker run -i --rm -u "$$(id -u):$$(id -g)" \
-	  -v "$$(pwd)/docs/reference/schemas:/out" \
+	  -v "$$(pwd)/docs/reference/notifications:/out" \
 	  -v "$$(pwd)/$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1:/protos" \
 	  "$(PROTOC_GEN_DOC_IMAGE)" \
-	  --doc_opt=/out/notification.md.tmpl,notification.md
+	  --doc_opt=/out/schema.md.tmpl,schema.md
+	@cp "$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1/notification.proto" \
+	  docs/reference/notifications/notification.proto
 	@docker run -i --rm -u "$$(id -u):$$(id -g)" \
-	  -v "$$(pwd)/docs/reference/schemas:/out" \
+	  -v "$$(pwd)/docs/reference/policies:/out" \
 	  -v "$$(pwd)/$(APISERVER_DIR)/proto/src/main/proto/org/dependencytrack/policy/v1:/protos" \
 	  "$(PROTOC_GEN_DOC_IMAGE)" \
-	  --doc_opt=/out/policy.md.tmpl,policy.md
+	  --doc_opt=/out/schema.md.tmpl,schema.md
 .PHONY: generate-proto-docs
 
 serve:

docs/concepts/architecture/design/notifications.md

@@ -60,7 +60,7 @@ erDiagram
 
 The `ID` column uses [UUIDv7], which combines global uniqueness with sortability.
 The `PAYLOAD` column contains the serialized notification in [Protobuf] format.
-The [notification schema reference](../../../reference/schemas/notification.md) describes the schema.
+The [notification schema reference](../../../reference/notifications/schema.md) describes the schema.
 
 ### Preliminary filtering
 

docs/concepts/changes-in-v5.md

@@ -150,7 +150,7 @@ remediation steps, lives in the
 [upgrade guides](../guides/upgrading/index.md). Headline items:
 
 * **Notification schema.** Subjects now use [Protobuf][Protobuf] (see the
-  [notification schema reference](../reference/schemas/notification.md)).
+  [notification schema reference](../reference/notifications/schema.md)).
   List fields gain a `List` suffix, enum-like values gain a type prefix
   (`INFORMATIONAL` → `LEVEL_INFORMATIONAL`, `SYSTEM` → `SCOPE_SYSTEM`,
   `NEW_VULNERABILITY` → `GROUP_NEW_VULNERABILITY`), and timestamps

docs/concepts/notifications.md

@@ -26,7 +26,7 @@ email to Webhook. Refer to [Publishers](../reference/notifications/publishers.md
 ## Templates
 
 Templates define how the platform's internal representation of notifications
-(see [Notification schema](../reference/schemas/notification.md)) maps
+(see [Notification schema](../reference/notifications/schema.md)) maps
 to the format that notification recipients expect.
 
 Each [publisher](#publishers) ships with a default template, and administrators

docs/reference/.pages

@@ -17,4 +17,3 @@ nav:
     - Badges: badges.md
     - File formats: file-formats.md
     - Community integrations: community-integrations.md
-  - Schemas: schemas

docs/reference/notifications/.pages

@@ -3,3 +3,4 @@ nav:
   - Publishers: publishers.md
   - Templating: templating.md
   - Filter expressions: filter-expressions.md
+  - Proto schema: schema.md

docs/reference/notifications/filter-expressions.md

@@ -30,9 +30,9 @@ The expression evaluation context contains the following variables:
 
 | Variable    | Type                                                         | Description                                                                            |
 |:------------|:-------------------------------------------------------------|:---------------------------------------------------------------------------------------|
-| `level`     | [`Level`](../../reference/schemas/notification.md#level)     | The notification level, as an integer enum value. Use named constants (see below).      |
-| `scope`     | [`Scope`](../../reference/schemas/notification.md#scope)     | The notification scope, as an integer enum value. Use named constants (see below).      |
-| `group`     | [`Group`](../../reference/schemas/notification.md#group)     | The notification group, as an integer enum value. Use named constants (see below).      |
+| `level`     | [`Level`](schema.md#level)     | The notification level, as an integer enum value. Use named constants (see below).      |
+| `scope`     | [`Scope`](schema.md#scope)     | The notification scope, as an integer enum value. Use named constants (see below).      |
+| `group`     | [`Group`](schema.md#group)     | The notification group, as an integer enum value. Use named constants (see below).      |
 | `title`     | `string`                                                     | The notification title.                                                                |
 | `content`   | `string`                                                     | The notification content.                                                              |
 | `timestamp` | [`google.protobuf.Timestamp`][protobuf-ts-docs]              | The notification creation time.                                                        |
@@ -41,7 +41,7 @@ The expression evaluation context contains the following variables:
 ### Enum constants
 
 The `level`, `scope`, and `group` variables hold integer values. To compare them in a readable way,
-use the named constants from the [notification schema](../../reference/schemas/notification.md#enums):
+use the named constants from the [notification schema](schema.md#enums):
 
 ```js
 level == Level.LEVEL_INFORMATIONAL
@@ -59,7 +59,7 @@ scope == Scope.SCOPE_PORTFOLIO
 
 The `subject` variable holds the notification's subject. Its type depends on the notification
 group; see [Subjects](groups.md#subjects) in the notification groups reference for the
-group-to-subject mapping, and the [notification schema reference](../../reference/schemas/notification.md)
+group-to-subject mapping, and the [notification schema reference](schema.md)
 for each subject's fields.
 
 ### Available functions

docs/reference/notifications/groups.md

@@ -7,7 +7,7 @@ trigger type: `Event` for ad-hoc notifications that the system emits in response
 to a system event, or `Schedule` for notifications that fire periodically on a
 cron schedule.
 
-The [notification schema reference](../schemas/notification.md) describes the
+The [notification schema reference](schema.md) describes the
 subject schema for each group.
 
 ## System scope
@@ -176,19 +176,19 @@ Summarizes new policy violations found in a set of projects.
 ## Subjects
 
 The typed subject of a notification depends on its group. The
-[notification schema reference](../schemas/notification.md) describes
+[notification schema reference](schema.md) describes
 each subject schema.
 
 | Group                                                   | Subject type                                                                                                                                            |
 |:--------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `BOM_CONSUMED`, `BOM_PROCESSED`                         | [BomConsumedOrProcessedSubject](../schemas/notification.md#bomconsumedorprocessedsubject)                                                               |
-| `BOM_PROCESSING_FAILED`                                 | [BomProcessingFailedSubject](../schemas/notification.md#bomprocessingfailedsubject)                                                                     |
-| `BOM_VALIDATION_FAILED`                                 | [BomValidationFailedSubject](../schemas/notification.md#bomvalidationfailedsubject)                                                                     |
-| `NEW_VULNERABILITY`                                     | [NewVulnerabilitySubject](../schemas/notification.md#newvulnerabilitysubject)                                                                           |
-| `NEW_VULNERABLE_DEPENDENCY`                             | [NewVulnerableDependencySubject](../schemas/notification.md#newvulnerabledependencysubject)                                                             |
-| `POLICY_VIOLATION`                                      | [PolicyViolationSubject](../schemas/notification.md#policyviolationsubject)                                                                             |
-| `PROJECT_AUDIT_CHANGE`                                  | [VulnerabilityAnalysisDecisionChangeSubject](../schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../schemas/notification.md#policyviolationanalysisdecisionchangesubject) |
-| `VEX_CONSUMED`, `VEX_PROCESSED`                         | [VexConsumedOrProcessedSubject](../schemas/notification.md#vexconsumedorprocessedsubject)                                                               |
-| `USER_CREATED`, `USER_DELETED`                          | [UserSubject](../schemas/notification.md#usersubject)                                                                                                   |
-| `NEW_VULNERABILITIES_SUMMARY`                           | [NewVulnerabilitiesSummarySubject](../schemas/notification.md#newvulnerabilitiessummarysubject)                                                         |
-| `NEW_POLICY_VIOLATIONS_SUMMARY`                         | [NewPolicyViolationsSummarySubject](../schemas/notification.md#newpolicyviolationssummarysubject)                                                       |
+| `BOM_CONSUMED`, `BOM_PROCESSED`                         | [BomConsumedOrProcessedSubject](schema.md#bomconsumedorprocessedsubject)                                                               |
+| `BOM_PROCESSING_FAILED`                                 | [BomProcessingFailedSubject](schema.md#bomprocessingfailedsubject)                                                                     |
+| `BOM_VALIDATION_FAILED`                                 | [BomValidationFailedSubject](schema.md#bomvalidationfailedsubject)                                                                     |
+| `NEW_VULNERABILITY`                                     | [NewVulnerabilitySubject](schema.md#newvulnerabilitysubject)                                                                           |
+| `NEW_VULNERABLE_DEPENDENCY`                             | [NewVulnerableDependencySubject](schema.md#newvulnerabledependencysubject)                                                             |
+| `POLICY_VIOLATION`                                      | [PolicyViolationSubject](schema.md#policyviolationsubject)                                                                             |
+| `PROJECT_AUDIT_CHANGE`                                  | [VulnerabilityAnalysisDecisionChangeSubject](schema.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](schema.md#policyviolationanalysisdecisionchangesubject) |
+| `VEX_CONSUMED`, `VEX_PROCESSED`                         | [VexConsumedOrProcessedSubject](schema.md#vexconsumedorprocessedsubject)                                                               |
+| `USER_CREATED`, `USER_DELETED`                          | [UserSubject](schema.md#usersubject)                                                                                                   |
+| `NEW_VULNERABILITIES_SUMMARY`                           | [NewVulnerabilitiesSummarySubject](schema.md#newvulnerabilitiessummarysubject)                                                         |
+| `NEW_POLICY_VIOLATIONS_SUMMARY`                         | [NewPolicyViolationsSummarySubject](schema.md#newpolicyviolationssummarysubject)                                                       |