Skip to content

Conversation

@ahouseholder
Copy link
Contributor

@ahouseholder ahouseholder commented Sep 9, 2025

This PR:

  • resolves Reserve registered namespace invalid #907
  • resolves [Documentation] Clarify reserved special purpose namespaces #908
  • might address [Documentation] "unregistered" vs. "private" #909 but there is not enough detail in that issue to tell whether it does or not
  • Explicitly calls out RESERVED namespace strings:
    • invalid and x_invalid are blocked from use
    • example and x_example are reserved for examples and documentation
    • test and x_test are reserved for tests
  • adds a nist namespace
  • refactors one of the probability-based decision points based on NIST 800-30 into the nist namespace
    • this incidentally resolved a situation in which two identically named decision points were clobbering each other when we generated the .json files, hence what appears to be an unrelated change to data/json/decision_points/basic/probability_scale_in_5_weighted_levels_ascending_1_0_0.json
  • revises the namespaces.md documentation diagrams for clarity

Copilot Summary

This pull request refactors the probability scale decision point definitions and updates the documentation for namespace structure and extension usage. The main changes are the migration of the NIST-based probability scale to its own namespace, a redesign of the "basic" weighted probability scale, and comprehensive improvements to the documentation on namespace conventions and extensions.

Decision Point Refactoring:

  • Migrated the NIST SP 800-30 probability scale (P_5X) from the basic namespace to a new nist#800-30 namespace, restoring its original value definitions and associated registry entries. [1] [2]
  • Redesigned the basic probability scale (P_5W) to use ascending probability ranges with higher resolution as probability increases, replacing the previous NIST-based value definitions.
  • Updated the SSVC object registry to remove the old basic.P_5X entry and add the new nist#800-30.P_5X entry. [1] [2]
  • Updated the Python module src/ssvc/decision_points/basic/probability/__init__.py to remove the NIST probability scale from the basic namespace and ensure only the correct decision points are registered.

Documentation Improvements (Namespace and Extension Structure):

  • Expanded documentation in docs/reference/code/namespaces.md to clarify reserved namespace strings, the use and requirements of fragments in registered and unregistered namespaces, and the semantic and structural requirements for namespace extensions. This includes new diagrams, notes, and examples for better understanding. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

These changes improve the clarity and maintainability of the decision point definitions and provide more robust guidance for namespace usage and extension in SSVC.

@ahouseholder ahouseholder self-assigned this Sep 9, 2025
@ahouseholder ahouseholder added content/semantic Changes to the semantic content of the SSVC documentation enhancement New feature or request python Pull requests that update Python code content/representation Formatting, page layout, syntax, etc. tech/backend Back-end tools, code, infrastructure tech/data Data implementation (content of /data, data object instances, etc.) integration Related to integration of SSVC into another framework or system labels Sep 9, 2025
@ahouseholder ahouseholder added this to the 2025-09 milestone Sep 9, 2025
@ahouseholder
Copy link
Contributor Author

ahouseholder commented Sep 9, 2025

Screenshots of the most significant content changes:

Screenshot 2025-09-09 at 4 22 52 PM

Note

The following screenshot is slightly behind the current branch. The later version has been copy edited to fix the example and test lines.

Screenshot 2025-09-09 at 4 22 39 PM Screenshot 2025-09-09 at 4 22 19 PM Screenshot 2025-09-09 at 4 22 12 PM

Copy link
Contributor

@sei-vsarvepalli sei-vsarvepalli left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also has other probability stuff updates in it - all okay.

@ahouseholder ahouseholder merged commit 25637c3 into main Sep 10, 2025
5 checks passed
@ahouseholder ahouseholder deleted the 907-reserve-registered-namespace-invalid branch September 10, 2025 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content/representation Formatting, page layout, syntax, etc. content/semantic Changes to the semantic content of the SSVC documentation enhancement New feature or request integration Related to integration of SSVC into another framework or system python Pull requests that update Python code tech/backend Back-end tools, code, infrastructure tech/data Data implementation (content of /data, data object instances, etc.)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Documentation] Clarify reserved special purpose namespaces Reserve registered namespace invalid

3 participants