diff --git a/README.md b/README.md
index 0cb88542..171597c6 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,106 @@
# Spdx-Java-Library
[](https://maven-badges.herokuapp.com/maven-central/org.spdx/java-spdx-library)
+[](https://javadoc.io/doc/org.spdx/java-spdx-library)
-Java library which implements the Java object model for SPDX and provides useful helper functions.
-
-The API documentation is available at:
-
-
-## Code quality badges
-
[](https://sonarcloud.io/dashboard?id=java-spdx-library)
[](https://sonarcloud.io/dashboard?id=java-spdx-library)
[](https://sonarcloud.io/dashboard?id=java-spdx-library)
[](https://sonarcloud.io/dashboard?id=java-spdx-library)
+Spdx-Java-Library is a Java library which implements the Java object model for SPDX and provides useful helper functions.
+
+The library is available in Maven Central as
+[`org.spdx:java-spdx-library`](https://search.maven.org/artifact/org.spdx/java-spdx-library)
+(note the order of the word "java-spdx").
+
+If you are using Maven, you can add the following dependency in your POM file:
+
+```xml
+
+ org.spdx
+ java-spdx-library
+ [2.0,3.0)
+
+```
+
+See the [GETTING-STARTED.md](GETTING-STARTED.md) file for installation
+instructions and how to get started in different scenarios.
+
+## Table of Contents
+
+- [Library Version Compatibility](#library-version-compatibility)
+- [API Documentation](#api-documentation)
+- [Storage Interface](#storage-interface)
+ - [Storage Interface Usage](#storage-interface-usage)
+- [Multi-Threaded Considerations](#multi-threaded-considerations)
+- [Configuration Options](#configuration-options)
+- [Initialization](#initialization)
+- [Update for New Versions of the Spec](#update-for-new-versions-of-the-spec)
+- [Contributing](#contributing)
+
## Library Version Compatibility
Library version 2.0.0 and higher is not compatible with previous versions of the library due to breaking changes introduced in SPDX 3.0.
-The library does support the spec versions 2.X and 3.X.
+However, the library supports both SPDX specification versions 2.X and 3.X.
-See the [README-V3-UPGRADE.md](README-V3-UPGRADE.md) file for information on how to upgrade from earlier versions of the library.
+See [README-V3-UPGRADE.md](README-V3-UPGRADE.md) for library upgrade instructions.
+
+## API Documentation
+
+Here are links to the API documentation for the family of SPDX Java libraries.
+
+"release" points to the API documentation of the latest stable version of the library, while "dev" points to the API documentation generated every time there is an update in the library's GitHub repository.
+
+| Library | Description | Doc (release) | Doc (dev) |
+|-|-|-|-|
+| [java-spdx-library][lib-gh] | Core library implementing the SPDX Java object model and helper functions. | [release][lib-docr] | [dev][lib-docd] |
+| [spdx-java-core][core-gh] | Core utilities and shared functionality for SPDX Java libraries. | [release][core-docr] | [dev][core-docd] |
+| Model | | | |
+| [spdx-java-model-2_X][model2-gh] | Model implementation for SPDX 2.X specification. | [release][model2-docr] | [dev][model2-docd] |
+| [spdx-java-model-3_0][model3-gh] | Model implementation for SPDX 3.0 specification. | [release][model3-docr] | |
+| Model store | | | |
+| [spdx-jackson-store][jackson-gh] | Jackson Databind-based storage implementation for SPDX objects. Supports JSON, YAML and XML formats. | [release][jackson-docr] | |
+| [spdx-rdf-store][rdf-gh] | RDF-based storage implementation for SPDX objects. | [release][rdf-docr] | [dev][rdf-docd] |
+| [spdx-spreadsheet-store][spreadsheet-gh] | Spreadsheet-based storage implementation for SPDX objects. Supports XLS and XLSX formats. | [release][spreadsheet-docr] | |
+| [spdx-tagvalue-store][tagvalue-gh] | Tag-value-file-based storage implementation for SPDX objects. | [release][tagvalue-docr] | [dev][tagvalue-docd] |
+| [spdx-v3jsonld-store][v3jsonld-gh] | JSON-LD-based storage implementation for SPDX 3 objects. | [release][v3jsonld-docr] | [dev][v3jsonld-docd] |
+| Tools | | | |
+| [spdx-model-to-java][genjava-gh] | Generates Java source files from SPDX 3 model files. Used for spdx-java-model-3_0. | | |
+| [spdx-maven-plugin][maven-gh] | Maven plugin producing SPDX documents for artifacts described in the Maven POM file. | [release][maven-docr] | |
+| [tools-java][tools-gh] | Command-line tools for working with SPDX documents. | [release][tools-docr] | |
+
+[lib-gh]: https://github.com/spdx/Spdx-Java-Library
+[lib-docr]: https://javadoc.io/doc/org.spdx/java-spdx-library
+[lib-docd]: https://spdx.github.io/Spdx-Java-Library/
+[core-gh]: https://github.com/spdx/spdx-java-core
+[core-docr]: https://javadoc.io/doc/org.spdx/spdx-java-core
+[core-docd]: https://spdx.github.io/spdx-java-core/
+[model2-gh]: https://github.com/spdx/spdx-java-model-2_X
+[model2-docr]: https://javadoc.io/doc/org.spdx/spdx-java-model-2_X
+[model2-docd]: https://spdx.github.io/spdx-java-model-2_X/
+[model3-gh]: https://github.com/spdx/spdx-java-model-3_0
+[model3-docr]: https://javadoc.io/doc/org.spdx/spdx-java-model-3_0
+[jackson-gh]: https://github.com/spdx/spdx-java-jackson-store
+[jackson-docr]: https://javadoc.io/doc/org.spdx/spdx-jackson-store
+[rdf-gh]: https://github.com/spdx/spdx-java-rdf-store
+[rdf-docr]: https://javadoc.io/doc/org.spdx/spdx-rdf-store
+[rdf-docd]: https://spdx.github.io/spdx-java-rdf-store/
+[spreadsheet-gh]: https://github.com/spdx/spdx-java-spreadsheet-store
+[spreadsheet-docr]: https://javadoc.io/doc/org.spdx/spdx-spreadsheet-store
+[tagvalue-gh]: https://github.com/spdx/spdx-java-tagvalue-store
+[tagvalue-docr]: https://javadoc.io/doc/org.spdx/spdx-tagvalue-store
+[tagvalue-docd]: https://spdx.github.io/spdx-java-tagvalue-store/
+[v3jsonld-gh]: https://github.com/spdx/spdx-java-v3jsonld-store
+[v3jsonld-docr]: https://javadoc.io/doc/org.spdx/spdx-v3jsonld-store
+[v3jsonld-docd]: https://spdx.github.io/spdx-java-v3jsonld-store/
+[genjava-gh]: https://github.com/spdx/spdx-model-to-java
+[maven-gh]: https://github.com/spdx/spdx-maven-plugin
+[maven-docr]: https://javadoc.io/doc/org.spdx/spdx-maven-plugin/latest/index.html
+[tools-gh]: https://github.com/spdx/tools-java
+[tools-docr]: https://javadoc.io/doc/org.spdx/tools-java
## Storage Interface
@@ -34,7 +113,7 @@ See the [README-V3-UPGRADE.md](README-V3-UPGRADE.md) file for information on how
This interface is currently used to implement JSON, XML, YAML, and RDF/XML
formats.
- The default storage interface is an in-memory Map which should be sufficient
- for light weight usage of the library.
+ for lightweight usage of the library.
### Storage Interface Usage
@@ -58,15 +137,6 @@ support multi-threaded applications.
These methods serialize access to the model store for the specific SPDX
document used for the SPDX model object.
-## Getting Started
-
-See the [GETTING-STARTED.md](GETTING-STARTED.md) file for how to get started in different scenarios.
-
-## API Documentation
-
-The API documentation is available at:
-
-
## Configuration options
`Spdx-Java-Library` can be configured using either Java system properties or a Java properties file located in the runtime CLASSPATH at `/resources/spdx-java-library.properties`.
@@ -98,7 +168,7 @@ InMemSpdxStore modelStore = new InMemSpdxStore();
IModelCopyManager copyManager = new ModelCopyManager();
```
-Many factory and helper methods in the library make use of a DefaultModelStore
+Many factory and helper methods in the library make use of a `DefaultModelStore`
if no model store or copy manager is specified.
The `SpdxModelFactory.init()` will create defaults for this purpose.
@@ -127,6 +197,14 @@ To update Spdx-Java-Library, the following is a very brief checklist:
## Development Status
-Note: This library is currently unstable, and under development.
-Reviews, suggestions are welcome.
-Please enter an issue with any suggestions.
+Stable.
+
+## Contributing
+
+Reviews and suggestions are welcome.
+Please [submit an issue][issues] with any suggestions.
+
+See [CONTRIBUTING.md][contributing] for contribution guidelines.
+
+[issues]: https://github.com/spdx/Spdx-Java-Library/issues
+[contributing]: https://github.com/spdx/Spdx-Java-Library/blob/master/CONTRIBUTING.md