THE SPDX WIKI IS NO LONGER ACTIVE. ALL CONTENT HAS BEEN MOVED TO https://github.com/spdx
Difference between revisions of "Documents/Producing SPDX Documents"
From SPDX Wiki
(→SPDX document for a binary delivery - uses relationships) |
|||
| (48 intermediate revisions by the same user not shown) | |||
| Line 22: | Line 22: | ||
= Overview = | = Overview = | ||
| + | SPDX documents describe the licensing associated with a files. These files can be organized into what we call a "Package". A package is merely a grouping of files, with some association to each other as defined by the creator of the document. In general, the association should be obvious, such as an SPDX document for a software library or application. SPDX Documents can use one of two formats: | ||
| − | = Structure of an SPDX Document = | + | * Tag/value -a simple text based format. Here is an example you can view. |
| + | * RDF/xml - a Resource Description Format developed by the W3C. Here is an example you can view. | ||
| + | |||
| + | You can use either format and there are SPDX tools to convert one format to another. The format you use will be based on your own factors, preference, tools and use. | ||
| + | |||
| + | = SPDX Document = | ||
| + | The most current version of the specification can be found here: [https://spdx.org/specifications Specifications]. Prior to reading through this document, we recommend you read through this section and then read through the latest specification to get a more in depth feel for the sections and fields. | ||
| + | |||
| + | |||
| + | == Structure of an SPDX Document == | ||
| + | |||
| + | [[File:specification21.png|300px|left]] | ||
| + | |||
| + | <p style="padding:10px;"> | ||
| + | |||
| + | SPDX Documents are composed of one or more sections. Some of these sections are required, while others are optional. If you examine the figure, you will see the following sections as of the 2.1 Specification: | ||
| + | * Document Creation Information - Denotes who created the document, how it was created and other useful information related to its creation. | ||
| + | * Package Information - This section provides information about the "package". A package can be one or more files. These files could be one or more files of any type including but not limited to source, documents, binaries, and so forth. The package information contains the originator, where it was sourced from, a download URL, a checksum and so forth. it also contains summary licensing for the package. | ||
| + | * File Information - This is information about a specific file. It can contain the file copyrights found in the file (if any), the license of the file, a checksum for the file, file contributors and so forth. | ||
| + | * Snippet Information - Snippet information can be used to define licensing for ranges within files. | ||
| + | * Other Licensing Information - Other licensing information provides a way to describe licenses that are not on the SPDX License List. You can create a local (to the SPDX document) identifier for the license and place the license text itself in the document as a well and then reference it for files just like you would a license from the license list. | ||
| + | * Relationships - Relationships were introduced in the 2.0 specification and are a very powerful way of expressing how SPDX documents relate to one another. See explanation and example above. | ||
| + | * Annotations - Annotations are comments made by people on various entities and elements within the document. For example, someone reviewing the document may make an annotation about a file and its license. Annotations are useful for reviews of SPDX documents and for conveying specific information about the package, file, creation, license, file(s), etc | ||
| + | </p> | ||
| + | |||
| + | == Optional vs. Required Fields == | ||
| + | |||
| + | Each field in the SPDX Specification has a Cardinality associated with it. Possible values for this are: xx. | ||
| + | |||
| + | As an example: Cardinality: Optional, one or many. | ||
| + | |||
| + | == Packages and Relationships == | ||
| + | |||
| + | |||
| + | <br/> | ||
= Tooling = | = Tooling = | ||
| + | |||
| + | == SPDX Workgroup Tools == | ||
| + | |||
| + | == Community Tools == | ||
| + | |||
| + | == Commercial Tools == | ||
= Strategies = | = Strategies = | ||
| + | |||
| + | |||
| + | == Build Time Generation of Documents == | ||
= Best Practices = | = Best Practices = | ||
| + | |||
| + | Editors Note: we may move this section to its own document upon completion. | ||
= Examples = | = Examples = | ||
| − | == A Simple Example == | + | The following application will be used in the examples for this section. As the examples are meant to build on one another in terms of the use case and complexity they show. Some examples may use only portions of the application. Each example will state what is used. By using one application, going through the examples should be easier. The application used is time, version 1.7 with some made up directories added (okay alone it was too simple). |
| + | |||
| + | Download the example here | ||
| + | |||
| + | == A Simple Example (aka hello world) == | ||
| + | |||
== Document with minimum Required Fields == | == Document with minimum Required Fields == | ||
| + | |||
== SPDX document for a binary delivery - no relationships == | == SPDX document for a binary delivery - no relationships == | ||
| − | == SPDX document for a binary delivery - uses | + | |
| + | == SPDX document for a binary delivery - uses relationship to point to source package == | ||
| + | |||
== SPDX document for an application delivery (source, binaries, documents, etc) - more expressive use of relationships == | == SPDX document for an application delivery (source, binaries, documents, etc) - more expressive use of relationships == | ||
Latest revision as of 15:02, 26 October 2016
|
SPDX Tech Report |
PRODUCING SPDX DOCUMENTS
version 0.1
WORKING DRAFT
Contents
- 1 Overview
- 2 SPDX Document
- 3 Tooling
- 4 Strategies
- 5 Best Practices
- 6 Examples
- 6.1 A Simple Example (aka hello world)
- 6.2 Document with minimum Required Fields
- 6.3 SPDX document for a binary delivery - no relationships
- 6.4 SPDX document for a binary delivery - uses relationship to point to source package
- 6.5 SPDX document for an application delivery (source, binaries, documents, etc) - more expressive use of relationships
Overview
SPDX documents describe the licensing associated with a files. These files can be organized into what we call a "Package". A package is merely a grouping of files, with some association to each other as defined by the creator of the document. In general, the association should be obvious, such as an SPDX document for a software library or application. SPDX Documents can use one of two formats:
- Tag/value -a simple text based format. Here is an example you can view.
- RDF/xml - a Resource Description Format developed by the W3C. Here is an example you can view.
You can use either format and there are SPDX tools to convert one format to another. The format you use will be based on your own factors, preference, tools and use.
SPDX Document
The most current version of the specification can be found here: Specifications. Prior to reading through this document, we recommend you read through this section and then read through the latest specification to get a more in depth feel for the sections and fields.
Structure of an SPDX Document
SPDX Documents are composed of one or more sections. Some of these sections are required, while others are optional. If you examine the figure, you will see the following sections as of the 2.1 Specification:
- Document Creation Information - Denotes who created the document, how it was created and other useful information related to its creation.
- Package Information - This section provides information about the "package". A package can be one or more files. These files could be one or more files of any type including but not limited to source, documents, binaries, and so forth. The package information contains the originator, where it was sourced from, a download URL, a checksum and so forth. it also contains summary licensing for the package.
- File Information - This is information about a specific file. It can contain the file copyrights found in the file (if any), the license of the file, a checksum for the file, file contributors and so forth.
- Snippet Information - Snippet information can be used to define licensing for ranges within files.
- Other Licensing Information - Other licensing information provides a way to describe licenses that are not on the SPDX License List. You can create a local (to the SPDX document) identifier for the license and place the license text itself in the document as a well and then reference it for files just like you would a license from the license list.
- Relationships - Relationships were introduced in the 2.0 specification and are a very powerful way of expressing how SPDX documents relate to one another. See explanation and example above.
- Annotations - Annotations are comments made by people on various entities and elements within the document. For example, someone reviewing the document may make an annotation about a file and its license. Annotations are useful for reviews of SPDX documents and for conveying specific information about the package, file, creation, license, file(s), etc
Optional vs. Required Fields
Each field in the SPDX Specification has a Cardinality associated with it. Possible values for this are: xx.
As an example: Cardinality: Optional, one or many.
Packages and Relationships
Tooling
SPDX Workgroup Tools
Community Tools
Commercial Tools
Strategies
Build Time Generation of Documents
Best Practices
Editors Note: we may move this section to its own document upon completion.
Examples
The following application will be used in the examples for this section. As the examples are meant to build on one another in terms of the use case and complexity they show. Some examples may use only portions of the application. Each example will state what is used. By using one application, going through the examples should be easier. The application used is time, version 1.7 with some made up directories added (okay alone it was too simple).
Download the example here
