Initial steps to enhance the presentation of the CSAF model by sthagen · Pull Request #1221 · oasis-tcs/csaf

sthagen · 2025-11-15T16:39:26Z

Please cf. with proposal "Initial steps to enhance the presentation of the CSAF model" (#1220) for examples and the rationale behind this change-set.

Material Changes

None.

Editorial Changes

Maintenance Changes

Adapt the validator to changes in sources and other processing tools

Signed-off-by: Stefan Hagen <stefan@hagen.link>

…of items (WIP) Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

…and fxed a bug Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabilities.md

Signed-off-by: Stefan Hagen <stefan@hagen.link>

- added all remaining vulnerabilities outlines - fixed the forgotten additional elements indicators between advisory instance and vulnerabilities element (as document is required and product is pulled in by vulnerabilities and the other way around - removed a few redundant ellipsis indicators when a sequence instance item is followed by the next ellipsis indicating further elements a level above - fixed the mixed occurrences of ampersand and the English 'and' favoring the latter over the fashjionable former Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

- there is some robustness to aid callers and editors already - the matching of schema snippets and outlines is quite forgiving - in case there are nultiple paths per outline the script gracefully ignores any mismatches in the first path - the identifcation of relevant leaf types is a romantic affair - the output is very verbatim as an exploratory phase is best assisted with - dependency on python-jsonpath is gently reminded when executing without install - crude use of CSAF_JSON_SCHEMA environment variable for locating the schema alike - one could use it in pipelines with grep on ERROR and expecting to not find the pattern Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

- added some sub-processing for main-type string in underyling JSON schema - added test for plain enum type Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

- works for single file, files, and globs alike - provides summary passing grade per return code of 0 (pass), 1(fail), or 2(usage error) - can now be used in actions more easily Signed-off-by: Stefan Hagen <stefan@hagen.link>

…ct-overviews

tschmidtb51 · 2026-02-25T00:50:06Z

@sthagen We don't need the files in src/outline, correct? Then, would suggest to remove them / add the folder to be ignored...

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen · 2026-02-25T03:16:31Z

@sthagen We don't need the files in src/outline, correct? Then, would suggest to remove them / add the folder to be ignored...

done. Thanks for spotting.

tschmidtb51

I like how easy it is to check that as we have all the JSON Path at hand!

I'm sorry about the delayed review.
Some minor comments - mostly editorial - no blocker for that to be merged.

PS: I did not review the rendered files as they are derived from the sources.

csaf_2.1/prose/edit/bin/lapidify.py

tschmidtb51 · 2026-02-25T10:10:49Z

csaf_2.1/prose/edit/bin/validate-outlines.py

+                if sub_type := mapping.get('format', ''):
+                    if sub_type == 'date-time':
+                        return 'string.datetime'
+                    if sub_type == 'uri':
+                        return 'string.uri'
+                if 'enum' in mapping:
+                    return 'string.enum'
+                if 'pattern' in mapping:
+                    return 'string.pattern'


In #1165, we also have string with const and string with uri and pattern. We need to consider that if we merge #1165.

String.Const I add now, not sure, how String with both URI and Pattern works here as human readable label though. That one I may have to see and would adapt when we are there (the schema has that combination).

Pending #1165 😉 😄

tschmidtb51 · 2026-02-25T10:32:20Z

csaf_2.1/prose/edit/bin/validate-outlines.py

+        except KeyError:
+            pass
+        try:
+            return mapping['$ref'].replace('#/$defs/', '$defs.')


Shouldn't that be $.$defs (not sure whether that is allowed) or $['$defs'] (definitely allowed) or am I missing something?

Depends on what we want to achieve. My goal was a nicely globally anchored "you are here and these are your surroundings" feature of a hiking map targeting humans on the right hand side. There I found that for example number: $defs.version_t is more clear than number: $['defs'].version_t (sigil noise) or the "stuttering" number: $.$defs.version_t. The $defs hints at the local definitions nature, and the .version_t exposes the type.

Not sure what the benefit of JSON Paths in the type labels would be. Thus, I went wioth what looked most simple to scann for readers (my way of reading).

But, I have no strong opinion on that one.

If it is a valid JSON Path, we can keep it that way for now.

tschmidtb51 · 2026-02-25T10:32:54Z

csaf_2.1/prose/edit/bin/validate-outlines.py

+    if 'type' in raw_finds:
+        return {jpath.split(DOT)[-1]: raw_finds['type']}
+    if '$ref' in raw_finds:
+        return {jpath.split(DOT)[-1]: raw_finds['$ref'].replace('#/$defs/', '$defs.')}


See comment about $defs above.

Cf. #1221 (comment)

tschmidtb51 · 2026-02-25T10:35:14Z

csaf_2.1/prose/edit/bin/validate-outlines.py

+                ' does not match expected mapping type {vd}'
+            )
+            jp_status = FAIL
+    elif lt.startswith('$defs.'):


May need to be updated as well if we apply the changes above.

Sure. Cf. #1221 (comment)

csaf_2.1/prose/edit/src/schema-elements-02-props-02-document.md

csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabilities.md

tschmidtb51 · 2026-02-25T12:28:15Z

csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabilities.md

-            // ...
-          }
-        }
+```yaml <!--json-path($..vulnerabilities..metrics[*].properties)-->


I like that as it restricts the path a bit more and removes (potential) ambiguity (which does not exist yet). I wonder whether we should do that in all places applicable ...

tschmidtb51 · 2026-02-25T12:54:25Z

@sthagen I might have found a bug...

If I patch:

diff --git a/csaf_2.1/prose/edit/src/schema-elements-01-defs-10-references.md b/csaf_2.1/prose/edit/src/schema-elements-01-defs-10-references.md
index 2d293ce8..36570cca 100644
--- a/csaf_2.1/prose/edit/src/schema-elements-01-defs-10-references.md
+++ b/csaf_2.1/prose/edit/src/schema-elements-01-defs-10-references.md
@@ -2,10 +2,10 @@
 
 List of references (`references_t`) of value type `array` with `1` or more items of type Reference holds a list of Reference objects.
 
-```yaml <!--json-path($['$defs'].references_t)-->
+```yaml <!--json-path($['$defs'].product_id_t)-->
 $defs:
   # ...
-  references_t: Sequence
+  references-ee_t: Mapping
   # ...
 ```
 
@@ -19,8 +19,8 @@ $defs:
   # ...
   references:
   - # <reference-instance>:
-    category: String
-    summary: String
+    critical: String
+    summary: Sequence
     url: String.URI
   # ...
 ```

The result is still:

$ ./bin/validate-outlines.py src/schema-elements-01-defs-10-references.md 
snip(src/schema-elements-01-defs-10-references.md)[5,10]: OK
snip(src/schema-elements-01-defs-10-references.md)[17,26]: OK
file(src/schema-elements-01-defs-10-references.md): OK ..

What am I missing? I was under the impression, the tool would check the outlines and report entries that are invalid / have the wrong type according to the schema.

Edit:
Your oopsied.md from #1221 (comment) still works.
The tool does that, it might have to do with that specific file as document and vulnerabilities work.

Signed-off-by: Stefan Hagen <stefan@hagen.link>

…locks confused the section numbering validator Signed-off-by: Stefan Hagen <stefan@hagen.link>

…ons.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

…t-name.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

…up-id.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

…ups.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

…ities.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

sthagen · 2026-02-25T17:49:23Z

@tschmidtb51 there have to be bugs. Severe bugs. This tool should be a helper for us and was created along my explorations of how to create something outlinish, still valid YAML and mapping to the simplified types of the JSON Path results from the schema. I would like to clean up the tool and then we can fix enhance the tool as maintenance / tool changes. The goal was to not first inject nice outlines in YAML look everywhere and then llater explore if we can assess these, but to do this in lockstep.

Some deviations that are obviously wrong it does not detect. Some rare places where we have the upstream sources for CVSS (I think) encoded in some made up "variables" like annotations in the outlines it may never do so.

But, compared to our made up JSON skeletons we had before, I think we are in a much more verifiable position now.

Signed-off-by: Stefan Hagen <stefan@hagen.link>

…ct-overviews

sthagen · 2026-03-01T00:43:45Z

Motion set: https://groups.oasis-open.org/discussion/motion-for-the-presentation-enhancement-proposal-1221 on 2026-03-01 and seconded on 2026-03-04.
The motion will automatically carry if no objection is received per the TC list before one week has passed on 2026-03-08 02:00 UTC.

…ct-overviews

sthagen · 2026-03-09T19:52:38Z

~~TODO: We will have to adjust to some changes from the product-path change-set in the editor-revision branch.~~
Done in commit dff83ed

Initial batch of outline extractions and replacements (WIP)

70701a6

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen requested a review from tschmidtb51 November 15, 2025 16:39

sthagen self-assigned this Nov 15, 2025

sthagen added enhancement editorial mostly nits and consistency email To be sent via email to the TC tc-discussion-needed labels Nov 15, 2025

sthagen linked an issue Nov 15, 2025 that may be closed by this pull request

Initial steps to enhance the presentation of the CSAF model #1220

Closed

sthagen added 3 commits November 15, 2025 18:26

Transformed more outlines and fixed the notaion for instance inserts …

e22601a

…of items (WIP) Signed-off-by: Stefan Hagen <stefan@hagen.link>

Transformed some more outlines from vulnerabilities (WIP)

befd31a

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Added more vuln outlines, specialized strings for DateTime and Enum, …

d0484d5

…and fxed a bug Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen mentioned this pull request Nov 15, 2025

Typo in JSONescque outline #1222

Closed

sthagen added 3 commits November 15, 2025 21:45

csaf_version is a String.Enum

16384a7

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Completed product_tree outline migration

68d5915

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Specialized String.Pattern elements and added forgotten String.Enum

44edbb3

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen commented Nov 15, 2025

View reviewed changes

csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabilities.md Outdated Show resolved Hide resolved

sthagen added 3 commits November 16, 2025 11:27

Completed outline migration for document object

5da0eb8

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Completed dollar-defs outlines

d15e032

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen marked this pull request as ready for review November 16, 2025 17:20

sthagen requested review from justmurphy and santosomar November 16, 2025 17:20

sthagen added 8 commits November 23, 2025 16:44

Tagged outline fneces with json-path(s) and fixed key-mismatches

91a7728

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Fixed type error

e41c505

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Fixed type of generator.date in info models

8b93ee8

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Added some more hackish sub-type harvesting

881c840

- added some sub-processing for main-type string in underyling JSON schema - added test for plain enum type Signed-off-by: Stefan Hagen <stefan@hagen.link>

Refactored level warp and added some bogus linter joy

5dbe205

Signed-off-by: Stefan Hagen <stefan@hagen.link>

First glob capable validator

e1fb608

- works for single file, files, and globs alike - provides summary passing grade per return code of 0 (pass), 1(fail), or 2(usage error) - can now be used in actions more easily Signed-off-by: Stefan Hagen <stefan@hagen.link>

Merge branch 'editor-revision-2025-11-26' into valid-outlines-as-obje…

0ce9c35

…ct-overviews

sthagen mentioned this pull request Feb 24, 2026

Remove Notes and What is new #1316

Open

Removed outlines and added to git ignore (review feedback from tschmidt)

ab85317

Signed-off-by: Stefan Hagen <stefan@hagen.link>

tschmidtb51 approved these changes Feb 25, 2026

View reviewed changes

sthagen and others added 10 commits February 25, 2026 17:57

Added explicit slug to match the section mappings

cf4d55f

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Reverted hack from when hashes as first characters in lines of code b…

773d2e0

…locks confused the section numbering validator Signed-off-by: Stefan Hagen <stefan@hagen.link>

Update csaf_2.1/prose/edit/src/introduction-05-typographical-conventi…

c97ed5e

…ons.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/introduction-05-typographical-conventi…

f366325

…ons.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-02-props-02-document.md

296095b

Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-01-definitions.md

e802ae9

Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-01-defs-03-full-produc…

dd3286d

…t-name.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-01-defs-06-product-gro…

2e39566

…up-id.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-01-defs-07-product-gro…

0d9f594

…ups.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Update csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabil…

7c8c816

…ities.md Co-authored-by: tschmidtb51 <65305130+tschmidtb51@users.noreply.github.com>

Reviewer feedback on additional facetted string types

f390545

Signed-off-by: Stefan Hagen <stefan@hagen.link>

ndemianc approved these changes Feb 25, 2026

View reviewed changes

Merge branch 'editor-revision-2026-02-25' into valid-outlines-as-obje…

abfa1d6

…ct-overviews

sthagen added csaf 2.1 csaf 2.1 work and removed tc-discussion-needed email To be sent via email to the TC labels Mar 1, 2026

Merge branch 'editor-revision-2026-02-25' into valid-outlines-as-obje…

ea303c3

…ct-overviews

sthagen merged commit a55a380 into editor-revision-2026-02-25 Mar 9, 2026
14 checks passed

sthagen deleted the valid-outlines-as-object-overviews branch March 9, 2026 19:56

tschmidtb51 added motion_passed A motion has passed and removed motion This item has a motion pending labels Mar 11, 2026

Conversation

sthagen commented Nov 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Material Changes

Editorial Changes

Maintenance Changes

Uh oh!

Uh oh!

tschmidtb51 commented Feb 25, 2026

Uh oh!

sthagen commented Feb 25, 2026

Uh oh!

tschmidtb51 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sthagen commented Feb 25, 2026

Uh oh!

sthagen commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sthagen commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sthagen commented Nov 15, 2025 •

edited

Loading

tschmidtb51 left a comment •

edited

Loading

tschmidtb51 commented Feb 25, 2026 •

edited

Loading

sthagen commented Mar 1, 2026 •

edited

Loading

sthagen commented Mar 9, 2026 •

edited

Loading