Merge branch 'main' into 705-model-national-cybersecurity-incident-scoring-system

# Conflicts:
#	data/schema/v1/Decision_Point-1-0-1.schema.json
#	src/ssvc/_mixins.py
#	src/ssvc/decision_points/base.py
#	src/ssvc/namespaces.py
#	src/test/test_mixins.py

Author: ahouseholder

.github/workflows/lint_md_changes.yml

@@ -16,7 +16,7 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: tj-actions/changed-files@v45
+    - uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32
       id: changed-files
       with:
         files: '**/*.md'

data/schema/v1/Decision_Point-1-0-1.schema.json

@@ -47,9 +47,9 @@
 		},
 		"namespace": {
 		    "type": "string",
-		    "description": "Namespace (a short, unique string): For example, \"ssvc\" or \"cvss\" to indicate the source of the decision point. See SSVC Documentation for details.",
-		    "pattern": "^(?=.{3,25}$)(x_)?[a-z0-9]{3,4}([/.-]?[a-z0-9]+){0,22}$",
-		    "examples": ["ssvc", "cvss", "ssvc-jp", "ssvc/acme", "ssvc/example.com"]
+		    "description": "Namespace (a short, unique string): The value must be one of the official namespaces, currenlty \"ssvc\", \"cvss\" OR can start with 'x_' for private namespaces. See SSVC Documentation for details.",
+		    "pattern": "^(?=.{3,25}$)(x_)?[a-z0-9]{3}([/.-]?[a-z0-9]+){0,22}$",
+		    "examples": ["ssvc", "cvss", "x_custom","x_custom/extension"]
 		},
 		"version": {
 		    "type": "string",

docs/reference/code/index.md

@@ -6,4 +6,5 @@ These include:
 - [CSV Analyzer](analyze_csv.md)
 - [Policy Generator](policy_generator.md)
 - [Outcomes](outcomes.md)
+- [Namespaces](namespaces.md)
 - [Doctools](doctools.md)

docs/reference/code/namespaces.md

@@ -0,0 +1,3 @@
+# SSVC Namespaces
+
+::: ssvc.namespaces

mkdocs.yml

@@ -120,6 +120,7 @@ nav:
         - CSV Analyzer: 'reference/code/analyze_csv.md'
         - Policy Generator: 'reference/code/policy_generator.md'
         - Outcomes: 'reference/code/outcomes.md'
+        - Namespaces: 'reference/code/namespaces.md'
         - Doctools: 'reference/code/doctools.md'
   - Calculator: 'ssvc-calc/index.md'
   - About:

src/ssvc/_mixins.py

@@ -34,7 +34,7 @@ class _Versioned(BaseModel):
 
     @field_validator("version")
     @classmethod
-    def validate_version(cls, value):
+    def validate_version(cls, value: str) -> str:
         """
         Validate the version field.
         Args:
@@ -61,7 +61,7 @@ class _Namespaced(BaseModel):
 
     @field_validator("namespace", mode="before")
     @classmethod
-    def validate_namespace(cls, value):
+    def validate_namespace(cls, value: str) -> str:
         """
         Validate the namespace field.
         The value will have already been checked against the pattern in the field definition.

src/ssvc/decision_points/base.py

@@ -62,7 +62,7 @@ class SsvcDecisionPointValue(_Base, _Keyed, BaseModel):
     """
 
 
-class SsvcDecisionPoint(_Valued, _Keyed, _Versioned, _Namespaced, _Base, BaseModel):
+class SsvcDecisionPoint(_Base, _Keyed, _Versioned, _Namespaced, BaseModel):
     """
     Models a single decision point as a list of values.
     """

src/ssvc/namespaces.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 """
-Provides a namespace enum
+SSVC objects use namespaces to distinguish between objects that arise from different
+stakeholders or analytical category sources. This module defines the official namespaces
+for SSVC and provides a method to validate namespace values.
 """
 #  Copyright (c) 2025 Carnegie Mellon University and Contributors.
 #  - see Contributors.md for a full list of Contributors
@@ -18,10 +20,8 @@
 import re
 from enum import StrEnum, auto
 
-# extensions / experimental namespaces should start with the following prefix
-# this is to avoid conflicts with official namespaces
 X_PFX = "x_"
-
+"""The prefix for extension namespaces. Extension namespaces must start with this prefix."""
 
 # pattern to match
 # `(?=.{3,25}$)`: 3-25 characters long
@@ -32,12 +32,41 @@
 # `([/.-]?[a-z0-9]+){0,22}`: zero to 22 occurrences of the punctuation character followed by at least one alphanumeric character
 # (note that the total limit will kick in at or before this point)
 # `$`: end of the string
-NS_PATTERN = re.compile(r"^(?=.{3,25}$)(x_)?[a-z0-9]{3,4}([/.-]?[a-z0-9]+){0,22}$")
+NS_PATTERN = re.compile(r"^(?=.{3,25}$)(x_)?[a-z0-9]{3}([/.-]?[a-z0-9]+){0,22}$")
+"""The regular expression pattern for validating namespaces.
+
+Note: 
+    Namespace values must 
+    
+    - be 3-25 characters long
+    - contain only lowercase alphanumeric characters and limited punctuation characters (`/`,`.` and `-`)
+    - have only one punctuation character in a row
+    - start with 3-4 alphanumeric characters after the optional extension prefix
+    - end with an alphanumeric character
+    
+    See examples in the `NameSpace` enum.
+"""
 
 
 class NameSpace(StrEnum):
     """
     Defines the official namespaces for SSVC.
+
+    The namespace value must be one of the members of this enum or start with the prefix specified in X_PFX.
+    Namespaces must be 3-25 lowercase characters long and must start with 3-4 alphanumeric characters after the optional prefix.
+    Limited punctuation characters (/.-) are allowed between alphanumeric characters, but only one at a time.
+
+    Example:
+        Following are examples of valid and invalid namespace values:
+
+        - `ssvc` is *valid* because it is present in the enum
+        - `custom` is *invalid* because it does not start with the experimental prefix and is not in the enum
+        - `x_custom` is *valid* because it starts with the experimental prefix and meets the pattern requirements
+        - `x_custom/extension` is *valid* because it starts with the experimental prefix and meets the pattern requirements
+        - `x_custom/extension/with/multiple/segments` is *invalid* because it exceeds the maximum length
+        - `x_custom//extension` is *invalid* because it has multiple punctuation characters in a row
+        - `x_custom.extension.` is *invalid* because it does not end with an alphanumeric character
+        - `x_custom.extension.9` is *valid* because it meets the pattern requirements
     """
 
     # auto() is used to automatically assign values to the members.
@@ -47,9 +76,10 @@ class NameSpace(StrEnum):
     NCISS = auto()
 
     @classmethod
-    def validate(cls, value):
+    def validate(cls, value: str) -> str:
         """
-        Validate the namespace value.
+        Validate the namespace value. Valid values are members of the enum or start with the experimental prefix and
+        meet the specified pattern requirements.
 
         Args:
             value: the namespace value to validate

src/test/test_mixins.py

@@ -16,8 +16,8 @@
 
 from pydantic import BaseModel, ValidationError
 
-from ssvc.namespaces import NameSpace
 from ssvc._mixins import _Base, _Keyed, _Namespaced, _Valued, _Versioned
+from ssvc.namespaces import NameSpace
 
 
 class TestMixins(unittest.TestCase):