add spec to reference designs

Signed-off-by: Adolfo García Veytia (Puerco) <[email protected]>

semantics/oci-image.md

@@ -62,4 +62,56 @@ class SourceCode {
     Image --> Layer2: CONTAINS
     Image --> Layer3: CONTAINS
 
-```
+```
+
+## Design Specification
+
+The goal of this design is to allow maximum flexibility when adding metadata
+to the image components.
+
+### Package Structure
+
+The top level package represents the container image and references its manifest.
+The name of the package should be the digest of the image manifest, preceded as
+usual by the algorithm, eg `sha256:923784e51e709f...`.
+
+The image package can con contain three types of packages:
+
+#### Container Layer
+
+Each of the image layers hould be represented in a package. Ideally, the image
+SBOM should describe the whole container image structure. Just as the image,
+layers should also be named using their digests. The can layer can contain a
+purl of type OCI to reference it.
+
+#### Base Image
+
+Images often are derived from other images. When the described image uses as a 
+base another image, the SBOM can reference it using a package. In order to ensure
+that tools can discern the base image from other OCI artifacts, the base image
+package should be related to the image via a `DESCENDANT_OF` relationship.
+
+#### Source Package
+
+The SBOM describing the image should also reference the VCS URL where the source
+to build the image lives. To describe the build code, the image SBOM should have
+a package pointing to the source repository. This package should be related to the
+image package using a `GENERATED_FROM` relationship. 	  
+
+### Software Identifiers
+
+The image package, the layers and the base image should contain external references
+to the OCI artifacts using purls. The purl should of type [`oci`](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#oci) and does not require adding data about the registry,
+repository or tags (but it may). WHen including os/arch metadata in the purl, only
+the image should have it.
+
+The source code package should include a pointer to the repository containing the
+code that generated the image.
+
+**Note:** This is not a reference to the application source code, it is a reference
+to the code that was used to build the image (eg its Dockerfile).
+
+The purl referncing the source repository should be of type [github](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#github) if the code lives there. Check for other
+suitable types if the source is not hosted in GitHub.  
+
+

semantics/oci-layer.md

@@ -35,3 +35,27 @@ Layer --> busybox: CONTAINS
 
 Layer --> cacertificatesbundle: CONTAINS
 ```
+## Design Specification
+
+The goal of this design is to allow maximum flexibility when adding metadata
+to the layer package. Generally, a layer abstracts a filesystem so it can
+potentially contain anything. This is why the layer abstraction should have
+room for current and unexpected uses.
+
+### Package Structure
+
+The package in this design represents a layer in a container image. Separating the
+layers into their own packages ensures that adding data about packages can be added
+to the appropiate section of the SBOM. For example, a layer can express an added file
+via a `curl` pull while another can add child packages detailing the installed OS
+dependencies.
+
+Things inside of images should be added as SPDX Packages and Files and related using a
+CONTAINS relationship. 
+
+### Software Identifiers
+
+The package representing a layer should have a purl of type `oci` referencing the 
+layer in a registry-neutral way. No os/arch data needs be added to the purl as 
+the layer will mostl likely live under an image SBOM which should include the platform
+info. 

semantics/oci-multiarch-index.md

@@ -14,14 +14,13 @@ in the purl external reference.
 
 ## Structure Diagram
 
-
 ```mermaid
 classDiagram
   direction LR
 class ImageIndex{
-  PackageName: sha256:923784
+  PackageName: sha256:923784e51e709f
   ExternalRef: PACKAGE_MANAGER purl pkg:oci/alpine@sha256:923[...]
-  PackageChecksum: SHA256 923784
+  PackageChecksum: SHA256 923784e51e709f
 }
 class Image{
   PackageName: sha256:5fbbc2112ee51e709f374c9c01e
@@ -37,3 +36,23 @@ class Image2 {
     ImageIndex --> Image: VARIANT_OF
     ImageIndex --> Image2: VARIANT_OF
 ```
+
+## Design Specification
+
+### Package Structure
+
+The top level package represents the image index. The name of the package should be
+the digest of its manifest, preceded as usual by the algorithm,
+eg `sha256:923784e51e709f...`.
+
+Each container image fronted by the image must be represented by another package, also
+named as its digest. Each of these packages should be related to the index using a 
+`VARIANT_OF` SPDX relationship.
+
+### Software Identifiers
+
+Each of the packages in this design should contain a reference to the OCI object using
+a [purl of type `oci`](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#oci).
+Packages representing the single arch images must contain the os/arch metadata and optionally
+can add tag and repository metadata.
+