docs: improve docs on header.project-si-source (#133)

These changes are being made after finding examples in the wild
that provide values like `https://github.com/ossf/security-insights-spec/blob/main/.github/security-insights.yml`
that are unable to be easily consumed by the code in `ossf/si-tooling`

This change relates to the changes in:
- [fix: specific project-si-source URL that provides raw access to the parent SI file](ossf/si-tooling#27)
- ["example" test demonstrating the issue](https://github.com/ossf/si-tooling/pull/26/files#diff-2c7a40d9b54300b2087ef12ec04ebd8ae5be37e4eb341e57cea2e7f9f1bfe5caR8)

Signed-off-by: Travis Truman <trumant@gmail.com>

Author: trumant

README.md

@@ -14,7 +14,7 @@ We hope your project appreciates the value the specification provides and makes
 
 Projects adopting the specification in a single project repository should be able to get started and produce a useful `security-insights.yml` in about 30 minutes by consulting the [`template-minimum.yml`](template-minimum.yml).
 
-If your project has multiple repositories, you can apply the specification across all of them quickly by reusing the `project` definition from a single source. Consult [`template-multi-repository-project.yml`](template-multi-repository-project.yml) and [`template-multi-repository-project-reuse.yml`](template-multi-repository-project-reuse.yml) that are relevant to this use case.
+If your project has multiple repositories, you can define a detailed and centralized insights file in one repository and then reuse the `project` definition from that across other files. The consuming insights files must provide a URL in `header.project-si-source` that points to the parent insights file. The URL provided must respond to an unauthenticated GET request and return a valid security insights file using a content-type of "text/plain" or "application/yaml". See [`template-multi-repository-project.yml`](template-multi-repository-project.yml) and [`template-multi-repository-project-reuse.yml`](template-multi-repository-project-reuse.yml) that demonstrate how this use case can be implemented.
 
 Projects should include a `security-insights.yml` file in the root of their repository, or in the appropriate source forge directory such as `.github/` or `.gitlab/`.
 
@@ -64,4 +64,3 @@ Examples are also available to provide further context to the specification deta
 - `template-multi-repository-project-reuse.yml`: Contains a template for a secondary repository of a multi-repository project
 
 Discussion and feedback should take place in [GitHub Issues](https://github.com/ossf/security-insights-spec/issues). We ask that you follow the [Security Insights Enhancement Proposal](./docs/GOVERNANCE.md#security-insights-enhancement-proposals) process to explore potential changes to the specification.
-

schema.cue

@@ -104,7 +104,7 @@ import (
   // The date when the document or data was last updated.
   "last-updated":       #Date @go(LastUpdated)
 
-  // The version of the schema being used.
+  // 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.
@@ -113,7 +113,7 @@ import (
   // Additional information about the schema.
   comment?:             string
 
-  // A URL to the security insights file that contains project information for this file to inherit.
+  // A URL to the security insights file that contains project information for this file to inherit. The URL provided here should respond to an unauthenticated GET request and return a valid security insights file using a content-type of "text/plain" or "application/yaml". This is useful for projects that are part of a larger organization or ecosystem, where much of the security insights data is shared across multiple projects.
   "project-si-source"?: #URL @go(ProjectSISource)
 }
 

specification/header.md

@@ -42,7 +42,7 @@ The `header` object captures high-level metadata about the schema.
 ## `header.project-si-source` (optional)
 
 - **Type**: [URL]
-- **Description**: A URL to the security insights file that contains project information for this file to inherit.
+- **Description**: A URL to the security insights file that contains project information for this file to inherit. The URL provided here should respond to an unauthenticated GET request and return a valid security insights file using a content-type of "text/plain" or "application/yaml". This is useful for projects that are part of a larger organization or ecosystem, where much of the security insights data is shared across multiple projects.
 
 ---
 

template-multi-repository-project-reuse.yml

@@ -5,7 +5,7 @@ header:
   last-updated: '2025-03-01'
   last-reviewed: '2025-04-01'
   url: https://example.com/kubernetes/kubernetes
-  project-si-source: https://vcs.example.com/foobar/foo/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