Improve namespace implementation by ahouseholder · Pull Request #824 · CERTCC/SSVC

ahouseholder · 2025-07-17T20:58:50Z

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

This PR implements the namespace clarifications from #780.

Note

This PR builds on #821 and should either be merged into #821 or merged to main after #821 is merged into main.

CoPilot Summary

This pull request introduces several changes to improve the SSVC codebase by enhancing schema definitions, modularizing utility functions, and refining namespace validation. The updates include adjustments to schema descriptions, the introduction of reusable field specifications and patterns, and modifications to test cases to align with the new namespace format.

Schema Improvements:

Updated selections field description: Expanded the description to clarify the relationship between selection items and decision points, emphasizing the minimal nature of selection objects. (data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json, data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.jsonL32-R32)
Refined Namespace examples and pattern: Enhanced the namespace validation pattern to support additional characters (#) and complex structures while ensuring compliance with length and format constraints. (data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json, data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.jsonL67-R72)

Codebase Modularization:

Introduced utility modules:
- src/ssvc/utils/defaults.py: Consolidated constants such as DEFAULT_VERSION, X_PFX, and FIELD_DELIMITER.
- src/ssvc/utils/field_specs.py: Defined reusable Pydantic field specifications for VersionString, NamespaceString, and TargetIdList.
- src/ssvc/utils/patterns.py: Centralized regex patterns for semantic versioning and namespace validation.
Refactored imports: Updated references across modules to use the new utility functions and field specifications, improving maintainability and readability. (src/ssvc/_mixins.py, [1]; src/ssvc/selection.py, [2]

Namespace Validation Enhancements:

Improved namespace rules: Allowed additional punctuation (#) and refined validation logic to prevent consecutive separators. (src/ssvc/namespaces.py, src/ssvc/namespaces.pyL89-R39)
Aligned namespace format in tests: Updated test cases to use the new namespace format (x_example.test) for consistency. (src/test/decision_points/test_dp_base.py, [1]; src/test/decision_points/test_dp_helpers.py, [2]; src/test/dp_groups/test_dp_groups.py, [3]; src/test/outcomes/test_outcomes.py, [4]; src/test/test_doc_helpers.py, [5]

ahouseholder · 2025-07-17T21:00:09Z

@tschmidtb51

sei-vsarvepalli

All looks good and clear to me.. I will wait on Thomas' feedback if any over next week, then we can merge it off.

tschmidtb51

@ahouseholder Thank you for providing that. I missed the PR and therefore noted some comments in #780.

Main points:

enforcement of reverse DNS
provide option to separate organization (reverse DNS) and "model", e.g. #

I look forward to our conversation on Monday

docs/reference/code/namespaces.md

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

…private-and-extension-namespaces' into 780-clarify-distinction-between-private-and-extension-namespaces

…espaces

…private-and-extension-namespaces' into 780-clarify-distinction-between-private-and-extension-namespaces

…-distinction-between-private-and-extension-namespaces

Also added more test strings

…sed) to avoid confusion with "example.org" which is also reserved

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

…e domain expectation

…-distinction-between-private-and-extension-namespaces

ahouseholder · 2025-07-22T19:17:23Z

For ease of figuring out what's new, I've marked all previous suggestions as resolved, and have re-requested review from @tschmidtb51 and @sei-vsarvepalli on the current version of the branch.

src/ssvc/selection.py

…rsioned json schemas

ahouseholder · 2025-07-23T16:24:41Z

I did just push (in afe9c61) a revamp of the values part of the selection object.

Note

Strictly speaking, this should have gone into the #821 branch, but I'm doing this in #824 instead of #821 because it depends on a previous refactoring that only exists in the #824 branch.

To maintain parallelism with the full-size DecisionPointValue object, I added a MinimalDecisionPointValue that only requires a key. Compare:

from ssvc.decision_points.base import DecisionPointValue
DecisionPointValue.model_json_schema()

Out[6]: 
{'description': 'Models a single value option for a decision point.\n\nEach value should have the following attributes:\n\n- name (str): A name\n- description (str): A description\n- key (str): A key (a short, unique string) that can be used to identify the value in a shorthand way\n- _comment (str): An optional comment that will be included in the object.',
 'properties': {'key': {'title': 'Key', 'type': 'string'},
  'name': {'title': 'Name', 'type': 'string'},
  'description': {'title': 'Description', 'type': 'string'}},
 'required': ['key', 'name', 'description'],
 'title': 'DecisionPointValue',
 'type': 'object'}

from ssvc.selection import MinimalDecisionPointValue
MinimalDecisionPointValue.model_json_schema()
Out[8]: 
{'description': 'A minimal representation of a decision point value.',
 'properties': {'key': {'title': 'Key', 'type': 'string'}},
 'required': ['key'],
 'title': 'MinimalDecisionPointValue',
 'type': 'object'}

See commit diff for details of how this changes the JSON schema.

ahouseholder · 2025-07-23T16:34:05Z

Current preview of the resulting selection object:

{
  "schemaVersion": "2.0.0",
  "selections": [
    {
      "namespace": "ssvc",
      "key": "A",
      "version": "2.0.0",
      "values": [
        {
          "key": "N"
        }
      ]
    },
    {
      "namespace": "ssvc",
      "key": "SI",
      "version": "2.0.0",
      "values": [
        {
          "key": "N"
        },
        {
          "key": "M"
        }
      ]
    }
  ],
  "timestamp": "2025-07-23T16:38:36Z"
}

…for documentation

ahouseholder · 2025-07-23T19:07:30Z

After discussion with @sei-vsarvepalli, we've agreed to merge this into #821 and will continue the wrap-up tasks in that PR

ahouseholder added 3 commits July 17, 2025 12:20

work in progress commit. Not quite working yet

3993da4

updates namespace regex to fit test strings

494dbbd

add namespaces docs

2b8c5af

ahouseholder requested review from cgyarbrough, j--- and sei-vsarvepalli as code owners July 17, 2025 20:58

ahouseholder self-assigned this Jul 17, 2025

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

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

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

Clarify distinction between private and extension namespaces #780

Closed

sei-vsarvepalli reviewed Jul 17, 2025

View reviewed changes

tschmidtb51 suggested changes Jul 18, 2025

View reviewed changes

Update docs/reference/code/namespaces.md

3fbb206

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

ahouseholder mentioned this pull request Jul 18, 2025

namespace entries should point to a url of a JSON list of decision points in that namespace #752

Open

ahouseholder added 7 commits July 18, 2025 15:10

fix typo

2108157

Merge remote-tracking branch 'gh_pub/780-clarify-distinction-between-…

5b8c98f

…private-and-extension-namespaces' into 780-clarify-distinction-between-private-and-extension-namespaces

add reverse domain name recommendation for private / experimental nam…

5c0b213

…espaces

add reverse domain name recommendation for private / experimental nam…

8545878

…espaces

Merge remote-tracking branch 'gh_pub/780-clarify-distinction-between-…

8c4077c

…private-and-extension-namespaces' into 780-clarify-distinction-between-private-and-extension-namespaces

add warning about "no adds" in extensions.

c2a5e84

add one more test string

3dae4a9

ahouseholder mentioned this pull request Jul 21, 2025

Minimalist Selection Object #821

Merged

ahouseholder added 5 commits July 21, 2025 12:03

Merge branch '820-add-a-minimalist-selection-object' into 780-clarify…

ed4c9fb

…-distinction-between-private-and-extension-namespaces

adjust example namespaces

c2673cc

pattern was blocking 2-letter TLDs in reverse-domain-name convention

337bcf1

Also added more test strings

example.org -> example.organization (as in organization.example rever…

b52b8ca

…sed) to avoid confusion with "example.org" which is also reserved

refactor defaults, patterns, and types into an ssvc.utils sub-package

009b8a2

ahouseholder added 2 commits July 21, 2025 16:44

updated NS pattern

13c364e

add # to allowed chars

4aae5b0

ahouseholder commented Jul 22, 2025

View reviewed changes

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

ahouseholder added 3 commits July 22, 2025 11:08

replace "x_test" with "x_example.test" to bring into line with revers…

e26856b

…e domain expectation

revise documentation

343542b

Merge branch '820-add-a-minimalist-selection-object' into 780-clarify…

746ee88

…-distinction-between-private-and-extension-namespaces

ahouseholder requested review from sei-vsarvepalli and tschmidtb51 July 22, 2025 19:03

ahouseholder added 3 commits July 22, 2025 15:06

fix examples in namespace field_specs.py

eba76b4

refactor TargetIdList into ssvc.utils.field_specs

0855875

update schema

abc3bde

ahouseholder mentioned this pull request Jul 22, 2025

Improve validation of namespace string structures #830

Open

fix #753

6702558

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

add ADR & clarify namespace reference doc to explain intent of non-ssvc namespaces #753

Closed

sei-vsarvepalli reviewed Jul 22, 2025

View reviewed changes

src/ssvc/selection.py Show resolved Hide resolved

ahouseholder added 2 commits July 23, 2025 12:11

change how we set default version so that "version" is required in ve…

5dcf367

…rsioned json schemas

clean up definitions with mixins

afe9c61

ahouseholder added 7 commits July 23, 2025 12:39

enforce UTC and no milliseconds when serializing out to JSON

53d550d

refactor timestamp into a mixin class

46c27a9

fix tests

8dd88e1

add keys in parentheses when we generate examples of decision points …

4746d8e

…for documentation

add full identity to dp title strings

079d7b2

port over decision point identity method from another branch

65cef84

fix tests

a623e2c

ahouseholder merged commit b955ef7 into 820-add-a-minimalist-selection-object Jul 23, 2025
1 check passed

ahouseholder deleted the 780-clarify-distinction-between-private-and-extension-namespaces branch July 23, 2025 19:07

Conversation

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

Uh oh!

CoPilot Summary

Schema Improvements:

Codebase Modularization:

Namespace Validation Enhancements:

Uh oh!

ahouseholder commented Jul 17, 2025

Uh oh!

sei-vsarvepalli left a comment

Choose a reason for hiding this comment

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!

Uh oh!

Uh oh!

ahouseholder commented Jul 22, 2025

Uh oh!

Uh oh!

ahouseholder commented Jul 23, 2025

Uh oh!

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

Uh oh!

Uh oh!

ahouseholder commented Jul 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ahouseholder commented Jul 17, 2025 •

edited

Loading

ahouseholder commented Jul 23, 2025 •

edited

Loading