docs: Updated context and examples for header.url

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

Author: eddie-knight

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.

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

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

@@ -4,11 +4,11 @@ header:
   schema-version: 2.0.0
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
-  url: https://example.com/kubernetes/kubernetes
-  project-si-source: https://raw.githubusercontent.com/example/repo/refs/heads/main/security-insights.yml
+  url: https://example.com/foo/bar/raw/branch/main/security-insights.yml
+  project-si-source: https://example.com/foo/baz/refs/heads/main/security-insights.yml
 
 repository:
-  url: https://vcs.example.com/foobar/bar
+  url: https://vcs.example.com/foo/bar
   status: active
   accepts-change-request: true
   accepts-automated-change-request: true

examples/example-multi-repository-project.yml

@@ -5,7 +5,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/foobar/foo/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

spec/header.md

@@ -28,7 +28,11 @@ The `header` object captures high-level metadata about the schema.
 ## `header.url`
 
 - **Type**: [URL]
-- **Description**: The primary reference URL for this schema’s origin or repository.
+- **Description**: The original URL for this 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.
 
 ---
 

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.
 	url: #URL @go(URL)
 
 	// Additional information about the schema.