Document additional json schema fields (#4356)

* add documentation to key fields Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com> * regenerate json schema Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com> --------- Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>
2026-11-02 07:26:34 +01:00 · 2025-11-10 16:29:06 -05:00
parent 78a4ab8ced
commit 66c78d44af
11 changed files with 509 additions and 227 deletions
@@ -35,14 +35,23 @@ func (d *Document) UnmarshalJSON(data []byte) error {
 	return nil
 }

-// Descriptor describes what created the document as well as surrounding metadata
+// Descriptor identifies the tool that generated this SBOM document, including its name, version, and configuration used during catalog generation.
 type Descriptor struct {
-	Name          string      `json:"name"`
-	Version       string      `json:"version"`
+	// Name is the name of the tool that generated this SBOM (e.g., "syft").
+	Name string `json:"name"`
+
+	// Version is the version of the tool that generated this SBOM.
+	Version string `json:"version"`
+
+	// Configuration contains the tool configuration used during SBOM generation.
 	Configuration interface{} `json:"configuration,omitempty"`
 }

+// Schema specifies the JSON schema version and URL reference that defines the structure and validation rules for this document format.
 type Schema struct {
+	// Version is the JSON schema version for this document format.
 	Version string `json:"version"`
-	URL     string `json:"url"`
+
+	// URL is the URL to the JSON schema definition document.
+	URL string `json:"url"`
 }
@@ -10,25 +10,55 @@ import (
 	"github.com/anchore/syft/syft/license"
 )

+// File represents a file discovered during cataloging with its metadata, content digests, licenses, and relationships to packages.
 type File struct {
-	ID         string             `json:"id"`
-	Location   file.Coordinates   `json:"location"`
-	Metadata   *FileMetadataEntry `json:"metadata,omitempty"`
-	Contents   string             `json:"contents,omitempty"`
-	Digests    []file.Digest      `json:"digests,omitempty"`
-	Licenses   []FileLicense      `json:"licenses,omitempty"`
-	Executable *file.Executable   `json:"executable,omitempty"`
-	Unknowns   []string           `json:"unknowns,omitempty"`
+	// ID is a unique identifier for this file within the SBOM.
+	ID string `json:"id"`
+
+	// Location is the file path and layer information where this file was found.
+	Location file.Coordinates `json:"location"`
+
+	// Metadata contains filesystem metadata such as permissions, ownership, and file type.
+	Metadata *FileMetadataEntry `json:"metadata,omitempty"`
+
+	// Contents is the file contents for small files.
+	Contents string `json:"contents,omitempty"`
+
+	// Digests contains cryptographic hashes of the file contents.
+	Digests []file.Digest `json:"digests,omitempty"`
+
+	// Licenses contains license information discovered within this file.
+	Licenses []FileLicense `json:"licenses,omitempty"`
+
+	// Executable contains executable metadata if this file is a binary.
+	Executable *file.Executable `json:"executable,omitempty"`
+
+	// Unknowns contains unknown fields for forward compatibility.
+	Unknowns []string `json:"unknowns,omitempty"`
 }

+// FileMetadataEntry contains filesystem-level metadata attributes such as permissions, ownership, type, and size for a cataloged file.
 type FileMetadataEntry struct {
-	Mode            int    `json:"mode"`
-	Type            string `json:"type"`
+	// Mode is the Unix file permission mode in octal format.
+	Mode int `json:"mode"`
+
+	// Type is the file type (e.g., "RegularFile", "Directory", "SymbolicLink").
+	Type string `json:"type"`
+
+	// LinkDestination is the target path for symbolic links.
 	LinkDestination string `json:"linkDestination,omitempty"`
-	UserID          int    `json:"userID"`
-	GroupID         int    `json:"groupID"`
-	MIMEType        string `json:"mimeType"`
-	Size            int64  `json:"size"`
+
+	// UserID is the file owner user ID.
+	UserID int `json:"userID"`
+
+	// GroupID is the file owner group ID.
+	GroupID int `json:"groupID"`
+
+	// MIMEType is the MIME type of the file contents.
+	MIMEType string `json:"mimeType"`
+
+	// Size is the file size in bytes.
+	Size int64 `json:"size"`
 }

 type auxFileMetadataEntry FileMetadataEntry
@@ -82,17 +112,31 @@ type sbomImportLegacyFileMetadataEntry struct {
 	Size            int64               `json:"Size"`
 }

+// FileLicense represents license information discovered within a file's contents or metadata, including the matched license text and SPDX expression.
 type FileLicense struct {
-	Value          string               `json:"value"`
-	SPDXExpression string               `json:"spdxExpression"`
-	Type           license.Type         `json:"type"`
-	Evidence       *FileLicenseEvidence `json:"evidence,omitempty"`
+	// Value is the raw license identifier or text as found in the file.
+	Value string `json:"value"`
+
+	// SPDXExpression is the parsed SPDX license expression.
+	SPDXExpression string `json:"spdxExpression"`
+
+	// Type is the license type classification (e.g., declared, concluded, discovered).
+	Type license.Type `json:"type"`
+
+	// Evidence contains supporting evidence for this license detection.
+	Evidence *FileLicenseEvidence `json:"evidence,omitempty"`
 }

+// FileLicenseEvidence contains supporting evidence for a license detection in a file, including the byte offset, extent, and confidence level.
 type FileLicenseEvidence struct {
+	// Confidence is the confidence score for this license detection (0-100).
 	Confidence int `json:"confidence"`
-	Offset     int `json:"offset"`
-	Extent     int `json:"extent"`
+
+	// Offset is the byte offset where the license text starts in the file.
+	Offset int `json:"offset"`
+
+	// Extent is the length of the license text in bytes.
+	Extent int `json:"extent"`
 }

 type intOrStringFileType struct {
@@ -4,28 +4,67 @@ import (
 	"encoding/json"
 )

+// IDLikes represents a list of distribution IDs that this Linux distribution is similar to or derived from, as defined in os-release ID_LIKE field.
 type IDLikes []string

+// LinuxRelease contains Linux distribution identification and version information extracted from /etc/os-release or similar system files.
 type LinuxRelease struct {
-	PrettyName       string  `json:"prettyName,omitempty"`
-	Name             string  `json:"name,omitempty"`
-	ID               string  `json:"id,omitempty"`
-	IDLike           IDLikes `json:"idLike,omitempty"`
-	Version          string  `json:"version,omitempty"`
-	VersionID        string  `json:"versionID,omitempty"`
-	VersionCodename  string  `json:"versionCodename,omitempty"`
-	BuildID          string  `json:"buildID,omitempty"`
-	ImageID          string  `json:"imageID,omitempty"`
-	ImageVersion     string  `json:"imageVersion,omitempty"`
-	Variant          string  `json:"variant,omitempty"`
-	VariantID        string  `json:"variantID,omitempty"`
-	HomeURL          string  `json:"homeURL,omitempty"`
-	SupportURL       string  `json:"supportURL,omitempty"`
-	BugReportURL     string  `json:"bugReportURL,omitempty"`
-	PrivacyPolicyURL string  `json:"privacyPolicyURL,omitempty"`
-	CPEName          string  `json:"cpeName,omitempty"`
-	SupportEnd       string  `json:"supportEnd,omitempty"`
-	ExtendedSupport  bool    `json:"extendedSupport,omitempty"`
+	// PrettyName is a human-readable operating system name with version.
+	PrettyName string `json:"prettyName,omitempty"`
+
+	// Name is the operating system name without version information.
+	Name string `json:"name,omitempty"`
+
+	// ID is the lower-case operating system identifier (e.g., "ubuntu", "rhel").
+	ID string `json:"id,omitempty"`
+
+	// IDLike is a list of operating system IDs this distribution is similar to or derived from.
+	IDLike IDLikes `json:"idLike,omitempty"`
+
+	// Version is the operating system version including codename if available.
+	Version string `json:"version,omitempty"`
+
+	// VersionID is the operating system version number or identifier.
+	VersionID string `json:"versionID,omitempty"`
+
+	// VersionCodename is the operating system release codename (e.g., "jammy", "bullseye").
+	VersionCodename string `json:"versionCodename,omitempty"`
+
+	// BuildID is a build identifier for the operating system.
+	BuildID string `json:"buildID,omitempty"`
+
+	// ImageID is an identifier for container or cloud images.
+	ImageID string `json:"imageID,omitempty"`
+
+	// ImageVersion is the version for container or cloud images.
+	ImageVersion string `json:"imageVersion,omitempty"`
+
+	// Variant is the operating system variant name (e.g., "Server", "Workstation").
+	Variant string `json:"variant,omitempty"`
+
+	// VariantID is the lower-case operating system variant identifier.
+	VariantID string `json:"variantID,omitempty"`
+
+	// HomeURL is the homepage URL for the operating system.
+	HomeURL string `json:"homeURL,omitempty"`
+
+	// SupportURL is the support or help URL for the operating system.
+	SupportURL string `json:"supportURL,omitempty"`
+
+	// BugReportURL is the bug reporting URL for the operating system.
+	BugReportURL string `json:"bugReportURL,omitempty"`
+
+	// PrivacyPolicyURL is the privacy policy URL for the operating system.
+	PrivacyPolicyURL string `json:"privacyPolicyURL,omitempty"`
+
+	// CPEName is the Common Platform Enumeration name for the operating system.
+	CPEName string `json:"cpeName,omitempty"`
+
+	// SupportEnd is the end of support date or version identifier.
+	SupportEnd string `json:"supportEnd,omitempty"`
+
+	// ExtendedSupport indicates whether extended security or support is available.
+	ExtendedSupport bool `json:"extendedSupport,omitempty"`
 }

 func (s *IDLikes) UnmarshalJSON(data []byte) error {
@@ -36,22 +36,40 @@ type PackageBasicData struct {
 	PURL      string          `json:"purl"`
 }

+// cpes is a collection of Common Platform Enumeration identifiers for a package.
 type cpes []CPE

+// CPE represents a Common Platform Enumeration identifier used for matching packages to known vulnerabilities in security databases.
 type CPE struct {
-	Value  string `json:"cpe"`
+	// Value is the CPE string identifier.
+	Value string `json:"cpe"`
+
+	// Source is the source where this CPE was obtained or generated from.
 	Source string `json:"source,omitempty"`
 }

+// licenses is a collection of license findings associated with a package.
 type licenses []License

+// License represents software license information discovered for a package, including SPDX expressions and supporting evidence locations.
 type License struct {
-	Value          string          `json:"value"`
-	SPDXExpression string          `json:"spdxExpression"`
-	Type           license.Type    `json:"type"`
-	URLs           []string        `json:"urls"`
-	Locations      []file.Location `json:"locations"`
-	Contents       string          `json:"contents,omitempty"`
+	// Value is the raw license identifier or expression as found.
+	Value string `json:"value"`
+
+	// SPDXExpression is the parsed SPDX license expression.
+	SPDXExpression string `json:"spdxExpression"`
+
+	// Type is the license type classification (e.g., declared, concluded, discovered).
+	Type license.Type `json:"type"`
+
+	// URLs are URLs where license text or information can be found.
+	URLs []string `json:"urls"`
+
+	// Locations are file locations where this license was discovered.
+	Locations []file.Location `json:"locations"`
+
+	// Contents is the full license text content.
+	Contents string `json:"contents,omitempty"`
 }

 func newModelLicensesFromValues(licenses []string) (ml []License) {
@@ -1,8 +1,16 @@
 package model

+// Relationship represents a directed relationship between two artifacts in the SBOM, such as package-contains-file or package-depends-on-package.
 type Relationship struct {
-	Parent   string      `json:"parent"`
-	Child    string      `json:"child"`
-	Type     string      `json:"type"`
+	// Parent is the ID of the parent artifact in this relationship.
+	Parent string `json:"parent"`
+
+	// Child is the ID of the child artifact in this relationship.
+	Child string `json:"child"`
+
+	// Type is the relationship type (e.g., "contains", "dependency-of", "ancestor-of").
+	Type string `json:"type"`
+
+	// Metadata contains additional relationship-specific metadata.
 	Metadata interface{} `json:"metadata,omitempty"`
 }
@@ -11,18 +11,25 @@ import (
 	"github.com/anchore/syft/syft/source"
 )

-// Source object represents the thing that was cataloged
-// Note: syft currently makes no claims or runs any logic to determine the Supplier field below
-
-// Instead, the Supplier can be determined by the user of syft and passed as a config or flag to help fulfill
-// the NTIA minimum elements. For mor information see the NTIA framing document below
-// https://www.ntia.gov/files/ntia/publications/framingsbom_20191112.pdf
+// Source represents the artifact that was analyzed to generate this SBOM, such as a container image, directory, or file archive.
+// The Supplier field can be provided by users to fulfill NTIA minimum elements requirements.
 type Source struct {
-	ID       string      `json:"id"`
-	Name     string      `json:"name"`
-	Version  string      `json:"version"`
-	Supplier string      `json:"supplier,omitempty"`
-	Type     string      `json:"type"`
+	// ID is a unique identifier for the analyzed source artifact.
+	ID string `json:"id"`
+
+	// Name is the name of the analyzed artifact (e.g., image name, directory path).
+	Name string `json:"name"`
+
+	// Version is the version of the analyzed artifact (e.g., image tag).
+	Version string `json:"version"`
+
+	// Supplier is supplier information, which can be user-provided for NTIA minimum elements compliance.
+	Supplier string `json:"supplier,omitempty"`
+
+	// Type is the source type (e.g., "image", "directory", "file").
+	Type string `json:"type"`
+
+	// Metadata contains additional source-specific metadata.
 	Metadata interface{} `json:"metadata"`
 }