Merge pull request spdx#1 from davaya/template

Template

Author: goneall

README.md

@@ -0,0 +1,3 @@
+# JSON examples based on JSON-LD
+
+[PR #376](https://github.com/spdx/spdx-3-model/pull/376)

ex/annotation1.py

@@ -0,0 +1,3 @@
+# JSON serialization 375
+
+[PR #375](https://github.com/spdx/spdx-3-model/pull/375)

json1/README.md

@@ -0,0 +1 @@
+# Simplified JSON Serialization

json2/README.md

@@ -0,0 +1,3 @@
+# Native JSON-LD Serialization
+
+RDF-based JSON-LD examples

json3/README.md

@@ -0,0 +1,14 @@
+# Individual Element Examples
+
+The model directory contains Python example templates generated from the
+[SPDX model]() files, along with the code to generate those templates.
+## Model Types
+* `parse_model.py` reads the model files from GitHub and writes a local snapshot file `model_types.json`
+in the output directory, by default called `generated`.
+* `make_types.py` reads the model snapshot and generates a Python class file for each type defined in the model.
+These Python files are templates used to create logical examples of each type.
+
+## Individual Element Examples
+To create a new logical example, copy the type template (e.g. `person.py` into the [ex](../ex) folder,
+give it an example name (e.g., `person1.py`) and fill in each of the property values
+for that example.

jsonld/README.md

@@ -0,0 +1,48 @@
+# Using the Serialization Playground
+
+## Structure
+The playground directory structure has three components:
+1. A directory of Python [template classes](generated), with one template for each type defined by the model.
+Each template lists just the properties of the type, with no property values.
+2. A directory of Python [example classes](../ex) with property values from a template class filled in,
+3. A directory of serialized examples for each proposed serialization format, e.g., [JSON1](../json1).
+
+### Template Classes
+The template classes are generated from the logical model:
+```
+class Sbom:
+    sbomType: SBOMType = None
+    context: str = None
+    element: AnyUri = None
+    rootElement: AnyUri = None
+    namespaces: NamespaceMap = None
+    imports: ExternalMap = None
+    spdxId: AnyUri = None
+    name: str = None
+    summary: str = None
+    description: str = None
+    comment: str = None
+    creationInfo: CreationInfo = None
+    verifiedUsing: IntegrityMethod = None
+    externalReference: ExternalReference = None
+    externalIdentifier: ExternalIdentifier = None
+    extension: Extension = None
+```
+
+### Example Logical Values
+One example for each of the use cases listed in the [README](README.md).
+Each example logical value is a copy of the template for that type with property values filled in.
+Many of the model types will not have a use case, and a few types will have several use cases / examples.
+Contributors may propose additional example logical values to accompany corresponding serialized data.
+
+These are the logical values to be serialized into various serialization formats.
+All required properties must have a value; optional properties may be left empty (Python None).
+```
+class Sbom:
+    sbomType: SBOMType = 'source'
+    context: str = None
+    ... TBSL ...
+```
+### Serialized Examples
+The contributor of a format shows how an example logical value is serialized and parsed
+to/from the serialized value for that use case.

model/README.md

@@ -0,0 +1 @@
+# RDF Serialization

model/USING.md

@@ -0,0 +1,35 @@
+# Serialization Use Cases
+Mapping from spdx-3-model [use case list](https://github.com/spdx/spdx-3-model/blob/main/serialization/README.md)
+to Element Examples
+
+- **Person:** [Person1](ex/person1.md) with minimal CreationInfo 
+- **Agent:** [Agent1](ex/agent.md)
+- **Annotation:** [Annotation1](ex/annotation1.md)
+- **File:** [File1](ex/file1.md)
+- **Package:** [Package1](ex/package1.md) with [File1](ex/file1.md) and [File2](ex/file2.md)
+- **Package:** [Package2](ex/package2.md) with ExternalIdentifier
+- **Package:** [Package3](ex/package3.md) with ExternalReference
+- **Relationship:** [Relationship1](ex/relationship1.md) with [Package1](ex/package1.md) contains two Files
+- **Relationship:** [Relationship2](ex/relationship2.md) with time properties
+- **SBOM:** [Sbom1](ex/sbom1.md) with two Files
+- **SpdxDocument:** [SpdxDocument1](ex/spdxdocument1.md) with two Files
+- **SpdxDocument:** [SpdxDocument3](ex/spdxdocument3.md) with NamespaceMap
+- **SpdxDocument:** [SpdxDocument4](ex/spdxdocument4.md) with ExternalMap
+- **Person:** [Person3](ex/person3.md) with no CreationInfo *NOTE: invalid after model update*
+- **Person:** [Person1](ex/person1.md) with minimal CreationInfo
+- **Person:** [Person2](ex/person2.md) with full CreationInfo
+- **Bundle:** [Bundle1](ex/bundle1.md) *Note: with no elements?*
+- **two Persons:** [Person1](ex/person1.md) and [Person2](ex/person2.md)
+- **Bundle:** [Bundle2](ex/bundle2.md) of [Person1](ex/person1.md) and [Person2](ex/person2.md)
+
+Licensing use cases:
+- single artifact under one listed license: [License1](ex/license1.md)?
+- single artifact under one custom license: [CustomLicense1](ex/customlicense1.md)?
+- single artifact under license expression of listed licenses: [LicenseExpression1](ex/licenseexpression1.md)?
+- single artifact under license expression of listed and custom licenses: [LicenseExpression2](ex/licenseexpression2.md)?
+- two artifacts under same license expression of listed and custom licenses: [LicenseExpression3](ex/licenseexpression3.md)?
+
+*NOTE: need list of element types required by each licensing use case, specify which artifact examples*
+
+- security use cases to be added here
+- build use cases to be added here