docs: updated examples and explanation for header.url

Signed-off-by: Eddie Knight <knight@linux.com>

Author: eddie-knight

docs/schema.md

@@ -89,7 +89,7 @@ The version of the Security Insights schema being used.
 
 ### `header.url`
 
-The primary reference URL for this schema’s origin or repository.
+The original URL for the current Security Insights file. This should point to the canonical location where the file is hosted (e.g., a raw file URL in a version control system). This helps preserve context when the file is extracted from its source. This may also be referenced to help readers find the latest version of the security insights file, in the event that they are accessing it from an outdated source, such as a past release artifact. This is not to be confused with the URL for the project. Project URLs should be specified in `project.repositories` instead.
 
 - **Type**: [URL]
 

examples/example-full.yml

@@ -2,7 +2,7 @@ header:
   schema-version: 2.0.0
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
-  url: https://example.com/foo/bar
+  url: https://example.com/foo/bar/raw/branch/main/security-insights.yml
   comment: |
     This file contains all possible information for both project and repository,
     though it is not required to include all of this information every time.
@@ -33,11 +33,11 @@ project:
     signature-verification: https://example.com/signature-verification
   repositories:
     - name: Foo
-      url: https://vcs.example.com/foobar/foo
+      url: https://example.com/foobar/foo
       comment: |
         Foo is the core repo for FooBar.
     - name: Bar
-      url: https://vcs.example.com/foobar/bar
+      url: https://example.com/foobar/bar
       comment: |
         Bar is a subproject repo.
   vulnerability-reporting:

examples/example-minimum.yml

@@ -2,7 +2,7 @@ header:
   schema-version: 2.0.0
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
-  url: https://example.com/kubernetes/kubernetes
+  url: https://example.com/foo/bar/raw/branch/main/security-insights.yml
   comment: |
     This file contains the minimum information for both project and repository.
     It not required to include both a project and repository section if the project
@@ -18,15 +18,15 @@ project:
       primary: true
   repositories:
     - name: Foo
-      url: https://vcs.example.com/foobar/foo
+      url: https://example.com/foobar/foo
       comment: |
         Foo is the core repo for FooBar.
   vulnerability-reporting:
     reports-accepted: true
     bug-bounty-available: true
 
 repository:
-  url: https://vcs.example.com/foobar/foo
+  url: https://example.com/foobar/foo
   status: active
   accepts-change-request: true
   accepts-automated-change-request: true

examples/example-multi-repository-project-reuse.yml

@@ -1,14 +1,14 @@
 # Repository template for a multi-repository project
-# This file would be stored in the https://vcs.example.com/foobar/bar repository
+# This file would be stored in the https://example.com/foobar/bar repository
 header:
   schema-version: 2.0.0
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
-  url: https://example.com/kubernetes/kubernetes
+  url: https://example.com/foo/bar/raw/branch/main/security-insights.yml
   project-si-source: https://raw.githubusercontent.com/example/repo/refs/heads/main/security-insights.yml
 
 repository:
-  url: https://vcs.example.com/foobar/bar
+  url: https://example.com/foobar/bar
   status: active
   accepts-change-request: true
   accepts-automated-change-request: true

examples/example-multi-repository-project.yml

@@ -1,11 +1,11 @@
 # Project and repository template for a multi-repository project
-# This file would be stored in the https://vcs.example.com/foobar/foo repository
-# and addressable via https://vcs.example.com/foobar/foo/security-insights.yml
+# This file would be stored in the https://example.com/foobar/foo repository
+# and addressable via https://example.com/foobar/foo/security-insights.yml
 header:
   schema-version: 2.0.0
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
-  url: https://example.com/kubernetes/kubernetes
+  url: https://example.com/foo/bar/raw/branch/main/security-insights.yml
   comment: |
     This file contains the minimum information for both project and repository.
     It not required to include both a project and repository section if the project
@@ -21,19 +21,19 @@ project:
       primary: true
   repositories:
     - name: Foo
-      url: https://vcs.example.com/foobar/foo
+      url: https://example.com/foobar/foo
       comment: |
         Foo is the core repo for FooBar.
     - name: Bar
-      url: https://vcs.example.com/foobar/bar
+      url: https://example.com/foobar/bar
       comment: |
         Bar is also part of the FooBar project.
   vulnerability-reporting:
     reports-accepted: true
     bug-bounty-available: true
 
 repository:
-  url: https://vcs.example.com/foobar/foo
+  url: https://example.com/foobar/foo
   status: active
   accepts-change-request: true
   accepts-automated-change-request: true

spec/schema.cue

@@ -125,7 +125,7 @@ import (
 	// The version of the Security Insights schema being used.
 	"schema-version": #SchemaVersion @go(SchemaVersion)
 
-	// The primary reference URL for this schema’s origin or repository.
+	// The original URL for the current Security Insights file. This should point to the canonical location where the file is hosted (e.g., a raw file URL in a version control system). This helps preserve context when the file is extracted from its source. This may also be referenced to help readers find the latest version of the security insights file, in the event that they are accessing it from an outdated source, such as a past release artifact. This is not to be confused with the URL for the project. Project URLs should be specified in `project.repositories` instead.
 	url: #URL @go(URL)
 
 	// Additional information about the schema.

spec/schema.md

@@ -82,7 +82,7 @@ The version of the Security Insights schema being used.
 
 ### `header.url`
 
-The primary reference URL for this schema’s origin or repository.
+The original URL for the current Security Insights file. This should point to the canonical location where the file is hosted (e.g., a raw file URL in a version control system). This helps preserve context when the file is extracted from its source. This may also be referenced to help readers find the latest version of the security insights file, in the event that they are accessing it from an outdated source, such as a past release artifact. This is not to be confused with the URL for the project. Project URLs should be specified in `project.repositories` instead.
 
 - **Type**: [URL]