🐛 Register sphinx-needs fields with a typed schema (#80)

## Problem

sphinx-codelinks registers its fields (`project`, `file`, `directory`,
and the
local/remote url fields) via `add_extra_option(app, name)` **without a
schema**.
Untyped fields default to `""` on *every* need, so when a project
enables strict
sphinx-needs schema validation (`unevaluatedProperties: false`) those
empty
fields are reported as unexpected on needs that never set them:

    Need 'REQ_1' has schema violations:
Unevaluated properties are not allowed ('directory', 'file', 'project'
were unexpected)

This is the codelinks-side counterpart of the same bug found and fixed
in
sphinx-test-reports.

## Fix

Register each field with a typed (string) schema so an unset value
defaults to
`None`. sphinx-needs strips `None` from the "reduced need" before schema
validation, so a strict `unevaluatedProperties: false` schema no longer
flags a
field a need never set (an untyped field stays `""`, which is not
stripped).

Registration adapts to the installed sphinx-needs by **capability
detection**
(no `packaging` dependency, matching sphinx-test-reports):

- `add_field(name, description, schema=...)` — the modern API, used
wherever it
  is importable.
- otherwise `add_extra_option(app, name, schema=...)` when
`add_extra_option`
  accepts a `schema` keyword (sphinx-needs >= 6).
- otherwise `add_extra_option(app, name)` for sphinx-needs 5, which has
no schema
  validation, so the empty-default bug cannot arise there anyway.

The `schema` capability is detected with
`"schema" in signature(add_extra_option).parameters`.

## Test

Adds `tests/doc_test/schema_strictness/` +
`tests/test_schema_validation.py`: a
strict-schema project with a plain need, asserting no schema violation.
Confirmed **red before the fix** (`'directory', 'file', 'project' were
unexpected`) and **green after**. The test is skipped when
`add_extra_option`
has no `schema` keyword (sphinx-needs < 6).

Local checks: `ruff` + `mypy` clean; regression test green on
sphinx-needs 6/7/8
and correctly skipped on 5; existing src-trace doctree snapshots
unchanged.

Author: ubmarco

src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -6,8 +6,7 @@
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from packaging.version import Version
-import sphinx
+from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx_needs.api import add_need  # type: ignore[import-untyped]
 from sphinx_needs.utils import add_doc  # type: ignore[import-untyped]
@@ -23,14 +22,6 @@
 from sphinx_codelinks.source_discover.source_discover import SourceDiscover
 from sphinx_codelinks.sphinx_extension.debug import measure_time
 
-sphinx_version = sphinx.__version__
-
-
-if Version(sphinx_version) >= Version("1.6"):
-    from sphinx.util import logging
-else:
-    import logging  # type: ignore[no-redef]
-
 logger = logging.getLogger(__name__)
 
 

src/sphinx_codelinks/sphinx_extension/source_tracing.py

@@ -1,5 +1,6 @@
 from collections.abc import Iterator  # only in python 3.11 afterwards
 import contextlib
+from inspect import signature
 from pathlib import Path
 from timeit import default_timer as timer  # Used for timing measurements
 import tomllib
@@ -35,6 +36,34 @@
 
 logger = logging.getLogger(__name__)
 
+try:
+    from sphinx_needs.api import add_field as _add_field
+except ImportError:  # sphinx-needs < 8 has no add_field
+    _add_field = None
+
+# add_extra_option only accepts a schema on sphinx-needs >= 6 (where schema
+# validation exists); older versions take just (app, name). Probe the signature
+# instead of comparing versions, so no ``packaging`` dependency is needed.
+_USE_FIELD_SCHEMA = "schema" in signature(add_extra_option).parameters
+
+
+def _register_sn_field(app: Sphinx, name: str, description: str) -> None:
+    """Register a string field, preferring the modern ``add_field`` API.
+
+    ``add_field`` (sphinx-needs >= 8) registers a typed field; older versions
+    fall back to ``add_extra_option`` (only deprecated on >= 8). A typed field
+    defaults to ``None`` and is stripped before schema validation, whereas an
+    untyped field defaults to ``""`` and would trip a strict
+    ``unevaluatedProperties: false`` schema on needs that never set it.
+    """
+    schema = {"type": "string"}
+    if _add_field is not None:
+        _add_field(name, description, schema=schema)
+    elif _USE_FIELD_SCHEMA:
+        add_extra_option(app, name, schema=schema)
+    else:
+        add_extra_option(app, name)
+
 
 def _check_sphinx_needs_dependency(app: Sphinx) -> bool:
     """Check if sphinx-needs is actually loaded as an extension."""
@@ -185,13 +214,17 @@ def set_config_to_sphinx(
 
 def update_sn_extra_options(app: Sphinx, config: _SphinxConfig) -> None:
     src_trace_sphinx_config = CodeLinksConfig.from_sphinx(config)
-    add_extra_option(app, "project")
-    add_extra_option(app, "file")
-    add_extra_option(app, "directory")
+    _register_sn_field(app, "project", "Source-tracing project")
+    _register_sn_field(app, "file", "Source file")
+    _register_sn_field(app, "directory", "Source directory")
     if src_trace_sphinx_config.set_local_url:
-        add_extra_option(app, src_trace_sphinx_config.local_url_field)
+        _register_sn_field(
+            app, src_trace_sphinx_config.local_url_field, "Local source URL"
+        )
     if src_trace_sphinx_config.set_remote_url:
-        add_extra_option(app, src_trace_sphinx_config.remote_url_field)
+        _register_sn_field(
+            app, src_trace_sphinx_config.remote_url_field, "Remote source URL"
+        )
 
 
 def update_sn_types(app: Sphinx, _config: _SphinxConfig) -> None:

tests/doc_test/schema_strictness/conf.py

@@ -0,0 +1,15 @@
+project = "schema-strictness-demo"
+copyright = "2026, useblocks"
+author = "useblocks"
+
+extensions = ["sphinx_needs", "sphinx_codelinks"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# A strict sphinx-needs schema that forbids any field beyond the core
+# id/title/type. sphinx-codelinks registers fields (project/file/directory and
+# optionally the url fields) globally, attaching them to every need; those must
+# not be reported as "additional" fields when left unpopulated.
+needs_schema_definitions_from_json = "schemas.json"
+
+html_theme = "alabaster"

tests/doc_test/schema_strictness/index.rst

@@ -0,0 +1,11 @@
+Strict schema with unset sphinx-codelinks fields
+================================================
+
+This plain requirement does not use source tracing. It leaves the fields that
+sphinx-codelinks registers globally (``project``, ``file``, ``directory`` ...)
+unpopulated. A schema that forbids additional fields
+(``unevaluatedProperties: false``) must therefore not report them as
+unexpected.
+
+.. req:: A plain requirement
+   :id: REQ_1

tests/doc_test/schema_strictness/schemas.json

@@ -0,0 +1,13 @@
+{
+  "schemas": [
+    {
+      "id": "no-additional-fields",
+      "severity": "violation",
+      "validate": {
+        "local": {
+          "unevaluatedProperties": false
+        }
+      }
+    }
+  ]
+}

tests/test_schema_validation.py

@@ -0,0 +1,67 @@
+"""Regression test for sphinx-needs schema validation of sphinx-codelinks fields.
+
+sphinx-codelinks registers extra fields (``project``, ``file``, ``directory``
+and, when enabled, the local/remote url fields) with sphinx-needs. These fields
+are attached to *every* need in the project.
+
+When a user defines a strict sphinx-needs schema that forbids any field beyond
+the core ``id`` / ``title`` / ``type`` (``unevaluatedProperties: false``), those
+registered fields must not be treated as "additional" fields for needs that
+never populate them. The fields therefore have to be registered with a typed
+schema, so unset values default to ``None`` and are stripped before schema
+validation (an untyped field defaults to ``""``, which is not stripped and trips
+``unevaluatedProperties: false``).
+"""
+
+from collections.abc import Callable
+from inspect import signature
+import json
+from pathlib import Path
+import shutil
+
+import pytest
+from sphinx.testing.util import SphinxTestApp
+from sphinx_needs.api import add_extra_option  # type: ignore[import-untyped]
+
+# Schema validation (needs_schema_definitions) arrived in sphinx-needs 6.0.0,
+# the same release where add_extra_option gained its ``schema`` keyword. Probe
+# that keyword to gate the test, instead of pulling in ``packaging`` for a
+# version comparison.
+SN_SUPPORTS_SCHEMAS = "schema" in signature(add_extra_option).parameters
+
+
+@pytest.mark.skipif(
+    not SN_SUPPORTS_SCHEMAS,
+    reason="needs_schema_definitions requires sphinx-needs>=6.0.0",
+)
+def test_strict_schema_ignores_unset_codelinks_fields(
+    tmp_path: Path,
+    make_app: Callable[..., SphinxTestApp],
+) -> None:
+    this_file_dir = Path(__file__).parent
+    sphinx_project = Path("doc_test") / "schema_strictness"
+    sphinx_src_dir = tmp_path / sphinx_project
+    shutil.copytree(
+        this_file_dir / sphinx_project,
+        sphinx_src_dir,
+        dirs_exist_ok=True,
+    )
+
+    app: SphinxTestApp = make_app(srcdir=sphinx_src_dir, freshenv=True)
+    app.build()
+
+    report = json.loads(
+        (Path(app.outdir) / "schema_violations.json").read_text(encoding="utf-8")
+    )
+
+    # Schema validation actually ran over our need ...
+    assert report["validated_needs_count"] >= 1
+
+    # ... and produced no violations. If sphinx-codelinks registered its fields
+    # untyped (default ""), REQ_1 would carry empty project/file/directory values
+    # and the strict schema would (wrongly) report
+    # "unevaluated properties are not allowed".
+    assert report["validation_warnings"] == {}, (
+        "Strict schema flagged unset sphinx-codelinks fields: "
+        f"{json.dumps(report['validation_warnings'], indent=2)}"
+    )