Merge pull request #121 from CycloneDX/v1.4-dev

v1.4 General Availability
CycloneDX · Jan 12, 2022 · ccbf7b5 · ccbf7b5
2 parents efe5b9d + ec99395
commit ccbf7b5
Show file tree

Hide file tree

Showing 167 changed files with 11,160 additions and 43 deletions.
diff --git a/.github/workflows/cibuild.yml b/.github/workflows/cibuild.yml
@@ -0,0 +1,47 @@
+name: CI Build
+
+on: [push, pull_request]
+
+env:
+  PYTHON_VERISON_DEFAULT: "3.10"
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up JDK 1.8
+      uses: actions/setup-java@v1
+      with:
+        java-version: 1.8
+    - name: Build with Maven
+      run: |
+        cd tools
+        mvn -B package --file pom.xml
+        cd ..
+    - name: Setup Python Environment
+      # see https://github.com/actions/setup-python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ env.PYTHON_VERISON_DEFAULT }}
+        architecture: 'x64'
+    - name: Generate JSON Schema documentation
+      run: |
+        cd docgen/json
+        ./gen.sh
+    - name: Generate XML Schema documentation
+      run: |
+        cd docgen/xml
+        ./gen.sh
+    - name: Archive JSON Schema documentation
+      uses: actions/upload-artifact@v2
+      with:
+        name: JSON-Schema-documentation
+        path: docgen/json/docs
+    - name: Archive XML Schema documentation
+      uses: actions/upload-artifact@v2
+      with:
+        name: XML-Schema-documentation
+        path: docgen/xml/docs
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
diff --git a/docgen/json/gen.sh b/docgen/json/gen.sh
@@ -0,0 +1,29 @@
+#!/bin/bash
+rm -f -R docs
+mkdir -p docs/{1.2,1.3,1.4}
+
+# Check to see if generate-schema-doc is executable and is in the path. If not, install JSON Schema for Humans.
+if ! [ -x "$(command -v generate-schema-doc)" ]; then
+  pip3 install json-schema-for-humans==0.39.5
+fi
+
+generate () {
+  version=$1
+  title='CycloneDX v'$version' JSON Reference'
+  echo Generating $title
+  STRICT_SCHEMA_FILE='../../schema/bom-'$version'-strict.schema.json'
+  if [ -f "$STRICT_SCHEMA_FILE" ]; then
+      SCHEMA_FILE='../../schema/bom-'$version'-strict.schema.json'
+  else
+      SCHEMA_FILE='../../schema/bom-'$version'.schema.json'
+  fi
+  echo $SCHEMA_FILE
+  generate-schema-doc --config no_link_to_reused_ref --config no_show_breadcrumbs --config no_collapse_long_descriptions --config deprecated_from_description --config title="$title" --config custom_template_path=$(pwd)'/templates/cyclonedx/base.html' --minify $SCHEMA_FILE 'docs/'$version'/index.html'
+  sed -i -e "s/\${quotedTitle}/\"$title\"/g" 'docs/'$version'/index.html'
+  sed -i -e "s/\${title}/$title/g" 'docs/'$version'/index.html'
+  sed -i -e "s/\${version}/$version/g" 'docs/'$version'/index.html'
+}
+
+generate 1.2
+generate 1.3
+generate 1.4
diff --git a/docgen/json/templates/cyclonedx/badge_type.html b/docgen/json/templates/cyclonedx/badge_type.html
@@ -0,0 +1,14 @@
+{%- if type_name == "string" -%}
+    {%- if schema.kw_min_length -%}
+        {{ restriction("Must be at least <code>" ~ schema.kw_min_length.literal ~ "</code> characters long", "min-length", schema.kw_min_length.html_id) }}
+    {%- endif -%}
+    {%- if schema.kw_max_length -%}
+        {{ restriction("Must be at most <code>" ~ schema.kw_max_length.literal ~ "</code> characters long", "max-length", schema.kw_max_length.html_id) }}
+    {%- endif -%}
+{%- endif -%}
+{%- if type_name in ["integer", "number"] -%}
+    {%- set restriction_text = (schema | get_numeric_restrictions_text("<code>", "</code>")) -%}
+    {%- if restriction_text -%}
+        {{ restriction(schema | get_numeric_restrictions_text("<code>", "</code>"), "numeric", schema.html_id ~ "_number") }}
+    {%- endif -%}
+{%- endif -%}
diff --git a/docgen/json/templates/cyclonedx/base.html b/docgen/json/templates/cyclonedx/base.html
@@ -0,0 +1,85 @@
+{% from 'content.html' import content with context %}
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>${title}</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+    <meta charset="UTF-8"/>
+    <meta name="twitter:card" content="summary_large_image"/>
+    <meta name="twitter:site" content="@CycloneDX_Spec"/>
+    <meta name="twitter:title" content="${quotedTitle}"/>
+    <meta name="twitter:image" content="https://cyclonedx.org/theme/assets/images/CycloneDX-Twitter-Card.png"/>
+    <meta name="twitter:description" content="${quotedTitle}"/>
+    <meta name="description" content="${quotedTitle}"/>
+    <meta property="og:description" content="${quotedTitle}"/>
+    <meta property="og:title" content="${quotedTitle}"/>
+    <meta property="og:locale" content="en_US"/>
+    <meta property="og:type" content="website" />
+    <meta property="og:image" content="https://cyclonedx.org/theme/assets/images/CycloneDX-Twitter-Card.png" />
+    <link rel="icon" href="https://cyclonedx.org/cyclonedx-icon.png" type="image/png"/>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.0/css/bootstrap.min.css" integrity="sha512-P5MgMn1jBN01asBgU0z60Qk4QxiXo86+wlFahKrsQf37c9cro517WzVSPPV1tDKzhku2iJ2FVgL67wG03SGnNA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" integrity="sha512-SfTiTlX6kk+qitfevl/7LibUOeJWlt9rbyDn92a1DqWOw9vWG2MFoays0sgObmWazO5BQPiFucnnEAjpAB+/Sw==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+    <link rel="stylesheet" type="text/css" href="schema_doc.css">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.slim.js" integrity="sha512-HNbo1d4BaJjXh+/e6q4enTyezg5wiXvY3p/9Vzb20NIvkJghZxhzaXeffbdJuuZSxFhJP87ORPadwmU9aN3wSA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.0/js/bootstrap.min.js" integrity="sha512-XKa9Hemdy1Ui3KSGgJdgMyYlUg1gM+QhL6cnlyTe2qzMCYm4nAZ1PsVerQzTTXzonUR+dmswHqgJPuwCq1MaAg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/markdown-it/12.2.0/markdown-it.min.js" integrity="sha512-cTQeM/op796Fp1ZUxfech8gSMLT/HvrXMkRGdGZGQnbwuq/obG0UtcL04eByVa99qJik7WlnlQOr5/Fw5B36aw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <script src="schema_doc.min.js"></script>
+</head>
+<body class="blue" data-spy="scroll" data-target=".js-scrollspy" onload="anchorOnLoad();" id="root">
+
+<nav class="navbar fixed-top navbar-expand-sm navbar-inverse">
+    <a href="https://cyclonedx.org" class="navbar-brand site-header__logo"><img src="https://cyclonedx.org/theme/assets/images/layout/logo-white.svg" width="150"></img></a>
+    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+    </button>
+    <div class="collapse navbar-collapse" id="navbarScroll">
+        <ul class="navbar-nav mr-auto my-2 my-lg-0 navbar-nav-scroll" style="max-height: 100px;">
+            <li class="nav-item dropdown">
+                <a class="nav-link dropdown-toggle" href="#" id="navbarScrollingDropdown" role="button" data-toggle="dropdown" aria-expanded="false">
+                    v${version} (JSON)
+                </a>
+                <ul class="dropdown-menu" aria-labelledby="navbarScrollingDropdown">
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.4/json/">v1.4 (JSON)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.3/json/">v1.3 (JSON)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.2/json/">v1.2 (JSON)</a></li>
+                    <li><hr class="dropdown-divider"/></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.4/xml/">v1.4 (XML)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.3/xml/">v1.3 (XML)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.2/xml/">v1.2 (XML)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.1/xml/">v1.1 (XML)</a></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.0/xml/">v1.0 (XML)</a></li>
+                </ul>
+            </li>
+        </ul>
+    </div>
+</nav>
+
+
+<div class="container-fluid" style="margin-top:70px; margin-bottom:3rem">
+    <h1>${title}</h1>
+
+    {%- if title -%}
+        <h1>{{ title }}</h1>
+    {%- endif -%}
+    {%- if config.expand_buttons -%}
+        <div class="text-right">
+            <button class="btn btn-primary" type="button" data-toggle="collapse" data-target=".collapse:not(.show)" aria-expanded="false">Expand all</button>
+            <button class="btn btn-primary" type="button" data-toggle="collapse" data-target=".collapse.show" aria-expanded="false">Collapse all</button>
+        </div>
+    {%- endif -%}
+
+    {{ content(schema) }}
+
+<footer class="site-footer__copyright fixed-bottom">
+    <div class="container">
+        <div class="row">
+            <div class="col-sm-12">
+                &copy; OWASP Foundation - CycloneDX is a <a href="https://owasp.org/cyclonedx">OWASP Flagship Project</a>
+            </div>
+        </div>
+    </div>
+</footer>
+
+</body>
+</html>
diff --git a/docgen/json/templates/cyclonedx/breadcrumbs.html b/docgen/json/templates/cyclonedx/breadcrumbs.html
@@ -0,0 +1,17 @@
+<div class="breadcrumbs">
+{%- for node in schema.nodes_from_root -%}
+    {%- if loop.first -%}
+        root
+    {%- else -%}
+        <a href="#{{ node.html_id }}" onclick="anchorLink('{{ node.html_id }}')">{{ node.name_for_breadcrumbs }}</a>
+    {%- endif -%}
+    {%- if not loop.last %}
+        <svg width="1em" height="1em" viewBox="0 0 16 16" class="bi bi-arrow-right-short" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+            <path
+                fill-rule="evenodd"
+                d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"
+            />
+        </svg>
+    {% endif -%}
+{%- endfor -%}
+</div>
diff --git a/docgen/json/templates/cyclonedx/content.html b/docgen/json/templates/cyclonedx/content.html
@@ -0,0 +1,116 @@
+{% from "macro_restriction.html" import restriction with context %}
+
+{%- macro tabbed_section(operator, current_node) -%}
+    {% include "tabbed_section.html" %}
+{%- endmacro -%}
+
+{%- macro content(schema, skip_headers=False) -%}
+    {% set keys = schema.keywords %}
+
+    {# Resolve type #}
+    {%- set type_name = schema.type_name -%}
+
+    {% if not skip_headers %}
+        {%- if config.show_breadcrumbs -%}
+            {%- include "breadcrumbs.html" -%}
+        {%- endif -%}
+
+        {# Display type #}
+        {%- if not schema is combining -%}
+            <span class="badge value-type">Type: {{ type_name }}</span>
+        {%- endif -%}
+
+        {# Display default #}
+        {%- set default_value = schema.default_value -%}
+        {%- if default_value -%}
+            {{ " " }}<span class="badge default-value">Default: {{ default_value }}</span>
+        {%- endif -%}
+        <br/>
+
+        {%- set description = (schema | get_description) -%}
+        {%- include "section_description.html" -%}
+    {%- endif -%}
+
+
+    {%- if schema.should_be_a_link(config) -%}
+        <a href="#{{ schema.links_to.html_id }}" onclick="anchorLink('{{ schema.links_to.html_id }}')" class="ref-link">Same definition as {{ schema.links_to.link_name }}</a>
+    {%- elif schema.refers_to -%}
+        {{ content(schema.refers_to_merged, True) }}
+    {%- else -%}
+        {# Handle having oneOf or allOf with only one condition #}
+        {%- if schema.kw_all_of and (schema.kw_all_of.array_items | length) == 1 -%}
+            {{ content(schema.kw_all_of.array_items[0]) }}
+        {%- elif schema.kw_any_of and (schema.kw_any_of.array_items | length) == 1 -%}
+            {{ content(schema.kw_any_of.array_items[0]) }}
+        {%- else -%}
+            {%- if schema.explicit_no_additional_properties -%}
+                {{ " " }}<span class="badge no-additional">No Additional Properties</span>
+            {%- endif -%}
+
+            {# Combining: allOf, anyOf, oneOf, not #}
+            {%- if schema.kw_all_of -%}
+                <div class="all-of-value" id="{{ schema.kw_all_of.html_id }}">{{ tabbed_section("allOf", schema.kw_all_of) }}</div>
+            {%- endif -%}
+            {%- if schema.kw_any_of -%}
+                <div class="any-of-value" id="{{ schema.kw_any_of.html_id }}">{{ tabbed_section("anyOf", schema.kw_any_of) }}</div>
+            {%- endif -%}
+            {%- if schema.kw_one_of -%}
+                <div class="one-of-value" id="{{ schema.kw_one_of.html_id }}">{{ tabbed_section("oneOf", schema.kw_one_of) }}</div>
+            {%- endif -%}
+            {%- if schema.kw_not -%}
+                {% include "section_not.html" %}
+            {%- endif -%}
+
+            {# Enum and const #}
+            {%- if schema.kw_enum -%}
+                <div class="enum-value" id="{{ schema.kw_enum.html_id }}">
+                <h4>Must be one of:</h4>
+                <ul class="list-group">
+                {%- for enum_choice in schema.kw_enum.array_items -%}
+                    <li class="list-group-item enum-item">{{ enum_choice.literal | python_to_json }}</li>
+                {%- endfor -%}
+                </ul>
+                </div>
+            {%- endif -%}
+            {%- if schema.kw_const -%}
+                <span class="const-value" id="{{ schema.kw_const.html_id }}">Specific value: <code>{{ schema.kw_const.raw | python_to_json }}</code></span>
+            {%- endif -%}
+
+            {# Pattern (Regular Expression) #}
+            {%- if schema.kw_pattern -%}
+                <span class="pattern-value" id="{{ schema.kw_pattern.html_id }}">Must match regular expression: <code>{{ schema.kw_pattern.literal | escape }}</code></span>
+            {%- endif -%}
+
+            {# Conditional subschema, or if-then-else section #}
+            {%- if schema.has_conditional -%}
+                {% include "section_conditional_subschema.html" %}
+            {%- endif -%}
+
+            {# Required properties that are not defined under "properties". They will only be listed #}
+            {% include "section_undocumented_required_properties.html" %}
+
+            {# Show the requested type(s) #}
+            {% include "badge_type.html" %}
+
+            {# Show array restrictions #}
+            {%- if type_name.startswith("array") -%}
+                {% include "section_array.html" %}
+            {%- endif -%}
+
+            {# Display examples #}
+            {%- set examples = schema.examples -%}
+            {%- if examples -%}
+                {% include "section_examples.html" %}
+            {%- endif -%}
+
+            {# Properties, pattern properties, additional properties #}
+            {%- for sub_property in schema.iterate_properties -%}
+                {# Custom modification to remove $ properties from documentation #}
+                {%- if not sub_property.property_display_name.startswith("$") -%}
+                    {% include "section_properties.html" %}
+                {%- endif -%}
+            {%- endfor -%}
+
+        {%- endif -%}
+    {%- endif -%}
+{%- endmacro -%}
diff --git a/docgen/json/templates/cyclonedx/macro_restriction.html b/docgen/json/templates/cyclonedx/macro_restriction.html
@@ -0,0 +1,3 @@
+{%- macro restriction(inner_text, css_class_name, html_id) -%}
+    <p><span class="badge badge-light restriction {{ css_class_name }}-restriction" id="{{ html_id }}">{{ inner_text }}</span></p>
+{%- endmacro -%}