DISCUSSION: SPDX 3 data model

go.mod

@@ -1,6 +1,6 @@
 module github.com/spdx/tools-golang
 
-go 1.13
+go 1.18
 
 require (
 	github.com/anchore/go-struct-converter v0.0.0-20221118182256-c68fdcfa2092

spdx/v3/v3_0/README.md

@@ -0,0 +1,53 @@
+# SPDX 3 Model Patterns
+
+This is a non-exhaustive list of some patterns we are able to use in Golang to work with an SPDX 3 data model.
+
+I've included some variations I think we should consider. An explanation is as follows, along with some pros/cons:
+
+- [embedded first](embedded_first) - lean into modifying go structs directly with exported fields, using struct embedding.
+This requires using interfaces, but the interfaces are simple single-functions to get an editable embedded struct.
+  - pro: interfaces are simple
+  - pro: modifying structs is simple and idiomatic
+  - pro: minimal surface area: very few additional functions necessary
+  - con: construction is confusing -- which nesting has field X?
+  - con: naming is hard, need `Package` and `IPackage`
+
+
+- [interfaces only](interfaces_only) - only export interfaces and use interfaces to interact with structs.
+NOTE: this also includes a variant that setters return `error`, which could be applied to other options.
+This option only exports the interface types and simple no-arg constructor functions.
+  - pro: idiomatic getter naming (without `Get`)
+  - pro: single type exported, data structs are not
+  - pro: minimal surface area: no extra helper functions/structs that we may decide to change later
+  - con: absolutely no JSON/etc. output
+  - con: getter/setter still not especially idiomatic
+  - con: duplicated code because no embedding
+  - con: construction is tedious and could be error-prone if referencing wrong variable name
+
+
+- [interfaces only with constructors](interfaces_only/constructors)
+  - (generally same pros/cons as above), but:
+  - pro: much simpler construction pattern for users
+  - pro: single validation spot during construction (with returning `error` pattern)
+  - con: more structs and functions exported which cannot be changed without breaking backwards compatibility
+
+
+- [inverted](inverted) - since we know the entire data model and it does not need to be extended,
+  it is possible to implement an uber-struct without the need to use interfaces at all.
+I thought I'd mention this for some semblance of completeness, but this is probably a very bad idea. 
+  - pro: single set of types exported
+  - pro: fairly easy to interact with existing documents
+  - con: easy to construct incorrectly
+  - con: potential unneecssary memory usage
+
+
+- [embedded with interfaces and constructors](embedded_with_interfaces_and_constructors) - takes the approach of both 
+embedding and interfaces, along with constructor functions. This makes creation reasonably simple and working with
+existing documents reasonably simple.
+  - pro: probably the most idiomatic Go of these options
+  - pro: simple construction
+  - pro: reasonably simple to work with existing documents
+  - pro: eliminates some code duplication seen with `interfaces_only`
+  - con: getter/setter still not especially idiomatic
+  - con: larger surface area: at least 4 exported parts for each type
+  - con: absolutely no JSON/etc. output

spdx/v3/v3_0/embedded_first/model.go

@@ -0,0 +1,161 @@
+package v3_0
+
+import "time"
+
+type ElementID string
+
+// ----------------------- SpdxDocument -----------------------
+
+type SpdxDocument struct {
+	ElementCollection
+
+	NamespaceMap map[string]string
+}
+
+type ISpdxDocument interface {
+	IElementCollection
+}
+
+// ----------------------- ElementCollection -----------------------
+
+type ElementCollection struct {
+	Element
+
+	RootElements []IElement
+	Elements     []IElement
+}
+
+type IElementCollection interface {
+	IElement
+
+	AsElementCollection() *ElementCollection
+}
+
+// ----------------------- Element -----------------------
+
+type Element struct {
+	SpdxID ElementID
+	Name   string
+}
+
+func (e *Element) AsElement() *Element {
+	return e
+}
+
+type IElement interface {
+	AsElement() *Element
+}
+
+var _ interface {
+	IElement
+} = (*Element)(nil)
+
+// ----------------------- Artifact -----------------------
+
+type Artifact struct {
+	Element
+
+	BuiltTime time.Time
+}
+
+func (a *Artifact) AsArtifact() *Artifact {
+	return a
+}
+
+type IArtifact interface {
+	IElement
+
+	AsArtifact() *Artifact
+}
+
+var _ interface {
+	IArtifact
+} = (*Artifact)(nil)
+
+// ----------------------- SoftwareArtifact -----------------------
+
+type SoftwareArtifact struct {
+	Artifact
+
+	CopyrightText string
+}
+
+type ISoftwareArtifact interface {
+	IArtifact
+
+	AsSoftwareArtifact() *SoftwareArtifact
+}
+
+func (a *SoftwareArtifact) AsSoftwareArtifact() *SoftwareArtifact {
+	return a
+}
+
+var _ interface {
+	ISoftwareArtifact
+} = (*SoftwareArtifact)(nil)
+
+// ----------------------- Package -----------------------
+
+type IPackage interface {
+	ISoftwareArtifact
+
+	AsPackage() *Package
+}
+
+type Package struct {
+	SoftwareArtifact
+
+	PackageVersion string
+}
+
+func (p *Package) AsPackage() *Package {
+	return p
+}
+
+var _ interface {
+	IPackage
+} = (*Package)(nil)
+
+// ----------------------- File -----------------------
+
+type IFile interface {
+	ISoftwareArtifact
+
+	AsFile() *File
+}
+
+type File struct {
+	SoftwareArtifact
+
+	ContentType string
+}
+
+func (f *File) AsFile() *File {
+	return f
+}
+
+var _ IPackage = (*Package)(nil)
+
+// ----------------------- Relationship -----------------------
+
+type RelationshipType string
+
+type Relationship struct {
+	Element
+
+	RelationshipType RelationshipType
+	From             IElement
+	To               []IElement
+}
+
+type IRelationship interface {
+	IElement
+
+	AsRelationship() *Relationship
+}
+
+func (r *Relationship) AsRelationship() *Relationship {
+	return r
+}
+
+var _ IRelationship = (*Relationship)(nil)

spdx/v3/v3_0/embedded_first/model_test.go

@@ -0,0 +1,70 @@
+package v3_0
+
+import (
+	"fmt"
+	"testing"
+)
+
+func Test_makeAnSpdxDocument(t *testing.T) {
+	// creating new documents: 2 packages found from 1 file with 2 relationships
+
+	// embedded nesting is not ideal when instantiating:
+	pkg1 := &Package{
+		SoftwareArtifact: SoftwareArtifact{
+			Artifact: Artifact{
+				Element: Element{
+					SpdxID: "pkg-1",
+					Name:   "pkg-1",
+				},
+			},
+		},
+		PackageVersion: "1.0.0",
+	}
+
+	// can just reference properties directly, once an object exists:
+	pkg2 := &Package{}
+	pkg2.SpdxID = "package-2"
+	pkg2.Name = "package-2"
+	pkg2.PackageVersion = "2.0.0"
+
+	file1 := &File{}
+	file1.SpdxID = "file-1"
+	file1.Name = "file-1"
+	file1.ContentType = "text/plain"
+
+	file1containsPkg1 := &Relationship{
+		RelationshipType: "CONTAINS",
+		From:             file1,
+		To:               []IElement{pkg1},
+	}
+
+	pkg1dependsOnFile1 := &Relationship{
+		RelationshipType: "DEPENDS_ON",
+		From:             pkg1,
+		To:               []IElement{pkg2},
+	}
+
+	doc := SpdxDocument{
+		ElementCollection: ElementCollection{
+			Element: Element{
+				SpdxID: "spdx-document",
+			},
+			Elements: []IElement{
+				pkg1,
+				pkg2,
+				pkg1dependsOnFile1,
+				file1containsPkg1,
+			},
+		},
+	}
+	fmt.Printf("%#v\n", doc)
+
+	// working with existing documents
+
+	for _, e := range doc.Elements {
+		if e, ok := e.(IPackage); ok {
+			e.AsPackage().Name = "updated-name"
+		}
+	}
+	fmt.Printf("%#v\n", doc)
+}