fix: Improved clarity around required values (#98)

* fix: Improved clarity around required values Signed-off-by: Eddie Knight <[email protected]>
ossf · Dec 29, 2024 · 85757fe · 85757fe
1 parent 699e801
commit 85757fe
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 41 deletions.
diff --git a/schema.cue b/schema.cue
@@ -52,10 +52,10 @@ header: {
 }
 
 project?: {
-  name:      string
-  homepage:  #URL
-  funding:   #URL
-  roadmap:   #URL
+  name:        string
+  homepage?:   #URL
+  roadmap?:    #URL
+  funding?:    #URL
 
   administrators: [...#Contact]
 
@@ -66,8 +66,8 @@ project?: {
   }]
 
   "vulnerability-reporting": {
-    "reports-accepted":       bool
-    "bug-bounty-available":   bool
+    "reports-accepted":        bool
+    "bug-bounty-available":    bool
     "bug-bounty-program"?:     #URL
     contact?:                  #Contact
     comment?:                  string
@@ -79,22 +79,22 @@ project?: {
   }
 
   documentation?: {
-    "detailed-guide"?:        #URL
-    "code-of-conduct"?:       #URL
+    "detailed-guide"?:         #URL
+    "code-of-conduct"?:        #URL
     "quickstart-guide"?:       #URL
-    "release-process"?:       #URL
+    "release-process"?:        #URL
     "signature-verification"?: #URL
   }
 }
 
 repository?: {  
   status: "active" | "abandoned" | "concept" | "inactive" | "moved" | "suspended" | "unsupported" | "WIP"
-
-  "accepts-change-request":           bool
-  "accepts-automated-change-request": bool
-  "bug-fixes-only":                   bool
-  "no-third-party-packages":          bool
-  url:                                #URL
+  
+  url:                                 #URL
+  "accepts-change-request":            bool
+  "accepts-automated-change-request":  bool
+  "bug-fixes-only"?:                   bool
+  "no-third-party-packages"?:          bool
 
   "core-team": [...#Contact]
 

diff --git a/specification-details/aliases.md b/specification-details/aliases.md
@@ -1,6 +1,6 @@
 # Aliases
 
-The following aliases are used throughout the schema.
+The following aliases are used throughout the schema for consistency.
 
 ## `assessment`
 

diff --git a/specification-details/project.md b/specification-details/project.md
@@ -2,33 +2,30 @@
 
 The `project` object describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details.
 
----
-
-## `project.name`
-
-- **Type**: `string`
-- **Description**: The name of the project.
-
----
+This field is not required if `header.project-si-source` is supplied.
 
-## `project.homepage`
+## Required vs Optional Fields
 
-- **Type**: [URL]
-- **Description**: A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.
+Required if `project` is present:
 
----
+- `name`
+- `administrators`
+- `repositories`
+- `vulnerability-reporting`
 
-## `project.funding`
+Optional:
 
-- **Type**: [URL]
-- **Description**: A URL to information about sponsorships, donations, or other funding topics.
+- `homepage`
+- `funding`
+- `roadmap`
+- `documentation`
 
 ---
 
-## `project.roadmap`
+## `project.name`
 
-- **Type**: [URL]
-- **Description**: A URL pointing to a roadmap or schedule for planned features and releases.
+- **Type**: `string`
+- **Description**: The name of the project.
 
 ---
 
@@ -134,3 +131,30 @@ An object containing references to key documentation URLs.
 
 - **Type**: [URL]
 - **Description**: URL to documentation explaining how to verify digital signatures on assets.
+
+---
+
+## `project.homepage` (optional)
+
+- **Type**: [URL]
+- **Description**: A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.
+
+---
+
+## `project.funding` (optional)
+
+- **Type**: [URL]
+- **Description**: A URL to information about sponsorships, donations, or other funding topics.
+
+---
+
+## `project.roadmap` (optional)
+
+- **Type**: [URL]
+- **Description**: A URL pointing to a roadmap or schedule for planned features and releases.
+
+---
+
+[URL]: ./aliases.md#url
+[Contact]: ./aliases.md#contact
+[contacts]: ./aliases.md#contact
diff --git a/specification-details/repository.md b/specification-details/repository.md
@@ -2,7 +2,26 @@
 
 The `repository` object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture.
 
-This section is not required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories.
+This section is not required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories via their respective `header.project-si-source`.
+
+## Required vs Optional Fields
+
+Required if `repository` is present:
+
+- `status`
+- `url`
+- `accepts-change-request`
+- `accepts-automated-change-request`
+- `core-team`
+- `license`
+- `security`
+
+Optional top-level fields:
+
+- `documentation`
+- `release`
+- `bug-fixes-only` (assume false if not present)
+- `no-third-party-packages` (assume false if not present)
 
 ---
 

diff --git a/template-minimum.yml b/template-minimum.yml
@@ -10,9 +10,6 @@ header:
 
 project:
   name: FooBar
-  homepage: https://foo.bar
-  funding: https://foo.bar/FUNDING.yml
-  roadmap: https://foo.bar/roadmap.html
   administrators:
     - name: Joe Dohn
       affiliation: Foo
@@ -29,12 +26,10 @@ project:
     bug-bounty-available: true
 
 repository:
-  url: https://github.com/kubernetes/kubernetes
+  url: https://my.vcs/foobar/foo
   status: active
-  bug-fixes-only: false
   accepts-change-request: true
   accepts-automated-change-request: true
-  no-third-party-packages: false
   core-team:
     - name:        Alice White
       affiliation: Foo Bar