diff --git a/README.md b/README.md
index e68be8fd..94e82e4f 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
[![shield_npm-version]][link_npm]
[![shield_rtfd]][link_rtfd]
-[![shield_gh-workflow-test]][link_gh_workflow_test]
+[![shield_gh-workflow-test]][link_gh-workflow-test]
[![shield_coverage]][link_codacy]
-[![shield_ossf-best-practices]][link_ossf_best_practices]
+[![shield_ossf-best-practices]][link_ossf-best-practices]
[![shield_license]][license_file]
[![shield_website]][link_website]
[![shield_slack]][link_slack]
@@ -13,48 +13,54 @@
----
-Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), written in _TypeScript_ and compiled for the target.
+Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_),
+written in _TypeScript_ and compiled for the target.
## Responsibilities
-* Provide a general-purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_.
-* Provide typing for said implementation, so developers and dev-tools can rely on it.
-* Provide data models to work with _CycloneDX_.
-* Provide JSON- and XML-normalizers that:
- * Support all shipped data models.
- * Respect any injected [_CycloneDX_ Specification][CycloneDX-spec] and generate valid output according to it.
- * Can be configured to generate reproducible/deterministic output.
- * Can prepare data structures for JSON- and XML-serialization.
-* Serialization:
- * Provide a universal JSON-serializer for all target environments.
- * Provide an XML-serializer for all target environments.
- * Support the downstream implementation of custom XML-serializers tailored to specific environments by providing an abstract base class that takes care of normalization and BomRef-discrimination. This is done because there is no universal XML support in _JavaScript_.
-* Provide formal JSON- and XML-validators according to [_CycloneDX_ Specification][CycloneDX-spec] (currently for _Node.js_ only).
+The CycloneDX JavaScript Library is responsible for:
+
+* Providing a general purpose JavaScript implementation of CycloneDX for Node.js and WebBrowsers
+* Providing comprehensive TypeScript typings for developer tooling support
+* Implementing core CycloneDX data models
+* Providing JSON and XML normalizers that:
+ * Support all shipped data models
+ * Respect injected CycloneDX Specifications and generate valid output
+ * Can be configured for reproducible/deterministic output
+ * Prepare data structures for JSON and XML serialization
+* Handling serialization through:
+ * Universal JSON serializer for all target environments
+ * XML serializer for all target environments
+ * Support for custom XML serializer implementations via abstract base class
+* Providing formal JSON and XML validators according to CycloneDX Specification (Node.js only)
## Capabilities
-* **Enums** for the following use cases:
- * `AttachmentEncoding`
- * `ComponentScope`
- * `ComponentType`
- * `ExternalReferenceType`
- * `HashAlgorithm`
- * **Vulnerability** related:
- * `AffectStatus`
- * `AnalysisJustification`
- * `AnalysisResponse`
- * `AnalysisState`
- * `RatingMethod`
- * `Severity`
-
-* **Data Models** for the following use cases:
+The library provides:
+
+### Enums
+* `AttachmentEncoding`
+* `ComponentScope`
+* `ComponentType`
+* `ExternalReferenceType`
+* `HashAlgorithm`
+* Vulnerability-related:
+ * `AffectStatus`
+ * `AnalysisJustification`
+ * `AnalysisResponse`
+ * `AnalysisState`
+ * `RatingMethod`
+ * `Severity`
+
+### Data Models
+* Core Models:
* `Attachment`
* `Bom`
* `BomLink`, `BomLinkDocument`, `BomLinkElement`
* `BomRef`, `BomRefRepository`
* `Component`, `ComponentRepository`, `ComponentEvidence`
* `ExternalReference`, `ExternalReferenceRepository`
- * `Hash`, `HashContent`, `HashDictionary`
+ * `Hash`, `HashContent`, `HashDictionary`
* `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository`
* `Metadata`
* `OrganizationalContact`, `OrganizationalContactRepository`
@@ -63,52 +69,146 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or
* `SWID`
* `Tool`, `ToolRepository`
-* **Vulnerability** related:
- - `Advisory`, `AdvisoryRepository`
- - AffectedSingleVersion, AffectedVersionRange, AffectedVersionRepository
- - Analysis
- - Credits
- - Rating, RatingRepository
- - Reference, ReferenceRepository
- - Source
- - Vulnerability, VulnerabilityRepository
-
-* **Utilities** for the following use cases:
- * Generate valid random SerialNumbers for Bom.serialNumber.
-
-* **Factories** for the following use cases:
- * Create data models from any license descriptor string.
- * Create PackageURL from Component data models.
- * Specific to _Node.js_: create data models from PackageJson-like data structures and derived data.
-
-* **Builders** for the following use cases:
- * Specific to _Node.js_: create deep data models Tool or Component from PackageJson-like data structures.
-
-* **Implementation of the [_CycloneDX_ Specification][CycloneDX-spec]** for the following versions:
- * `1.6`
- * `1.5`
- * `1.4`
- * `1.3`
- * `1.2`
-
-* **Normalizers** that convert data models to JSON structures.
-
-* **Normalizers** that convert data models to XML structures.
-
-* **Universal serializer** that converts Bom data models to JSON string.
-
-* **Specific Serializer** that converts Bom data models to XML string:
- - Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers.
- - Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below.
-
-* **Formal validators** for JSON string and XML string (currently for _Node.js_ only).
- Requires [optional dependencies](#optional-dependencies) as described below.
+* Vulnerability Models:
+ * `Advisory`, `AdvisoryRepository`
+ * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
+ * `Analysis`
+ * `Credits`
+ * `Rating`, `RatingRepository`
+ * `Reference`, `ReferenceRepository`
+ * `Source`
+ * `Vulnerability`, `VulnerabilityRepository`
+
+### Utilities
+* SerialNumber generation for `Bom.serialNumber`
+* License descriptor string parsing
+* PackageURL generation from Component models
+* Node.js-specific utilities for PackageJson handling
+
+### CycloneDX Specification Support
+* Version 1.6
+* Version 1.5
+* Version 1.4
+* Version 1.3
+* Version 1.2
## Installation
-This package and the build results are available for _npm_, _pnpm_, and _yarn_:
+This package and the build results are available for _npm_, _pnpm_ and _yarn_:
```shell
npm i -S @cyclonedx/cyclonedx-library
pnpm add @cyclonedx/cyclonedx-library
yarn add @cyclonedx/cyclonedx-library
+```
+
+You can install the package from source,
+which will build automatically on installation:
+
+```shell
+npm i -S github:CycloneDX/cyclonedx-javascript-library
+pnpm add github:CycloneDX/cyclonedx-javascript-library
+yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2
+```
+
+## Optional Dependencies
+
+Some dependencies are optional.
+See the shipped `package.json` for version constraints.
+
+* Serialization to XML on _Node.js_ requires any of:
+ * [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2)
+* Validation of JSON on _Node.js_ requires all of:
+ * [`ajv`](https://www.npmjs.com/package/ajv)
+ * [`ajv-formats`](https://www.npmjs.com/package/ajv-formats)
+ * [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019)
+* Validation of XML on _Node.js_ requires all of:
+ * [`libxmljs2`](https://www.npmjs.com/package/libxmljs2)
+ * the system might need to meet the requirements for [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation), in certain cases.
+
+## Usage
+
+See extended [examples].
+
+### As _Node.js_ package
+
+```javascript
+const CDX = require('@cyclonedx/cyclonedx-library')
+
+const bom = new CDX.Models.Bom()
+bom.metadata.component = new CDX.Models.Component(
+ CDX.Enums.ComponentType.Application,
+ 'MyProject'
+)
+const componentA = new CDX.Models.Component(
+ CDX.Enums.ComponentType.Library,
+ 'myComponentA',
+)
+bom.components.add(componentA)
+bom.metadata.component.dependencies.add(componentA.bomRef)
+```
+
+### In _WebBrowsers_
+
+```html
+
+
+```
+
+## API documentation
+
+We ship annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream.
+
+There are also pre-rendered documentations hosted on [readthedocs][link_rtfd].
+
+## Development & Contributing
+
+Feel free to open issues, bug reports or pull requests.
+See the [CONTRIBUTING][contributing_file] file for details.
+
+## License
+
+Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
+See the [LICENSE][license_file] file for the full license.
+
+[CycloneDX-spec]: https://github.com/CycloneDX/specification/#readme
+
+[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE
+[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md
+[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md
+[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io
+
+[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-library/latest?label=npm&logo=npm&logoColor=white "npm"
+[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs&logoColor=white "Read the Docs"
+[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests"
+[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy&logoColor=white "test coverage"
+[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7883?label=OpenSSF%20best%20practices "OpenSSF best practices"
+[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-javascript-library?logo=open%20source%20initiative&logoColor=white "license"
+[shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage"
+[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join"
+[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion"
+[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow"
+
+[link_website]: https://cyclonedx.org/
+[link_npm]: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library
+
+[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain
+[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard
+[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883
+[link_slack]: https://cyclonedx.org/slack/invite
+[link_discussion]: https://groups.io/g/CycloneDX
+[link_twitter]: https://twitter.com/CycloneDX_Spec