Minimalist Selection Object (#821)

Author: ahouseholder

data/schema/current/Decision_Point_Value_Selection.schema.json

@@ -1 +1 @@
-../v1/Decision_Point_Value_Selection-1-0-1.schema.json
+../v2/Decision_Point_Value_Selection-2-0-0.schema.json

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

@@ -0,0 +1,236 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://certcc.github.io/SSVC/data/schema/v2/Decision_Point_Value_Selection-2-0-0.schema.json",
+  "title": "Decision Point Value Selection List",
+  "description": "This schema defines the structure for representing selected values from SSVC Decision Points. Each selection list can have multiple selection objects, each representing a decision point, and each selection object can have multiple selected values when full certainty (i.e., a singular value selection) is not available.",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "description": "Timestamp of the selections, in RFC 3339 format.",
+      "examples": [
+        "2025-01-01T12:00:00Z",
+        "2025-01-02T15:30:45-04:00"
+      ],
+      "format": "date-time",
+      "title": "Timestamp",
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": "2.0.0",
+      "description": "The schema version of this selection list.",
+      "title": "Schemaversion",
+      "type": "string"
+    },
+    "target_ids": {
+      "description": "Optional list of identifiers for the item or items (vulnerabilities, reports, advisories, systems, assets, etc.) being evaluated by these selections.",
+      "examples": [
+        [
+          "CVE-1900-0000"
+        ],
+        [
+          "VU#999999",
+          "GHSA-0123-4567-89ab"
+        ]
+      ],
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "title": "Target Ids",
+      "type": "array"
+    },
+    "selections": {
+      "description": "List of selections made from decision points. Each selection item corresponds to value keys contained in a specific decision point identified by its namespace, key, and version. Note that selection objects are deliberately minimal objects and do not contain the full decision point details.",
+      "items": {
+        "$ref": "#/$defs/Selection"
+      },
+      "minItems": 1,
+      "title": "Selections",
+      "type": "array"
+    },
+    "resources": {
+      "description": "A list of references to resources that provide additional context about the decision points found in this selection.",
+      "examples": [
+        [
+          {
+            "description": "Documentation for a set of decision points",
+            "uri": "https://example.com/decision_points"
+          },
+          {
+            "description": "JSON representation of decision point 2",
+            "uri": "https://example.org/definitions/dp2.json"
+          },
+          {
+            "description": "A JSON file containing extension decision points in the x_com.example namespace",
+            "uri": "https://example.com/ssvc/x_com.example/decision_points.json"
+          }
+        ]
+      ],
+      "items": {
+        "$ref": "#/$defs/Reference"
+      },
+      "minItems": 1,
+      "title": "Resources",
+      "type": "array"
+    },
+    "references": {
+      "description": "A list of references to resources that provide additional context about the specific values selected.",
+      "examples": [
+        [
+          {
+            "description": "A report on which the selections were based",
+            "uri": "https://example.com/report"
+          }
+        ],
+        [
+          {
+            "description": "A code section on which the selections were based",
+            "uri": "https://git.example.com/some-relevant-path/code#L21-42"
+          },
+          {
+            "description": "A code section on which calls the vulnerable function",
+            "uri": "https://git.example.com/some-relevant-path/callingcode#L91-16"
+          }
+        ]
+      ],
+      "items": {
+        "$ref": "#/$defs/Reference"
+      },
+      "minItems": 1,
+      "title": "References",
+      "type": "array"
+    }
+  },
+  "required": [
+    "timestamp",
+    "schemaVersion",
+    "selections"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "MinimalDecisionPointValue": {
+      "description": "A minimal representation of a decision point value.\nIntended to parallel the DecisionPointValue object, but with fewer required fields.\nA decision point value is uniquely identified within a decision point by its key.\nGlobally, the combination of Decision Point namespace, key, and version coupled with the value key\nuniquely identifies a value across all decision points and values.\nOther required fields in the DecisionPointValue object, such as name and description, are optional here.",
+      "properties": {
+        "key": {
+          "title": "Key",
+          "type": "string"
+        },
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "description": {
+          "title": "Description",
+          "type": "string"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "title": "MinimalDecisionPointValue",
+      "type": "object"
+    },
+    "Reference": {
+      "additionalProperties": false,
+      "description": "A reference to a resource that provides additional context about the decision points or selections.\nThis object is intentionally minimal and contains only the URL and an optional description.",
+      "properties": {
+        "uri": {
+          "format": "uri",
+          "minLength": 1,
+          "title": "Uri",
+          "type": "string"
+        },
+        "description": {
+          "title": "Description",
+          "type": "string"
+        }
+      },
+      "required": [
+        "uri"
+      ],
+      "title": "Reference",
+      "type": "object"
+    },
+    "Selection": {
+      "additionalProperties": false,
+      "description": "A minimal selection object that contains the decision point ID and the selected values.\nWhile the Selection object parallels the DecisionPoint object, it is intentionally minimal, with\nfewer required fields and no additional metadata, as it is meant to represent a selection made from a\npreviously defined decision point. The expectation is that a Selection object will usually have\nfewer values than the original decision point, as it represents a specific evaluation\nat a specific time and may therefore rule out some values that were previously considered.\nOther fields like name and description may be copied from the decision point, but are not required.",
+      "properties": {
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "description": {
+          "title": "Description",
+          "type": "string"
+        },
+        "namespace": {
+          "description": "The namespace of the SSVC object.",
+          "examples": [
+            "ssvc",
+            "cisa",
+            "x_com.example//com.example#private",
+            "ssvc/de-DE/example.organization#reference-arch-1"
+          ],
+          "maxLength": 1000,
+          "minLength": 3,
+          "pattern": "^(?=.{3,1000}$)(?:x_(?!.*[.-]{2,})[a-z][a-z0-9]+(?:[.-][a-z0-9]+)*|(?!.*[.-]{2,})[a-z][a-z0-9]+(?:[.-][a-z0-9]+)*)(?:(?:/(([A-Za-z]{2,3}(-[A-Za-z]{3}(-[A-Za-z]{3}){0,2})?|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[A-WY-Za-wy-z0-9](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Ii]-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]-[Mm][Ii][Nn][Gg][Oo])/|//)(?!.*[.-]{2,})[a-zA-Z][a-zA-Z0-9]*(?:[.-][a-zA-Z0-9]+)*(?:#[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*)?(?:/(?!.*[.-]{2,})[a-zA-Z][a-zA-Z0-9]*(?:[.-][a-zA-Z0-9]+)*(?:#[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*)?)*)?$",
+          "title": "Namespace",
+          "type": "string"
+        },
+        "key": {
+          "title": "Key",
+          "type": "string"
+        },
+        "version": {
+          "description": "The version of the SSVC object. This must be a valid semantic version string.",
+          "examples": [
+            "1.0.0",
+            "2.1.3"
+          ],
+          "minLength": 5,
+          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+          "title": "Version",
+          "type": "string"
+        },
+        "values": {
+          "description": "A list of selected value keys from the decision point values.",
+          "examples": [
+            [
+              {
+                "key": "N"
+              },
+              {
+                "key": "Y"
+              }
+            ],
+            [
+              {
+                "key": "A"
+              },
+              {
+                "key": "B"
+              },
+              {
+                "key": "C"
+              }
+            ]
+          ],
+          "items": {
+            "$ref": "#/$defs/MinimalDecisionPointValue"
+          },
+          "minItems": 1,
+          "title": "Values",
+          "type": "array"
+        }
+      },
+      "required": [
+        "namespace",
+        "key",
+        "version",
+        "values"
+      ],
+      "title": "Selection",
+      "type": "object"
+    }
+  }
+}

docs/adr/0012-ssvc-namespaces.md

@@ -0,0 +1,121 @@
+---
+status: "accepted"
+date: 2025-07-22
+deciders: @ahouseholer @sei-vsarvepalli
+consulted: @tschmidtb51
+---
+# Use of Namespaces in SSVC objects
+
+## Context and Problem Statement
+
+We need to include decision points and other objects that are not directly
+defined by the SSVC project team. For example, CVSS vector elements are a 
+rich source of structured data that can be used to inform SSVC decisions and
+modeled as SSVC decision point objects. However, the 
+[FIRST CVSS SIG](https://www.first.org/cvss) owns the definition of CVSS vector 
+elements. So we need a way to describe these objects in SSVC format
+without making them part of the SSVC specification.
+
+
+## Decision Drivers
+
+- Need to include decision points based on data, objects, standards, and other
+  definitions that are not part of the SSVC specification.
+- Need to clearly distinguish between objects managed by the SSVC project and
+  objects provided for convenience by the SSVC project, but whose semantics are
+  defined by other projects or standards.
+
+## Considered Options
+
+- One big pile of objects (effectively no namespaces)
+- Use namespaces to distinguish between SSVC project objects and other objects
+
+## Decision Outcome
+
+Chosen option: "Use namespaces", because
+
+- Clearly distinguishes between SSVC project objects and objects derived from other sources
+- Allows for extension of SSVC objects with additional data from other sources
+- Allows for extensions for langauages, translation, localization, etc.
+
+Specifically, we intend to use:
+
+**Registered namespaces** for objects that we create and maintain (even if they are
+based on other sources).
+
+!!! example
+
+    We use the `ssvc` namespace for all SSVC objects that are part of the
+    main project. We use the `cvss` namespace to contain CVSS vector elements.
+
+**Unregistered namespaces** for objects that we do not create or maintain, but
+that others may want for their own use. Unregistered namespaces must start with 
+an `x_` prefix followed by a reverse domain name, such as `x_org.example`.
+Unregistered namespaces are intended for experimental or private use.
+
+!!! example
+
+    A government agency might create a set of decision points for internal use 
+    using the `x_example.agency` namespace. This allows them to use SSVC objects
+    of their own design alongside existig SSVC objects without needing to
+    register their namespace with the SSVC project.
+
+**Namespace extensions** for objects that are derived from other objects in an
+registered or unregistered namespace. Extensions are not intended to be used to 
+introduce new objects, but rather to refine existing objects with additional data
+or semantics.
+Namespace extensions can be used for refining the meaning of decision point 
+values for a specific constituency, or adding additional nuance to
+interpretation of a decision point in a specific context.
+
+!!! example
+
+    An ISAO (Information Sharing and Analyzing Organization) might want to refine the meaning of decision point values for their
+    constituency, and could use `ssvc//example.isao` as the namespace for their
+    collection of extensions.
+
+### Consequences
+
+#### Positive Consequences
+
+- SSVC users can customize SSVC objects with additional refinements using extensions
+- SSVC users can create their own SSVC objects in an unregistered namespace for
+  their own use, and share them with others
+- Facilitates language translation and localization of SSVC objects to specific
+  constituencies
+
+
+#### Negative Consequences
+
+- Registered namespaces must be managed and maintained
+- Potential for confusion if unregistered namespaces are used without care or
+  violating the naming conventions
+
+<!-- This is an optional element. Feel free to remove. -->
+### Confirmation
+
+- Regular expressions are used in the SSVC specification in both python objects
+  and JSON schema to validate the namespace format.
+- Object validators can be used to ensure that namespaces are correctly formatted
+  and that registered namespaces are used for objects that are part of the SSVC
+  specification.
+
+<!-- This is an optional element. Feel free to remove. -->
+## Pros and Cons of the Options
+
+### One big pile of objects
+
+We started out with all objects having no namespaces, which meant that
+all objects were effectively part of the SSVC specification. This was problematic
+because it made it difficult to distinguish between objects that were part of the
+SSVC specification under our control and objects that were derived from other sources.
+
+- Good, because it was simple and easy to understand
+- Bad, because it made it difficult to distinguish between SSVC project objects and
+  objects based on specifications we neither created nor maintained
+
+
+<!-- This is an optional element. Feel free to remove. -->
+## More Information
+
+- [SSVC Namespace Documentation](../reference/code/namespaces.md)

docs/adr/index.md

@@ -23,6 +23,7 @@ the decision records that have been made.
 - [0009 - Outcomes are Ordered Sets](0009-outcomes-are-ordered-sets.md)
 - [0010 - Outcome Sets are separate from Decision Point Groups](0010-outcome-sets-are-separate-from-decision-point-groups.md)
 - [0011 - Correspondence between Automatable v2.0.0, Value Density v1.0.0, and CVSS v4](0011-automatable-and-value-density-and-CVSSv4.md)
+- [0012 - SSVC Namespaces](0012-ssvc-namespaces.md)
 
 ## Rejected Records