CycloneDX’s JavaScript Library documentation

OWASP CycloneDX is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.

This JavaScript library provides data models, validators and more, to help you create/render CycloneDX documents.

Install

This package and the build results are available for npm, pnpm and yarn:

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:

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
Validation of JSON on _Node.js_ requires all of:
Validation of XML on _Node.js_ requires all of:
- libxmljs2
- the system must meet the requirements for node-gyp

Examples

For Node

JavaScript

JavaScript as CommonJS

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

const CDX = require('@cyclonedx/cyclonedx-library')
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)
const jsonValidator = new CDX.Validation.JsonStrictValidator(serializeSpec.version)
jsonValidator.validate(serializedJson)
  .then(validationErrors => {
    if (validationErrors === null) {
      console.info('JSON valid')
    } else {
      throw new Error('JSON ValidationError:\n' + JSON.stringify(validationErrors))
    }
  })
  .catch(err => {
    if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
      console.info('JSON validation skipped:', err)
    } else {
      throw err
    }
  })

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)
const xmlValidator = new CDX.Validation.XmlValidator(serializeSpec.version)
xmlValidator.validate(serializedXML)
  .then(validationErrors => {
    if (validationErrors === null) {
      console.info('XML valid')
    } else {
      throw new Error('XML ValidationError:\n' + JSON.stringify(validationErrors))
    }
  })
  .catch(err => {
    if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
      console.info('XML validation skipped:', err)
    } else {
      throw err
    }
  })

JavaScript as ECMAScript module

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

import * as CDX from '@cyclonedx/cyclonedx-library'
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)
const jsonValidator = new CDX.Validation.JsonStrictValidator(serializeSpec.version)
try {
  const validationErrors = await jsonValidator.validate(serializedJson)
  if (validationErrors === null) {
    console.info('JSON valid')
  } else {
    throw new Error('JSON ValidationError:\n' + JSON.stringify(validationErrors))
  }
} catch (err) {
  if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
    console.info('JSON validation skipped:', err)
  } else {
    throw err
  }
}

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)
const xmlValidator = new CDX.Validation.XmlValidator(serializeSpec.version)
try {
  const validationErrors = await xmlValidator.validate(serializedXML)
  if (validationErrors === null) {
    console.info('XML valid')
  } else {
    throw new Error('XML ValidationError:\n' + JSON.stringify(validationErrors))
  }
} catch (err) {
  if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
    console.info('XML validation skipped:', err)
  } else {
    throw err
  }
}

TypeScript

TypeScript for CommonJS

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

import * as CDX from '@cyclonedx/cyclonedx-library'
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)
const jsonValidator = new CDX.Validation.JsonStrictValidator(serializeSpec.version)
jsonValidator.validate(serializedJson)
  .then(validationErrors => {
    if (validationErrors === null) {
      console.info('JSON valid')
    } else {
      throw new Error('JSON ValidationError:\n' + JSON.stringify(validationErrors))
    }
  })
  .catch(err => {
    if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
      console.info('JSON validation skipped:', err)
    } else {
      throw err
    }
  })

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)
const xmlValidator = new CDX.Validation.XmlValidator(serializeSpec.version)
xmlValidator.validate(serializedXML)
  .then(validationErrors => {
    if (validationErrors === null) {
      console.info('XML valid')
    } else {
      throw new Error('XML ValidationError:\n' + JSON.stringify(validationErrors))
    }
  })
  .catch(err => {
    if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
      console.info('XML validation skipped:', err)
    } else {
      throw err
    }
  })

TypeScript for ECMAScript module

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

import * as CDX from '@cyclonedx/cyclonedx-library'
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)
const jsonValidator = new CDX.Validation.JsonStrictValidator(serializeSpec.version)
try {
  const validationErrors = await jsonValidator.validate(serializedJson)
  if (validationErrors === null) {
    console.info('JSON valid')
  } else {
    throw new Error('JSON ValidationError:\n' + JSON.stringify(validationErrors))
  }
} catch (err) {
  if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
    console.info('JSON validation skipped:', err)
  } else {
    throw err
  }
}

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)
const xmlValidator = new CDX.Validation.XmlValidator(serializeSpec.version)
try {
  const validationErrors = await xmlValidator.validate(serializedXML)
  if (validationErrors === null) {
    console.info('XML valid')
  } else {
    throw new Error('XML ValidationError:\n' + JSON.stringify(validationErrors))
  }
} catch (err) {
  if (err instanceof CDX.Validation.MissingOptionalDependencyError) {
    console.info('XML validation skipped:', err)
  } else {
    throw err
  }
}

For Web

With Parcel

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

const CDX = require('@cyclonedx/cyclonedx-library')
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)

With webpack

/*!
This file is part of CycloneDX JavaScript Library.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
Copyright (c) OWASP Foundation. All Rights Reserved.
*/

/** Example how to serialize a Bom to JSON / XML. */

const CDX = require('@cyclonedx/cyclonedx-library')
// full Library is available as `CDX`, now

const lFac = new CDX.Factories.LicenseFactory()
const purlFac = new CDX.Factories.PackageUrlFactory('generic')

const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
  CDX.Enums.ComponentType.Application,
  'MyProject'
)
bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))

const componentA = new CDX.Models.Component(
  CDX.Enums.ComponentType.Library,
  'myComponentA',
  {
    group: 'acme',
    version: '1.33.7'
  }
)
componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
componentA.purl = purlFac.makeFromComponent(componentA)

bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)

const serializeSpec = CDX.Spec.Spec1dot6

const jsonSerializer = new CDX.Serialize.JsonSerializer(
  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
const serializedJson = jsonSerializer.serialize(bom)
console.log(serializedJson)

const xmlSerializer = new CDX.Serialize.XmlSerializer(
  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
const serializedXML = xmlSerializer.serialize(bom)
console.log(serializedXML)

API Reference

For Node

See the rendered TypeDoc for Node

For Web

See the rendered TypeDoc for Web

Contributing

Pull requests are welcome. But please read the CycloneDX contributing guidelines first.

Be aware: even though this project supports node>=14 on runtime, it requires node>=18 on dev-time.

Set up the project

Install dependencies:

npm install

The setup will also build the project.

Build from source

Build the JavaScript:

npm run build

Test the build result

Run the tests:

npm test

See the dedicated test docs for details and advanced instructions.

Coding standards

Apply coding standards via:

npm run cs-fix

Sign off your commits

Please sign off your commits, to show that you agree to publish your changes under the current terms and licenses of the project , and to indicate agreement with Developer Certificate of Origin (DCO).

git commit --signed-off ...

Changelog

All notable changes to this project will be documented in this file.

unreleased

6.7.2 – 2024-05-07

Changed
- The provided XML validation capabilities were explicitly hardened (via #1064; concerns #1061)
  This is considered a security measure concerning XML external entity (XXE) injection.

6.7.1 – 2024-05-07

Reverted v6.7.0, back to v6.6.1
Reason: https://github.com/CycloneDX/cyclonedx-javascript-library/security/advisories/GHSA-38gf-rh2w-gmj7

6.7.0 – 2024-05-07

!! THIS VERSION GOT YANKED !!
Reason: https://github.com/CycloneDX/cyclonedx-javascript-library/security/advisories/GHSA-38gf-rh2w-gmj7

Changed
- The provided XML validation capabilities no longer supports external entities (via #1063; concerns #1061)
  This is considered a security measure to prevent XML external entity (XXE) injection.

6.6.1 – 2024-05-06

Fixed
- JSON validator allow arbitrary $schema (#1059 via #1060)

6.6.0 – 2024-04-26

Changed
- Serializers and License-Normalizers will take license acknowledgement into account (#1051 via #1052)
Added
- Namespace Enums
  - New enum LicenseAcknowledgement (#1051 via #1052)
- Namespace Models
  - Class LicenseExpression got new property acknowledgement (#1051 via #1052)
  - Class NamedLicense got new property acknowledgement (#1051 via #1052)
  - Class SpdxLicense got new property acknowledgement (#1051 via #1052)

6.5.1 – 2024-04-16

Dependencies
- Bumped the range of optional requirement ajv-formats to ^3.0.1, was ^2.1.1 (via #1037)
  This should fix JSON-validation for time/date.

6.5.0 – 2024-04-11

Added support for *CycloneDX* Specification-1.6.

Changed
- Normalizers support CycloneDX Specification-1.6 (#1039 via #1041)
- Validators support CycloneDX Specification-1.6 (#1039 via #1041)
Added
- Existing Enums got new members and values for CycloneDX Specification-1.6 (#1039 via #1041)
  - Enums.ComponentType.CryptographicAsset
  - Enums.ExternalReferenceType.SourceDistribution
  - Enums.ExternalReferenceType.ElectronicSignature
  - Enums.ExternalReferenceType.DigitalSignature
  - Enums.ExternalReferenceType.RFC9116
- Namespace Spec was enhanced for CycloneDX Specification-1.6 (#1039 via #1041)
  - New const Spec.Spec1dot6
  - New enum member Spec.Version.v1dot6
Build
- Use TypeScript v5.4.5 now, was v5.4.3 (via #1040)

6.4.2 – 2024-03-21

Build
- Use TypeScript v5.4.3 now, was v5.4.2 (via #1030)
- Use webpack v5.91.0 now, was v5.90.3 (via #1031)

6.4.1 – 2024-03-18

Documentation
- Rendered (API) docs are hosted on readthedocs (#1027 via #1028)
Build
- Use TypeScript v5.4.2 now, was v5.3.3 (via #1021)

6.4.0 – 2024-02-26

Added
- Class Models.Metadata got a new property licenses (#1019 via #1020)
- Class Models.Metadata got a new property properties (#1019 via #1020)

6.3.2 – 2024-02-25

Refactor
- Removed dynamic imports in Node.js-specific XML serializer lookup (#1017 via #1018)
  This should improve compatibility with linkers and bundlers.
Build
- Use webpack v5.90.3 now, was v5.89.0 (via #1008, #1013, #1015)

6.3.1 – 2023-12-11

Maintenance release

6.3.0 – 2023-12-11

Dependencies
- Widened optional dependency libxmljs2@^0.31||^0.32||^0.33, was @^0.31||^0.32 (via #1001)

6.2.0 – 2023-12-11

Changed
- Serialization/normalization guarantees valid URI values (#992 via #996)

6.1.3 – 2023-12-09

Fixed
- Possible bug in XML serialization of undefined children (via #1000)
Build
- Use TypeScript v5.3.3 now, was v5.3.2 (via #999)

6.1.2 – 2023-12-02

Maintenance release.

Misc
- Widened dependency spdx-expression-parse@^3.0.1||^4, was @^3.0.1 (via #993)
- CI/CT: test also with Node.js v21 (via #995)

6.1.1 – 2023-12-01

Maintenance release.

Style
- Apply latest code style guide (via #988, #990)
Build
- Use TypeScript v5.3.2 now, was v5.2.2 (via #990)
- Use ts-loader v9.5.1 now, was v9.5.0 (via #990)

6.1.0 – 2023-11-05

Added
- Class Models.ExternalReference got a new property hashes (#984 via #985)
- Serializers and ExternalReference-Normalizers will take Models.ExternalReference.hashes into account (#984 via #985)
Build
- Use webpack v5.89.0 now, was v5.88.2 (via #979)
- Use ts-loader v9.5.0 now, was v9.4.4 (via #977)

6.0.0 – 2023-08-26

BREAKING
- Interface Spec.Protocol was removed from public API (#957 via #958)
  This is only a breaking change if you custom-implemented this TypeScript interface downstream; internal usage is non-breaking.
  This change was necessary, so that implementing more spec-features cause no breaking changes.
Build
- Use TypeScript v5.2.2 now, was v5.1.6 (via #966)

5.0.0 – 2023-08-16

BREAKING
- Interface Spec.Protocol now defines new mandatory methods (via #946)
  This is only a breaking change if you custom-implemented this TypeScript interface downstream; internal usage is non-breaking.
Added
- New enum Enums.Lifecycle with corresponding values from CycloneDX Specification-1.5 (#937 via #946)
- New class Models.NamedLifecycle (#937 via #946)
- New class Models.LifecycleRepository (#937 via #946)
- Class Models.Metadata got a new property lifecycles (#937 via #946)
- Serializers and Metadata-Normalizers will take Models.Metadata.lifecycles into account (#937 via #946)
Build
- Use webpack v5.88.2 now, was v5.88.1 (via #933)

4.0.0 – 2023-07-05

BREAKING
- Usage of this library in web browsers might no longer work out of the box (via #880)
  It might require a bundler/packer for web; see the examples/web/.
  This is only a breaking change if you used this library in a web browser.
Fixed
- Properly exclude external packages when preparing this library for web browsers (#883 via #880)
Examples
- Adjusted and extended examples for usage in web browsers (#883 via #880)
  Removed outdated examples/web/*, added examples/web/parcel & examples/web/webpack.
- Added examples for usage of CDX.Factories.PackageUrlFactory (via #882, #886)
Build
- Use TypeScript v5.1.6 now, was v5.1.5 (via #866)
- Use webpack v5.88.1 now, was v5.88.0 (via #870)
- Apply wider rules for externals in webpack build (#883 via #880)

3.0.0 – 2023-06-28

Added support for *CycloneDX* Specification-1.5.
Added functionality regarding *CycloneDX* BOM-Link.

BREAKING
- Interface Spec.Protocol now defines new mandatory methods (via #843)
  This is only a breaking change if you custom-implemented this TypeScript interface downstream; internal usage is non-breaking.
Changed
- Normalizers support CycloneDX Specification-1.5 (#505 via #843)
- Validators support CycloneDX Specification-1.5 (#505 via #843)
- Some models’ properties were widened to support CycloneDX BOM-Link (via #856)
Added
- Existing Enums got the new members and values for CycloneDX Specification-1.5 (#505 via #843)
- Namespace Spec was enhanced for CycloneDX Specification-1.5 (#505 via #843)
- Dedicated classes and types for CycloneDX BOM-Link (via #843, #856, #857)

API changes v3 - the details

BREAKING
- Interface Spec.Protocol now defines a new mandatory method supportsVulnerabilityRatingMethod() (via #843)
  This is only a breaking change if you custom-implemented this TypeScript interface downstream; internal usage is non-breaking.
Changed
- Namespace Models
  - Method BomRef.compare() accepts every stringable now, was Models.BomRef only (via #856)
  - Class ExternalReference‘s property url also accepts BomLink now, was URL|string only (via #856)
  - Class Vulnerability.Affect‘s property ref also accepts BomLinkElement now, was BomRef only (via #856)
- Namespace Serialize.{JSON,XML}.Normalize
  - All classes support CycloneDX Specification-1.5 now (#505 via #843)
  - Methods VulnerabilityRatingNormalizer.normalize() omit unsupported values for Models.Vulnerability.Rating.method (via #843)
    This utilizes the new method Spec.Protocol.supportsVulnerabilityRatingMethod().
- Namespace Validation
  - Classes {Json,JsonStrict,Xml}Validator support CycloneDX Specification-1.5 now (#505 via #843)
Added
- Namespace Enums
  - Enum ComponentType got new members (#505 via #843)
    New: Data, DeviceDriver, MachineLearningModel, Platform
  - Enum ExternalReferenceType got new members (#505 via #843)
    New: AdversaryModel, Attestation, CertificationReport, CodifiedInfrastructure, ComponentAnalysisReport, Configuration, DistributionIntake, DynamicAnalysisReport, Evidence, ExploitabilityStatement, Formulation, Log, MaturityReport, ModelCard, POAM, PentestReport, QualityMetrics, RiskAssessment, RuntimeAnalysisReport, SecurityContact, StaticAnalysisReport, ThreatModel, VulnerabilityAssertion
  - Enum Vulnerability.RatingMethod got new members (#505 via #843)
    New: CVSSv4, SSVC
- Namespace Models
  - New classes BomLinkDocument and BomLinkDocument to represent CycloneDX BOM-Link (via #843, #856, #857)
  - New type BomLink to represent CycloneDX BOM-Link (via #843, #856)
- Namespace Spec
  - Enum Version got new member v1dot5 to reflect CycloneDX Specification-1.5 (#505 via #843)
  - Constant SpecVersionDict got new entry to reflect CycloneDX Specification-1.5 (#505 via #843)
  - New constant Spec1dot5 to reflect CycloneDX Specification-1.5 (#505 via #843)
  - Constants Spec1dot{2,3,4} got a new method supportsVulnerabilityRatingMethod() (via #843)
  - Interface Protocol has a new method supportsVulnerabilityRatingMethod() (via #843)
Misc
- Added functional and integration tests for CycloneDX Specification-1.5 (#505 via #843)
- Added unit tests for CycloneDX BOM-Link (via #843, #856)
- Fetched latest stable schema definition files for offline usage (via #843)
- Improved internal documentation (via #856)
Build
- Use TypeScript v5.1.5 now, was v5.1.3 (via #860)
- Use webpack v5.88.0 now, was v5.86.0 (via #841)

2.1.0 – 2023-06-10

Changed
- Classes Serialize.Xml.Normalize.Vulnerability*Normalizer are now public available (via #816)
  Previously, only instances were available via Serialize.Xml.Normalize.Factory.makeForVulnerability*().
Build
- Use TypeScript v5.1.3 now, was v5.0.4 (via #790)
- Use webpack v5.86.0 now, was v5.82.1 (via #802)

2.0.0 – 2023-05-17

Improved license detection.
Finished Vulnerability capabilities.
Added ComponentEvidence capabilities.

BREAKING
- Method Factories.LicenseFactory.makeFromString() was changed in its behavior (#271, #530 via #547)
  It will try to create Models.SpdxLicense if value is eligible, else try to create Models.LicenseExpression if value is eligible, else fall back to Models.NamedLicense.
- Revisited sort and compare:
  - Methods Models.*.compare() may return different numbers than before.
  - Methods Models.*.sorted() may return different orders than before.
- Removed deprecated symbols (#747 via #752)
Changed
- Removed beta state from symbols {Enums,Models}.Vulnerability.* (#164 via #722)
  The structures are defined as stable now.
- Some property/parameter types were widened, enabling the use of Buffer and other data-saving mechanisms (#406, #516 via #753)
Added
- New data models and serialization/normalization for Models.ComponentEvidence (#516 via #753)
- Serializers and Component-Normalizers will take Models.Component.evidence into account (#516 via #753)
- Serializers and Bom-Normalizers will take Models.Bom.vulnerabilities into account (#164 via #722)
Misc
- Internal rework, modernization, refactoring

API changes v2 - the details

BREAKING
- Class Factories.LicenseFactory was modified
  - Renamed method makeDisjunctiveWithId() -> makeSpdxLicense() (#530 via #547)
  - Renamed method makeDisjunctiveWithName() -> makeNamedLicense() (#530 via #547)
- Class Models.LicenseExpression was modified
  - Removed static function isEligibleExpression() (via #547)
    Use Spdx.isValidSpdxLicenseExpression() instead.
  - Constructor no longer throws, when value is not eligible (#530 via #547)
    You may use Factories.LicenseFactory.makeExpression() to mimic the previous behavior.
  - Property expression setter no longer throws, when value is not eligible (#530 via #547)
    You may use Factories.LicenseFactory.makeExpression() to mimic the previous behavior.
- Class Models.SpdxLicense was modified
  - Constructor no longer throws, when value is not eligible (#530 via #547)
    You may use Factories.LicenseFactory.makeSpdxLicense() to mimic the previous behavior.
  - Property id setter no longer throws, when value is not eligible (#530 via #547)
    You may use Factories.LicenseFactory.makeSpdxLicense() to mimic the previous behavior.
- Interface Spec.Protocol now defines a new mandatory property supportsComponentEvidence:boolean (via #753)
- Interface Spec.Protocol now defines a new mandatory property supportsVulnerabilities:boolean (via #722)
- Removed deprecated symbols (#747 via #752)
  - Namespaces {Builders,Factories}.FromPackageJson were removed.
    You may use {Builders,Factories}.FromNodePackageJson instead.
  - Class Models.HashRepository was removed.
    You may use Models.HashDictionary instead.
  - Methods Serialize.{Json,Xml}.Normalize.*.normalizeRepository() were removed.
    You may use Serialize.{Json,Xml}.Normalize.*.normalizeIterable() instead
  - Type alias Types.UrnUuid was removed.
    You may use string instead.
  - Type predicate Types.isUrnUuid() was removed.
Changed
- Class Models.Attachment was modified
  - Property content was widened to be any stringable, was string (#406, #516 via #753)
    This enables the use of Buffer and other data-saving mechanisms.
- Class Models.Component was modified
  - Property copyright was widened to be any stringable, was string (#406, #516 via #753)
    This enables the use of Buffer and other data-saving mechanisms.
- Class Models.Vulnerability.Credits was modified
  - Property organizations is no longer optional (via #722)
    This collection(Set) will always exist, but might be empty.
    This is considered a non-breaking change, as the class was in beta state.
  - Property individuals is no longer optional (via #722)
    This collection(Set) will always exist, but might be empty.
    This is considered a non-breaking change, as the class was in beta state.
Added
- Namespace Models was enhanced
  - Class Component was enhanced
    - New optional property evidence of type Models.ComponentEvidence (#516 via #753)
  - New Class ComponentEvidence (#516 via #753)
  - Namespace Vulnerability was enhanced
    - Class Advisory was enhanced
      - New method compare() (via #722)
    - Class AdvisoryRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
    - Class Affect was enhanced
      - New method compare() (via #722)
    - Class AffectRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
    - Class AffectedSingleVersion was enhanced
      - New method compare() (via #722)
    - Class AffectedVersionRange was enhanced
      - New method compare() (via #722)
    - Class AffectedVersionRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
    - Class Rating was enhanced
      - New method compare() (via #722)
    - Class RatingRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
    - class Reference was enhanced
      - New method compare() (via #722)
    - Class ReferenceRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
    - class Source was enhanced
      - New method compare() (via #722)
    - class Vulnerability was enhanced
      - New method compare() (via #722)
    - Class VulnerabilityRepository was enhanced
      - New method sorted() (via #722)
      - New method compare() (via #722)
- Namespaces Serialize.{Json,Xml}.Normalize were enhanced
  - Class Factory was enhanced
    - New Method makeForComponentEvidence() (#516 via #753)
    - New method makeForVulnerability() (#164 via #722)
    - New method makeForVulnerabilitySource() (#164 via #722)
    - New method makeForVulnerabilityReference() (#164 via #722)
    - New method makeForVulnerabilityRating (#164 via #722)
    - New method makeForVulnerabilityAdvisory (#164 via #722)
    - New method makeForVulnerabilityCredits (#164 via #722)
    - New method makeForVulnerabilityAffect (#164 via #722)
    - New method makeForVulnerabilityAffectedVersion (#164 via #722)
    - New method makeForVulnerabilityAnalysis (#164 via #722)
  - New class ComponentEvidenceNormalizer (#516 via #753)
  - Class OrganizationalEntityNormalizer was enhanced
    - New method normalizeIterable() (via #722)
  - New class VulnerabilityNormalizer (#164 via #722)
  - New class VulnerabilityAdvisoryNormalizer (#164 via #722)
  - New class VulnerabilityAffectNormalizer (#164 via #722)
  - New class VulnerabilityAffectedVersionNormalizer (#164 via #722)
  - New class VulnerabilityAnalysisNormalizer (#164 via #722)
  - New class VulnerabilityCreditsNormalizer (#164 via #722)
  - New class VulnerabilityRatingNormalizer (#164 via #722)
  - New class VulnerabilityReferenceNormalizer (#164 via #722)
  - New class VulnerabilitySourceNormalizer (#164 via #722)
- Namespace Spec
  - Constants Spec1dot{2,3,4} were enhanced
    - New property supportsComponentEvidence:boolean (via #753)
    - New property supportsVulnerabilities:boolean (via #722)
- Namespace Spdx was enhanced
  - New function isValidSpdxLicenseExpression() (#271 via #547)
Misc
- Added dependency spdx-expression-parse@^3.0.1 (via #547)

1.14.0 – 2023-04-25

Added
- Formal validators for JSON string and XML string (#620 via #652, #691)
  Currently available only for Node.js. Requires optional dependencies.
  - Related new validator classes:
    - Validation.JsonValidator
    - Validation.JsonStrictValidator
    - Validation.XmlValidator
  - Related new error classes:
    - Validation.NotImplementedError
    - Validation.MissingOptionalDependencyError
Build
- Use TypeScript v5.0.4 now, was v4.9.5 (#549 via #644)
- Use webpack v5.80.0 now, was v5.79.0 (via #686)

1.13.3 - 2023-04-05

Fixed
- Serialize.{JSON,XML}.Normalize.LicenseNormalizer.normalizeIterable() now omits invalid license combinations (#602 via #623)
  If there is any Models.LicenseExpression, then this is the only license normalized; otherwise all licenses are normalized.
Docs
- Fixed link to CycloneDX-specification in README (via #617)

1.13.2 - 2023-03-29

Fixed
- Builders.FromNodePackageJson.ComponentBuilder no longer cuts component’s name after a slash(/) (#599 via #600)

1.13.1 - 2023-03-28

Docs
- Announce and annotate the generator for BOM’s SerialNumber (#588 via #598)

1.13.0 - 2023-03-28

Fixed
- “Bom.serialNumber” data model can have values following the alternative format allowed in CycloneDX XML specification (#588 via #597)
- Serialize.{JSON,XML}.Normalize.BomNormalizer.normalize now omits invalid/unsupported values for serialNumber (#588 via #597)
Changed
- Property Models.Bom.serialNumber is of type string, was type-aliased Types.UrnUuid = string (#588 via #597)
  Also, the setter no longer throws exceptions, since no string format is illegal.
  This is considered a non-breaking behavior change, because the corresponding normalizers assure valid data results.
Added
- Published generator for BOM’s SerialNumber: Utils.BomUtility.randomSerialNumber() (#588 via #597)
  The code was donated from cyclonedx-node-npm.
Deprecation
- Type alias Types.UrnUuid = string became deprecated (via #597)
  Use type string instead.
- Function Types.isUrnUuid became deprecated (via #597)

1.12.2 - 2023-03-28

Fixed
- Digesting this library in TypeScript build with ECMA Script module results works as expected, now (via #596)
Docs
- Development-docs are no longer packed with releases (via #572)
Misc
- Added more integration tests in CI (via #596)

1.12.1 - 2023-03-13

Maintenance release.

1.12.0 - 2023-03-02

Docs
- Made it clear, that {Builders,Factories}.{FromNodePackageJson,FromPackageJson}.* functionality is to be run on already normalized structures (#517 via #518)
  Normalization should be done downstream, for example via ``normalize-package-data` <https://www.npmjs.com/package/normalize-package-data>`_.

1.11.0 - 2023-02-02

Added
- New vulnerability-related enums were added in a new namespace Enums.Vulnerability (#164 via #419)
  Release stage is “beta”. These namespace and enums have been released to third-party developers experimentally for the purpose of collecting feedback. These enums should not be used in production, because their contracts may change without notice.
  - AffectStatus
  - AnalysisJustification
  - AnalysisResponse
  - AnalysisState
  - RatingMethod
  - Severity
- New vulnerability-related models were added in a new namespace Models.Vulnerability (#164 via #419)
  Release stage is “beta”. These namespace and models have been released to third-party developers experimentally for the purpose of collecting feedback. These models should not be used in production, because their contracts may change without notice.
  Attention: The models are not yet supported by shipped serializers nor shipped normalizers.
  - Advisory, AdvisoryRepository
  - Affect, AffectRepository, AffectedSingleVersion, AffectedVersionRange, AffectedVersionRepository
  - Analysis
  - Credits
  - Rating, RatingRepository
  - Reference, ReferenceRepository
  - Source
  - Vulnerability, VulnerabilityRepository
- New class Models.OrganizationalEntityRepository to represent a collection of Models.OrganizationalEntity (via #419)
  Additionally, Models.OrganizationalEntity.compare() was implemented.
- New types and related functionality Common Weaknesses Enumerations (CWE) were added (via #419)
  Release stage is “beta”. These types, functions and classes have been released to third-party developers experimentally for the purpose of collecting feedback. These types, functions and classes should not be used in production, because their contracts may change without notice.
  - type Types.CWE
  - runtime validation Types.isCWE()
  - class Types.CweRepository
Docs
- Use TSDoc syntax in TypeScript files, instead of JSDoc (via #318, #453)
Build
- Use TypeScript v4.9.5 now, was v4.9.4 (via #463)
Misc
- Added tests for internal helpers (via #454)
- Use eslint-config-standard-with-typescript@34.0.0 now, was 33.0.0 (via #460)

1.10.0 - 2023-01-28

Added
- Typing: Interfaces of models’ optional properties are now public API (#439 via #440)
- Ship TypeDoc configuration, so that users can build the documentation on demand (#57 via #436)
Fixed
- XML serializer now properly throws UnsupportedFormatError if it is unsupported by the supplied Spec (via #438)
Misc
- Added tests for internal helpers (via #431)
- Added more internal sortable data types (via #165)
- Fixed type hints in internals (via #432)
- Fixed type refs and links in doc-strings (via #437)
- Slightly improved performance of compare methods when reproducible results were needed (via #433)
- Use eslint-config-standard-with-typescript@33.0.0 now, was 23.0.0 (via #382, #423, #445)

1.9.2 - 2022-12-16

Maintenance release.

Docs
- Fix CI/CT shield (badges/shields#8671 via #371)

1.9.1 - 2022-12-10

Maintenance release.

Build
- Use TypeScript v4.9.4 now, was v4.9.3 (via #360)

1.9.0 - 2022-11-19

Changed
- Widened the accepted types for first parameter of all normalizeIterable methods (via #317)
Build
- Use TypeScript v4.9.3 now, was v4.8.4 (via #335)

1.8.0 - 2022-10-31

Added
- Enabled detection for node-package manifest’s deprecated licenses format in the node-specific builders (#308 via #309)

1.7.0 - 2022-10-25

Changed
- Shipped TypeScript declarations are usable by TypeScript v3.8 and above now (#291 via #292) Previously the source code was abused as type declarations, so they required a certain version of TypeScript 4.

1.6.0 - 2022-09-31

Changed
- Removed synthetic default imports im TypeScript sources (via #243)
  The resulting JavaScript did not change in functionality.
  Downstream users of the TypeScript sources/definitions might consider this a feature, as they are no longer required to compile with allowSyntheticDefaultImports enabled.
Added
- Documentation and example regarding dependency tree modelling were added in multiple places (via #250)
Build
- No longer enable TypeScript config esModuleInterop & allowSyntheticDefaultImports (via #243)
- Use TypeScript v4.8.4 now, was v4.8.3 (via #246)

1.5.1 - 2022-09-17

Deprecated
- The normalizer methods normalizeRepository will be known as normalizeIterable (via #230)

1.5.0 - 2022-09-17

Deprecated
- The class HashRepository will be known as HashDictionary (via #229)

1.4.2 - 2022-09-10

Maintenance release.

Build
- Use TypeScript v4.8.3 now, was v4.8.2 (via #212)

1.4.1 - 2022-09-09

Maintenance release.

Misc
- Style: imports are sorted, now (via #208)
Dependencies
- Widened the range of requirement packageurl-js to >=0.0.6 <0.0.8 || ^1, was >=0.0.6 <0.0.8 (via #210)

1.4.0 - 2022-09-07

Added
- New class Factories.FromNodePackageJson.PackageUrlFactory that acts like Factories.PackageUrlFactory, but omits PackageUrl’s npm-specific “default derived” qualifier values for download_url & vcs_url (#204 via #207)
Build
- Use TypeScript v4.8.2 now, was v4.7.4 (via #190)

1.3.4 - 2022-08-16

Fixed
- Factories.PackageUrlFactory omits empty-string URLs for PackageUrl’s qualifiers download_url & vcs_url (via #180)

1.3.3 - 2022-08-16

Fixed
- Improved omission of invalid anyURI when it comes to XML-normalization (#178 via #179)

1.3.2 - 2022-08-15

Fixed
- Serializers render bom-ref values of nested components as unique values, as expected (#175 via #176)
Misc
- Style: improved readability of constructor parameter types (via #166)

1.3.1 - 2022-08-04

Fixed
- JSON- and XML-Normalizer no longer render Models.Component.properties with *CycloneDX* Specification-1.2 (#152 via #153)
- XML-Normalizer now has the correct order/position of rendered Models.Component.properties (via #153)

1.3.0 - 2022-08-03

Changed
- Use version 9b04a94 of CycloneDX specification for XML and JSON schema validation (via #150)
- Use SPDX license enumeration from version 9b04a94 of CycloneDX specification. (via #150)
Added
- Models for Property and PropertyRepository (via #151)
- JSON- and XML-Normalizer for Models.Property, Models.PropertyRepository (via #151)
- New property Models.Component.properties (via #151)
Build
- Use webpack v5.74.0. now, was v5.73.0 (via #141)

1.2.0 - 2022-08-01

Added
- New getters/properties that represent the corresponding parameters of class constructor (via #145)
  - Builders.FromPackageJson.ComponentBuilder.extRefFactory,
    Builders.FromPackageJson.ComponentBuilder.licenseFactory
  - Builders.FromPackageJson.ToolBuilder.extRefFactory
  - Factories.PackageUrlFactory.type
  - Serialize.BomRefDiscriminator.prefix
  - Serialize.JsonSerializer.normalizerFactory
  - Serialize.XmlBaseSerializer.normalizerFactory,
    Serialize.XmlSerializer.normalizerFactory
- Factory for PackageURL from Models.Component can handle additional data sources, now (via #146)
  - Models.Component.hashes map -> PackageURL.qualifiers.checksum list
  - Models.Component.externalReferences[distribution].url -> PackageURL.qualifiers.download_url
  - Method Factories.PackageUrlFactory.makeFromComponent() got a new optional parameter sort, to indicate whether to go the extra mile and bring hashes and qualifiers in alphabetical order.
    This feature switch is related to reproducible builds.
Deprecated
- The sub-namespace FromPackageJson will be known as FromNodePackageJson (via #148)
  - Factories.FromPackageJson -> Factories.FromNodePackageJson
  - Builders.FromPackageJson -> Builders.FromNodePackageJson

1.1.0 - 2022-07-29

Added
- Support for nested/bundled (sub-)components via Models.Component.components was added, including serialization/normalization of models and impact on dependency graphs rendering (#132 via #136)
- *CycloneDX* Specification-1.4 made element Models.Component.version optional. Therefore, serialization/normalization with this specification version will no longer render this element if its value is empty (via #137, #138)

1.0.3 - 2022-07-28

Fixed
- Types.isCPE() for CPE2.3 allows escaped(\) chars &"><, as expected (via #134)

1.0.2 - 2022-07-26

Maintenance release.

Dependencies
- Widened the range of requirement packageurl-js to >=0.0.6 <0.0.8, was ^0.0.7 (#130 via #131)

1.0.1 - 2022-07-23

Maintenance release.

Build
- Use TypeScript v4.7.4 now, was v4.6.4 (via #55)
Dependencies
- Raised the requirement of packageurl-js to ^0.0.7, was ^0.0.6 (via #123)

1.0.0 - 2022-06-20

Initial release.

Responsibilities
- Provide a general purpose JavaScript-implementation of *CycloneDX* 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 a JSON- and an XML-normalizer, that…
  - supports all shipped data models.
  - respects any injected *CycloneDX* Specification and generates 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.
Capabilities & Features
- Enums for the following use cases:
  - AttachmentEncoding
  - ComponentScope
  - ComponentType
  - ExternalReferenceType
  - HashAlgorithm
- Data models for the following use cases:
  - Attachment
  - Bom
  - BomRef, BomRefRepository
  - Component, ComponentRepository
  - ExternalReference, ExternalReferenceRepository
  - HashContent, Hash, HashRepository
  - LicenseExpression, NamedLicense, SpdxLicense, LicenseRepository
  - Metadata
  - OrganizationalContact, OrganizationalContactRepository
  - OrganizationalEntity
  - SWID
  - Tool, ToolRepository
- Factories for the following use cases:
  - Create data models from any license descriptor string
  - Specific to Node.js: create data models from PackageJson-like data structures
- Builders for the following use cases:
  - Specific to Node.js: create deep data models from PackageJson-like data structures
- Implementation of the *CycloneDX* Specification for the following versions:
  - 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
- 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 plugs/requires/utilizes one of the following optional libraries
    - xmlbuilder2