Minimalist Selection Object #821

ahouseholder · 2025-07-15T20:47:22Z

resolves Add a minimalist selection object #820
resolves Clarify distinction between private and extension namespaces #780
resolves add ADR & clarify namespace reference doc to explain intent of non-ssvc namespaces #753
resolves Generate Decision_Point_Value_Selection.schema.json using Pydantic #735
resolves Create python dataclass corresponding to Decision_Point_Value_Selection-1-0-1.schema.json #766
resolves Should there a optional "references" section in Selection schema? #600

Selection Object

This PR adds a ssvc.selection module which contains a few pydantic dataclasses to represent a minimal version of an SSVC selection object. The MinimalSelectionList class is intended to serve as the source for a new JSON schema that replaces Decision_Point_Value_Selection_1-0-1.schema.json.

Our goal is to provide a terse object for data exchange purposes. To that end, the object does not represent fully-formed Decision Point objects, only the necessary fields to uniquely identify a specific decision point and its selected values. (A decision point is uniquely identified by its namespace, key, and version. Furthermore, within a given decision points, each value must have a unique value key. So the selection object only provides that level of detail. It's expected that in actual use, the receiver will dereference this selection object against a library of known decision point definitions.

Namespace Improvements

This PR also incorporates namespace improvements from #824

CoPilot Summary

This pull request introduces significant updates to the SSVC project, including the adoption of namespaces for SSVC objects, enhancements to schema definitions, and improvements to the codebase for better maintainability and functionality. The changes focus on enabling extensibility, improving schema validation, and refining documentation generation.

Namespace Implementation and Documentation:

Namespace Adoption for SSVC Objects: Added support for namespaces to distinguish between SSVC project objects and external objects, enabling customization and extensions. This includes registered namespaces for SSVC-maintained objects and unregistered namespaces for experimental or private use (docs/adr/0012-ssvc-namespaces.md, docs/adr/index.mdR26).
Namespace Validation: Updated _Namespaced mixin to use NamespaceString for stricter validation of namespace patterns (src/ssvc/_mixins.py, src/ssvc/_mixins.pyL73-R77).

Schema Enhancements:

Schema Version Update: Migrated the schema reference from version 1.0.1 to version 2.0.0 (data/schema/current/Decision_Point_Value_Selection.schema.json, data/schema/current/Decision_Point_Value_Selection.schema.jsonL1-R1).
New Schema Definition: Introduced a comprehensive schema for Decision_Point_Value_Selection version 2.0.0, including new fields like resources, references, and improved validation (data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json, data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.jsonR1-R226).

Codebase Improvements:

Mixin Enhancements: Added _Timestamped mixin to automatically set timestamps for SSVC objects and updated _Versioned to use VersionString for semantic version validation (src/ssvc/_mixins.py, [1] [2].
Decision Point Enhancements: Introduced an id property for DecisionPoint to provide a unified identity string (src/ssvc/decision_points/base.py, src/ssvc/decision_points/base.pyR190-R197).
Documentation Improvements: Enhanced markdown generation for decision points by including object IDs in titles and examples (src/ssvc/doc_helpers.py, [1] [2].

Documentation and Tools:

Schema Dumping Utility: Added functionality to dump the SelectionList schema to a file for easier integration and validation (src/ssvc/doctools.py, [1] [2].
Decision Record Update: Included the new decision record for namespaces in the ADR index (docs/adr/index.md, docs/adr/index.mdR26).

These changes collectively improve the extensibility, validation, and usability of the SSVC framework while providing clear documentation and tools for developers and users.

Co-Pilot Schema Comparison

Based on review of the two schemas, here are the salient changes between version 1.0.1 and 2.0.0:

Schema Structure Changes

Title added: Version 2.0.0 includes a title field: "Decision Point Value Selection List"
Schema version: Updated from referencing external schema version to inline const: "2.0.0"
Additional properties: Both versions set additionalProperties: false at the root level

Property Changes

Removed properties:
- id (vulnerability identifier) - replaced by target_ids
- role (stakeholder role)
Added properties:
- target_ids: Optional array of identifiers for items being evaluated (vulnerabilities, reports, etc.)
- resources: Array of references providing context about decision points
- references: Array of references providing context about selected values
Modified properties:
- timestamp: Simplified to direct string format instead of referencing external definition
- selections: Now uses internal Selection definition instead of external reference

Selection Object Changes

Restructured selection items: Moved from SsvcdecisionpointselectionSchema to simplified Selection object
New minimal approach: Selection objects are deliberately minimal and don't contain full decision point details
Enhanced namespace validation: Added complex regex pattern for namespace validation with support for locales and extensions
Version field: Added with default value "0.0.1" and semantic version validation
Values structure: Changed from simple string array to array of MinimalDecisionPointValue objects with key, name, and description fields

New Schema Definitions

MinimalDecisionPointValue: Minimal representation with key, name, and description
Reference: Structure for URI references with optional descriptions
Selection: Core selection object with namespace, key, version, and values

Required Fields Changes

Version 1.0.1 required: selections, id, timestamp, schemaVersion
Version 2.0.0 required: timestamp, schemaVersion, selections (removed id requirement)

also make CVSS decision point groups conform

namespace:key:version is sufficient to uniquely identify any Decision Point

…om the other key-value pairs

…b.com/CERTCC/SSVC into 820-add-a-minimalist-selection-object # Conflicts: # data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json # src/ssvc/selection.py

Copilot

Pull Request Overview

This PR introduces a new minimal SSVC selection model, aligns version strings to semantic format across CVSS groups, and adds a v2 JSON schema for selections.

Adds MinimalSelection and MinimalSelectionList Pydantic models with helper functions in src/ssvc/selection.py.
Standardizes all CVSS decision point group version fields to semantic X.Y.Z in collections.py.
Defines and references a new v2 JSON schema (Decision_Point_Value_Selection-2-0-0.schema.json) and updates the current schema pointer.

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/test/decision_points/test_cvss_helpers.py	Updated test data to use `1.0.0` instead of `1.0`.
src/ssvc/selection.py	New module defining minimal selection classes and schema generation.
src/ssvc/dp_groups/cvss/collections.py	Bumped all CVSS group versions to semantic `X.Y.Z`.
src/ssvc/_mixins.py	Introduced `VersionField` type for enforcing semantic version patterns.
data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json	Added v2 schema for selection objects with inline definitions.
data/schema/current/Decision_Point_Value_Selection.schema.json	Updated current schema pointer to v2.

Comments suppressed due to low confidence (3)

src/ssvc/selection.py:90

The new add_selection method is not covered by any tests; consider adding unit tests to verify selections are appended correctly.

    def add_selection(self, selection: MinimalSelection) -> None:

src/ssvc/selection.py:100

The selection_from_decision_point conversion function lacks direct test coverage; adding tests will help ensure correct mapping from DecisionPoint to MinimalSelection.

def selection_from_decision_point(decision_point: DecisionPoint) -> MinimalSelection:

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json:131

The schema does not include additionalProperties: false, allowing arbitrary fields; consider adding it at the root to enforce strict validation.

  "type": "object",

src/ssvc/selection.py

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json

ahouseholder · 2025-07-16T16:04:59Z

@tschmidtb51 requesting your feedback on the new schema.

…minimalist-selection-object

tschmidtb51

[Careful - unfinished review]

All elements should have a minLength (for Strings) etc. attribute.

I'll finish my review tomorrow with a fresh set of eyes.

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json

tschmidtb51 · 2025-07-24T21:29:12Z

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json

+          "title": "Version",
+          "type": "string"
+        },
+        "values": {


I agree with @sei-vsarvepalli that it is for humans nice to have a name value.

tschmidtb51 · 2025-07-25T15:40:46Z

Still reviewing

tschmidtb51

In my review, I came to the conclusion that it is best to use reverse FQDNs to differentiate between "language" and "xname" extensions. The latest and greatest is the new suggested ABNF - all other should follow from their or be made consistent to that...

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json

docs/adr/0012-ssvc-namespaces.md

docs/reference/code/namespaces.md

src/ssvc/selection.py

tschmidtb51 · 2025-07-25T20:26:14Z

src/ssvc/utils/patterns.py

+# --- Base namespace ---
+NO_CONSECUTIVE_SEP = r"(?!.*[.-]{2,})"  # no consecutive '.' or '-'
+
+BASE_PATTERN = (
+    rf"{NO_CONSECUTIVE_SEP}"
+    r"[a-z][a-z0-9]+"  # starts with lowercase letter + 1+ alnum
+    r"(?:[.-][a-z0-9]+)*"  # optional dot or dash + alnum
+)
+
+BASE_NS_PATTERN = rf"(?:x_{BASE_PATTERN}|{BASE_PATTERN})"
+
+# --- Extension segments ---
+# A single ext-seg with at most one '#'
+EXT_SEGMENT_PATTERN = (
+    rf"{NO_CONSECUTIVE_SEP}"
+    r"[a-zA-Z][a-zA-Z0-9]*"  # start with a letter
+    r"(?:[.-][a-zA-Z0-9]+)*"  # dot or dash + alnum
+    r"(?:#[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*)?"  # optional single hash section
+)
+
+# Subsequent ext-seg(s)
+SUBSEQUENT_EXT = rf"{EXT_SEGMENT_PATTERN}(?:/{EXT_SEGMENT_PATTERN})*"
+
+
+# --- Language extension ---
+LANG_EXT = rf"(?:/{BCP_47_PATTERN}/|//)"
+
+# --- Combine all parts into the full namespace pattern ---
+NS_PATTERN_STR = (
+    rf"^{LENGTH_CHECK_PATTERN}"
+    rf"{BASE_NS_PATTERN}"
+    rf"(?:{LANG_EXT}{SUBSEQUENT_EXT})?$"
+)


Please see comment on ABNF

src/test/test_namespaces_pattern.py

tschmidtb51 · 2025-07-25T20:36:48Z

src/ssvc/selection.py

Mostly covered in the JSON file - but the interface is hung up - I can't comment anything here.

tschmidtb51 · 2025-07-25T20:37:39Z

src/test/test_namespaces_pattern.py

You might want to add some cases after changing the regex and ABNF.

src/ssvc/selection.py

Co-authored-by: tschmidtb51 <[email protected]>

ahouseholder · 2025-07-28T20:06:48Z

The ABNF and Regex commentary has gotten too complicated for me to track in the context of this PR, and absorbing all of it will require more attention than I can give it at the moment.

I've merged the PR at its current state.

Please consolidate the feedback into a concise issue focused on the regex constructor in ssvc.utils.patterns.NS_PATTERN. I can't keep reverse-engineering back from comments on JSON schema, through pydantic generators, into what to change in the python code. If pydantic doesn't do it out of the box, I'm not inclined to go further than that as it's hard to justify additional engineering time on this already.

As it stands, I currently regret bringing ABNF into it, as it's not something we can easily manage and generate, and am more inclined to remove it from the documentation than to revise it.

ahouseholder added 13 commits July 15, 2025 14:20

refactor VersionField into an annotation for use in other objects

e7e3d79

also make CVSS decision point groups conform

add id property to decision points

de1a38b

namespace:key:version is sufficient to uniquely identify any Decision Point

add minimal selection object for data exchange

0d7b1c2

add new version of decision point value selection schema

1a4bd12

add new version of decision point value selection schema

6813909

make examples into lists

cc9874a

fix some formatting

3842cf7

remove default from VersionField annotation

0031210

we don't need a decision point id field separately, it's derivable fr…

be08398

…om the other key-value pairs

more clean up

4f4cde0

more clean up

b48d444

Merge branch '820-add-a-minimalist-selection-object' of https://githu…

bc81392

…b.com/CERTCC/SSVC into 820-add-a-minimalist-selection-object # Conflicts: # data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json # src/ssvc/selection.py

we don't need decision point id

82947e2

ahouseholder requested a review from sei-vsarvepalli as a code owner July 15, 2025 20:47

ahouseholder linked an issue Jul 15, 2025 that may be closed by this pull request

Add a minimalist selection object #820

Closed

ahouseholder requested a review from Copilot July 15, 2025 20:48

ahouseholder self-assigned this Jul 15, 2025

Copilot AI reviewed Jul 15, 2025

View reviewed changes

src/ssvc/selection.py Outdated Show resolved Hide resolved

src/ssvc/selection.py Show resolved Hide resolved

src/ssvc/selection.py Outdated Show resolved Hide resolved

data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json Outdated Show resolved Hide resolved

ahouseholder added integration/blocker Something that is blocking integration with another framework or system tech/backend Back-end tools, code, infrastructure integration Related to integration of SSVC into another framework or system labels Jul 15, 2025

ahouseholder added this to the 2025-09 milestone Jul 15, 2025

ahouseholder added 6 commits July 16, 2025 10:17

refactor schema version to variable

4b64e6b

compute path relative to module location

7c6c2a1

fix some redundancy based on copilot PR review

3b73b3d

refactor namespace and version specifications for modularity

3624054

add unit tests

f690df4

add namespace pattern and update examples

405f9d2

Merge branch 'main' of https://github.com/CERTCC/SSVC into 820-add-a-…

3b5f191

…minimalist-selection-object

tschmidtb51 suggested changes Jul 24, 2025

View reviewed changes

tschmidtb51 suggested changes Jul 25, 2025

View reviewed changes

tschmidtb51 reviewed Jul 25, 2025

View reviewed changes

src/ssvc/selection.py Outdated Show resolved Hide resolved

Update data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json

ab2ed94

Co-authored-by: tschmidtb51 <[email protected]>

ahouseholder mentioned this pull request Jul 28, 2025

Attach references to specific decision point selections instead of to the overall selection object? #832

Open

ahouseholder and others added 3 commits July 28, 2025 15:36

Update docs/adr/0012-ssvc-namespaces.md

1e77dcd

Co-authored-by: tschmidtb51 <[email protected]>

Update src/test/test_namespaces_pattern.py

c36eb64

Co-authored-by: tschmidtb51 <[email protected]>

Update src/ssvc/selection.py

538020d

Co-authored-by: tschmidtb51 <[email protected]>

ahouseholder mentioned this pull request Jul 28, 2025

Selection Resources and References descriptions are very similar #833

Closed

ahouseholder and others added 8 commits July 28, 2025 15:38

Update docs/reference/code/namespaces.md

e84a406

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

8c0f983

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

9b2a83a

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

9a48b01

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

2508240

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

0cedd65

Co-authored-by: tschmidtb51 <[email protected]>

Update docs/reference/code/namespaces.md

6949295

Co-authored-by: tschmidtb51 <[email protected]>

Update namespaces.md

eccf7ca

ahouseholder mentioned this pull request Jul 28, 2025

"name" and "description" should have min_length=1 #834

Closed

forbid extras

74463f1

ahouseholder mentioned this pull request Jul 28, 2025

In selection reference object, do we want that to be an URI or URL? #835

Open

Update docs/reference/code/namespaces.md

215da4e

Co-authored-by: tschmidtb51 <[email protected]>

ahouseholder mentioned this pull request Jul 28, 2025

Revise extension syntax #836

Closed

ahouseholder merged commit 9bcabec into main Jul 28, 2025
5 checks passed

ahouseholder deleted the 820-add-a-minimalist-selection-object branch July 28, 2025 20:01

This was referenced Jul 29, 2025

Create dataclass to represent DecisionTable selection #800

Open

Create a role registry #708

Closed

This was referenced Aug 8, 2025

ABNF suggestions #858

Closed

Should there a optional "references" section in Selection schema? #600

Closed

Minimalist Selection Object #821

Minimalist Selection Object #821

Uh oh!

Conversation

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

Uh oh!

Selection Object

Namespace Improvements

CoPilot Summary

Namespace Implementation and Documentation:

Schema Enhancements:

Codebase Improvements:

Documentation and Tools:

Co-Pilot Schema Comparison

Schema Structure Changes

Property Changes

Selection Object Changes

New Schema Definitions

Required Fields Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ahouseholder commented Jul 16, 2025

Uh oh!

tschmidtb51 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tschmidtb51 Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 commented Jul 25, 2025

Uh oh!

tschmidtb51 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tschmidtb51 Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tschmidtb51 Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ahouseholder commented Jul 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ahouseholder commented Jul 15, 2025 •

edited

Loading