useblocks · chrisjsewell · Feb 9, 2026 · Feb 9, 2026 · Feb 9, 2026
diff --git a/docs/_static/tutorial_needs.json b/docs/_static/tutorial_needs.json
diff --git a/docs/ubproject.toml b/docs/ubproject.toml
@@ -64,15 +64,19 @@ parse_variants = true
 
 [needs.fields.my_extra_option]
 description = "Custom extra option"
+nullable = true
 
 [needs.fields.another_option]
 description = "Another custom option"
+default = ""
 
 [needs.fields.author]
 description = "Author of the need"
+nullable = true
 
 [needs.fields.comment]
 description = "Additional comments"
+nullable = true
 
 [needs.fields.amount]
 description = "Amount value"
@@ -92,18 +96,23 @@ schema.type = "integer"
 
 [needs.fields.image]
 description = "Image reference"
+nullable = true
 
 [needs.fields.config]
 description = "Configuration option"
+nullable = true
 
 [needs.fields.github]
 description = "GitHub reference"
+nullable = true
 
 [needs.fields.value]
 description = "General value field"
+nullable = true
 
 [needs.fields.unit]
 description = "Unit specification"
+nullable = true
 
 [[needs.types]]
 directive = "int"

diff --git a/sphinx_needs/needs.py b/sphinx_needs/needs.py
@@ -909,14 +909,34 @@ def create_schema(app: Sphinx, env: BuildEnvironment, _docnames: list[str]) -> N
 
     for name, field_data in _NEEDS_CONFIG.fields.items():
         try:
+            back_compatible = field_data.source in {
+                "needs_extra_options",
+                "add_extra_option",
+            }
+            if (
+                not back_compatible
+                and field_data.schema is None
+                and field_data.default is None
+                and field_data.nullable is None
+            ):
+                log_warning(
+                    LOGGER,
+                    f"Field {name!r} (from {field_data.source}) has no 'schema', 'nullable' or 'default' defined, "
+                    "which defaults to a string schema with nullable=True and no default. "
+                    "To aide with backward compatibility please define at least one.",
+                    "config",
+                    None,
+                )
+
             _schema = (
                 deepcopy(field_data.schema)  # type: ignore[arg-type]
                 if field_data.schema is not None
                 else {"type": "string"}
             )
+            nullable = True
             if field_data.nullable is not None:
                 nullable = field_data.nullable
-            else:
+            elif back_compatible:
                 # follows that of legacy (pre-schema) extra option,
                 # i.e. nullable if schema is defined
                 nullable = field_data.schema is not None
@@ -936,7 +956,7 @@ def create_schema(app: Sphinx, env: BuildEnvironment, _docnames: list[str]) -> N
                 # note, default follows that of legacy (pre-schema) extra option,
                 # i.e. default to "" only if no schema is defined
                 default=None
-                if field_data.schema is not None
+                if not back_compatible or field_data.schema is not None
                 else FieldLiteralValue(""),
                 allow_defaults=True,
                 allow_extend=True,

diff --git a/tests/__snapshots__/test_api_usage.ambr b/tests/__snapshots__/test_api_usage.ambr
@@ -286,7 +286,10 @@
               'default': 'hallo',
               'description': 'My extra field',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'params': dict({
               'default': None,

diff --git a/tests/__snapshots__/test_dynamic_functions.ambr b/tests/__snapshots__/test_dynamic_functions.ambr
@@ -553,10 +553,13 @@
               ]),
             }),
             'test_func': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'title': dict({
               'description': 'Title of the need.',

diff --git a/tests/__snapshots__/test_external.ambr b/tests/__snapshots__/test_external.ambr
@@ -767,16 +767,22 @@
               ]),
             }),
             'extra1': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'extra2': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'has_dead_links': dict({
               'default': False,

diff --git a/tests/__snapshots__/test_extra_options.ambr b/tests/__snapshots__/test_extra_options.ambr
@@ -214,16 +214,22 @@
               ]),
             }),
             'impacts': dict({
-              'default': '',
+              'default': None,
               'description': 'What is the impact of this need?',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'introduced': dict({
-              'default': '',
+              'default': None,
               'description': 'When was this need introduced?',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'is_external': dict({
               'default': False,
@@ -312,10 +318,13 @@
               'type': 'integer',
             }),
             'modified': dict({
-              'default': '',
+              'default': None,
               'description': 'When was this need last modified?',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'params': dict({
               'default': None,

diff --git a/tests/__snapshots__/test_field_defaults.ambr b/tests/__snapshots__/test_field_defaults.ambr
@@ -139,10 +139,13 @@
               ]),
             }),
             'bad_value_type': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'closed_at': dict({
               'default': None,
@@ -457,30 +460,46 @@
               'default': 'test_global',
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'option_2': dict({
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'option_3': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'option_4': dict({
               'default': 'STATUS_UNKNOWN',
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'option_5': dict({
               'default': 'final',
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'params': dict({
               'default': None,
@@ -673,10 +692,13 @@
               'type': 'string',
             }),
             'too_many_params': dict({
-              'default': '',
+              'default': None,
               'description': 'Added by needs_fields config',
               'field_type': 'extra',
-              'type': 'string',
+              'type': list([
+                'string',
+                'null',
+              ]),
             }),
             'type': dict({
               'default': '',
@@ -741,7 +763,7 @@
       ),
     }),
     'bad_value_type': dict({
-      'default': FieldLiteralValue(value=''),
+      'default': None,
       'predicate_defaults': tuple(
       ),
     }),
@@ -839,7 +861,7 @@
       ),
     }),
     'option_3': dict({
-      'default': FieldLiteralValue(value=''),
+      'default': None,
       'predicate_defaults': tuple(
         tuple(
           'status == "implemented"',
@@ -943,7 +965,7 @@
       ),
     }),
     'too_many_params': dict({
-      'default': FieldLiteralValue(value=''),
+      'default': None,
       'predicate_defaults': tuple(
       ),
     }),

diff --git a/tests/doc_test/add_sections_sigs/conf.py b/tests/doc_test/add_sections_sigs/conf.py
@@ -4,9 +4,9 @@
 needs_json_remove_defaults = True
 
 needs_fields = {
-    "introduced": {},
-    "updated": {},
-    "impacts": {},
+    "introduced": {"nullable": True},
+    "updated": {"nullable": True},
+    "impacts": {"nullable": True},
 }
 
 needs_template_collapse = """

diff --git a/tests/doc_test/doc_df_check_linked_values/conf.py b/tests/doc_test/doc_df_check_linked_values/conf.py
@@ -31,4 +31,4 @@
     },
 ]
 
-needs_fields = {"test_func": {}, "hours": {}}
+needs_fields = {"test_func": {"nullable": True}, "hours": {"nullable": True}}
diff --git a/tests/doc_test/doc_df_user_functions/conf.py b/tests/doc_test/doc_df_user_functions/conf.py
@@ -31,7 +31,7 @@
     },
 ]
 
-needs_fields = {"test_func": {}, "hours": {}}
+needs_fields = {"test_func": {"nullable": True}, "hours": {"nullable": True}}
 
 
 def my_own_function(app, need, needs):

diff --git a/tests/doc_test/doc_dynamic_functions/conf.py b/tests/doc_test/doc_dynamic_functions/conf.py
@@ -31,7 +31,7 @@
     },
 ]
 
-needs_fields = {"test_func": {}}
+needs_fields = {"test_func": {"nullable": True}}
 
 needs_build_json = True
 needs_json_remove_defaults = True
diff --git a/tests/doc_test/doc_field_defaults/conf.py b/tests/doc_test/doc_field_defaults/conf.py
@@ -46,7 +46,10 @@
     "layout": {"default": "clean_l"},
     "option_1": {"default": "test_global"},
     "option_2": {"default": "[[copy('id')]]"},
-    "option_3": {"predicates": [('status == "implemented"', "STATUS_IMPL")]},
+    "option_3": {
+        "nullable": True,
+        "predicates": [('status == "implemented"', "STATUS_IMPL")],
+    },
     "option_4": {
         "default": "STATUS_UNKNOWN",
         "predicates": [('status == "closed"', "STATUS_CLOSED")],
@@ -59,7 +62,7 @@
         "default": "final",
     },
     "bad_value_type": {"default": 1.27},
-    "too_many_params": {"predicates": [("a", "b", "c", "d")]},
+    "too_many_params": {"nullable": True, "predicates": [("a", "b", "c", "d")]},
 }
 
 needs_build_json = True

diff --git a/tests/doc_test/doc_global_options/conf.py b/tests/doc_test/doc_global_options/conf.py
@@ -27,13 +27,13 @@
 ]
 
 needs_fields = {
-    "option_1": {},
-    "option_2": {},
-    "option_3": {},
-    "option_4": {},
-    "option_5": {},
-    "bad_value_type": {},
-    "too_many_params": {},
+    "option_1": {"nullable": True},
+    "option_2": {"nullable": True},
+    "option_3": {"nullable": True},
+    "option_4": {"nullable": True},
+    "option_5": {"nullable": True},
+    "bad_value_type": {"nullable": True},
+    "too_many_params": {"nullable": True},
 }
 
 needs_global_options = {

diff --git a/tests/doc_test/doc_layout/conf.py b/tests/doc_test/doc_layout/conf.py
@@ -31,7 +31,7 @@
     },
 ]
 
-needs_fields = {"author": {}, "author_image": {}}
+needs_fields = {"author": {"nullable": True}, "author_image": {"nullable": True}}
 
 
 needs_layouts = {

diff --git a/tests/doc_test/doc_needpie/conf.py b/tests/doc_test/doc_needpie/conf.py
@@ -38,4 +38,4 @@
     },
 ]
 
-needs_fields = {"author": {}}
+needs_fields = {"author": {"nullable": True}}
diff --git a/tests/doc_test/doc_needreport/conf.py b/tests/doc_test/doc_needreport/conf.py
@@ -1,5 +1,5 @@
 extensions = ["sphinx_needs"]
-needs_fields = {"other": {}}
+needs_fields = {"other": {"nullable": True}}
 needs_render_context = {
     "report_directive": "admonition",
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -31,4 +31,4 @@ @@
         },
     ]
-    needs_fields = {"test_func": {}, "hours": {}}
+    needs_fields = {"test_func": {"nullable": True}, "hours": {"nullable": True}}