feat(s2dm): enhance pluralization handling and naming conventions in GraphQL schema generation

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

Author: jdacoello

docs/s2dm.md

@@ -82,9 +82,34 @@ The exporter handles all `vspec` data types as follows:
 - **Strings** → GraphQL String
 - **Numbers** → GraphQL Int, Float, or custom scalars (Int8, UInt16, etc.)
 - **Booleans** → GraphQL Boolean
-- **Arrays** → GraphQL Lists
+- **Arrays** → GraphQL Lists (with natural plural field names)
 - **Allowed values** → GraphQL Enums
 
+#### List Field Names (Automatic Pluralization)
+
+When VSS branches have instances (like `Seat` with multiple rows/positions), the parent type gets a list field. The S2DM exporter automatically generates **natural plural names** using the inflect library:
+
+- `seat` → `seats: [Vehicle_Cabin_Seat]`
+- `door` → `doors: [Vehicle_Cabin_Door]`
+- `window` → `windows: [Vehicle_Cabin_Window]`
+- `battery` → `batteries: [Vehicle_Battery]`
+- `mirror` → `mirrors: [Vehicle_Body_Mirror]`
+
+This improves GraphQL schema readability by following common naming conventions instead of using mechanical suffixes like `_s`.
+
+**Example:**
+```graphql
+type Vehicle_Cabin {
+  """Cabin seats for passengers."""
+  seats: [Vehicle_Cabin_Seat]
+
+  """Cabin doors."""
+  doors: [Vehicle_Cabin_Door]
+}
+```
+
+**Tracking:** All pluralized field names are logged to `vspec_reference/pluralized_field_names.yaml` showing the original VSS FQN, the plural field name used, and its location in the GraphQL schema.
+
 #### Enum Value Sanitization
 
 GraphQL enum values must follow strict naming rules (alphanumeric + underscore only, cannot start with a digit). The S2DM exporter automatically sanitizes VSS enum values to comply with GraphQL requirements:
@@ -113,6 +138,46 @@ enum Vehicle_Cabin_Seat_InstanceTag_Dimension2 {
 
 This ensures complete traceability between the VSS source and the generated GraphQL schema.
 
+### GraphQL Naming Convention Warnings
+
+GraphQL best practices recommend using **singular names for types** (e.g., `User` not `Users`, `Product` not `Products`). The S2DM exporter automatically detects VSS branches with plural names and generates warnings to help identify potential naming convention violations.
+
+**Detection:** The exporter uses the inflect library to identify potential plural type names. It maintains a whitelist of known exceptions (acronyms like "ADAS", "ABS", Latin words like "Status", "Chassis") to reduce false positives.
+
+**Warning Output:** When plural type names are detected, two files are generated in `vspec_reference/`:
+
+1. **`plural_type_warnings.yaml`** - Lists all detected plural type names:
+   ```yaml
+   # WARNING: These elements in the reference model seem to have a plural name...
+
+   Vehicle.Cabin.Lights:
+     singular: Light
+     currentNameInGraphQLModel: Vehicle_Cabin_Lights
+
+   Vehicle.Body.Mirrors:
+     singular: Mirror
+     currentNameInGraphQLModel: Vehicle_Body_Mirrors
+
+   # Whitelisted words (excluded from plural detection):
+   whitelisted_non_plurals:
+     - ADAS
+     - ABS
+     - Status
+     - Chassis
+     # ... etc
+   ```
+
+2. **Console warnings:** During export, warnings are logged for immediate visibility:
+   ```
+   WARNING: Type 'Vehicle_Cabin_Lights' uses potential plural name 'Lights'.
+            Suggested singular: 'Light' (VSS FQN: Vehicle.Cabin.Lights)
+   ```
+
+**Review Process:** These warnings help VSS maintainers identify:
+- **True plurals** - VSS branches that should be renamed to singular form
+- **False positives** - Words that end in 's' but aren't actually plural (add to whitelist)
+- **Acceptable exceptions** - Cases where plural names are intentional
+
 ### VSS Instances Become GraphQL Structures
 When your `vspec` has instances (like multiple seats), the exporter creates proper GraphQL types:
 
@@ -186,7 +251,9 @@ myOutput/
     ├── README.md                   # Documentation and provenance info
     ├── vspec_lookup_spec.yaml      # Complete VSS tree (fully expanded)
     ├── vspec_units.yaml            # Units used (if provided via -u or implicit)
-    └── vspec_quantities.yaml       # Quantities used (if provided via -q or implicit)
+    ├── vspec_quantities.yaml       # Quantities used (if provided via -q or implicit)
+    ├── plural_type_warnings.yaml   # Plural type names detected (if any)
+    └── pluralized_field_names.yaml # Fields changed to plural form (if any instances)
 ```
 
 ### VSS Reference Files
@@ -197,11 +264,14 @@ The `vspec_reference/` directory provides complete traceability:
 - **vspec_lookup_spec.yaml** - Complete VSS specification tree (fully processed and expanded) in YAML format
 - **vspec_units.yaml** - Unit definitions used during generation (included if units were provided via `-u` flag or implicitly loaded)
 - **vspec_quantities.yaml** - Quantity definitions used during generation (included if quantities were provided via `-q` flag or implicitly loaded)
+- **plural_type_warnings.yaml** - VSS branches with plural type names that may violate GraphQL naming conventions (generated if any detected)
+- **pluralized_field_names.yaml** - Fields whose names were changed to plural form for list fields (generated if any instances exist)
 
 These files allow you to:
 1. Trace GraphQL elements back to their VSS source using the FQN in `@vspec` directives
 2. Reproduce the exact GraphQL schema by re-running the exporter
 3. Understand which input files were used for generation
+4. Review naming convention warnings and pluralization changes
 
 
 

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "graphene>=3.4.3",
     "pandas>=2.2.3",
     "case-converter>=1.2.0",
+    "inflect>=7.4.0",
 ]
 authors = [
 {name="COVESA VSS", email="covesa-dev@covesa.global"}

src/vss_tools/exporters/s2dm/__init__.py

@@ -109,29 +109,31 @@ def cli(
         log.info("Generating S2DM GraphQL schema...")
 
         # Generate the schema
-        schema, unit_enums_metadata, allowed_enums_metadata, vspec_comments = generate_s2dm_schema(
+        schema, unit_enums_metadata, allowed_enums_metadata, mapping_metadata = generate_s2dm_schema(
             tree, data_type_tree, extended_attributes=extended_attributes
         )
 
         if modular:
             # Write modular files
             write_modular_schema(
-                schema, unit_enums_metadata, allowed_enums_metadata, vspec_comments, output_dir, flat_domains
+                schema, unit_enums_metadata, allowed_enums_metadata, mapping_metadata, output_dir, flat_domains
             )
             log.info(f"Modular GraphQL schema written to {output_dir}/")
         else:
             # Single file export: write to outputDir/outputDir.graphql
             graphql_file = output_dir / f"{output_dir.name}.graphql"
             full_schema_str = print_schema_with_vspec_directives(
-                schema, unit_enums_metadata, allowed_enums_metadata, vspec_comments
+                schema, unit_enums_metadata, allowed_enums_metadata, mapping_metadata
             )
             with open(graphql_file, "w") as outfile:
                 outfile.write(full_schema_str)
 
             log.info(f"GraphQL schema written to {graphql_file}")
 
         # Generate VSS reference files (will check for implicit files)
-        generate_vspec_reference(tree, data_type_tree, output_dir, extended_attributes, vspec, units, quantities)
+        generate_vspec_reference(
+            tree, data_type_tree, output_dir, extended_attributes, vspec, units, quantities, mapping_metadata
+        )
 
     except S2DMExporterException as e:
         log.error(e)

src/vss_tools/exporters/s2dm/reference_generator.py

@@ -34,6 +34,7 @@ def generate_vspec_reference(
     vspec_file: Path,
     units_files: tuple[Path, ...],
     quantities_files: tuple[Path, ...],
+    mapping_metadata: dict[str, dict] | None = None,
 ) -> None:
     """
     Generate VSS reference files alongside GraphQL output.
@@ -49,6 +50,7 @@ def generate_vspec_reference(
         vspec_file: Path to vspec file (to find implicit units/quantities)
         units_files: Unit files from CLI
         quantities_files: Quantity files from CLI
+        mapping_metadata: Optional metadata including plural type warnings
 
     Raises:
         S2DMExporterException: If reference file generation fails
@@ -152,8 +154,58 @@ def generate_vspec_reference(
             except (PermissionError, OSError) as e:
                 raise S2DMExporterException(f"Failed to write quantities file {quantities_output}: {e}") from e
 
+        # Write plural type warnings if any were collected
+        if mapping_metadata and mapping_metadata.get("plural_type_warnings"):
+            warnings_output = reference_dir / "plural_type_warnings.yaml"
+            try:
+                with open(warnings_output, "w") as f:
+                    # Write header comment
+                    f.write(
+                        "# WARNING: These elements in the reference model seem to have a plural name, "
+                        "while GraphQL best practices suggest the use of the singular form for type names.\n"
+                    )
+                    f.write("# Consider replacing plural forms and whitelisting false positives.\n\n")
+
+                    # Write each warning as FQN with nested fields
+                    for warning in mapping_metadata["plural_type_warnings"]:
+                        f.write(f"{warning['fqn']}:\n")
+                        f.write(f"  suggested_singular: {warning['suggested_singular']}\n")
+                        f.write(f"  current_name_in_graphql_model: {warning['type_name']}\n")
+                        f.write("\n")
+
+                warning_count = len(mapping_metadata["plural_type_warnings"])
+                log.info(f"  - Plural warnings: {warnings_output.name} ({warning_count} warning(s))")
+            except (PermissionError, OSError) as e:
+                raise S2DMExporterException(f"Failed to write plural warnings file {warnings_output}: {e}") from e
+
+        # Write pluralized field names if any were collected
+        if mapping_metadata and mapping_metadata.get("pluralized_field_names"):
+            pluralized_output = reference_dir / "pluralized_field_names.yaml"
+            try:
+                with open(pluralized_output, "w") as f:
+                    # Write header comment
+                    f.write(
+                        "# Following names were changed to their plural form as they resolve to an output type "
+                        "with a List type modifier.\n\n"
+                    )
+
+                    # Write each pluralized field as FQN with nested fields
+                    for entry in mapping_metadata["pluralized_field_names"]:
+                        f.write(f"{entry['fqn']}:\n")
+                        f.write(f"  plural_field_name: {entry['plural_field_name']}\n")
+                        f.write(f"  path_in_graphql_model: {entry['path_in_graphql_model']}\n")
+                        f.write("\n")
+
+                log.info(
+                    f"  - Pluralized fields: {pluralized_output.name} "
+                    f"({len(mapping_metadata['pluralized_field_names'])} field(s))"
+                )
+            except (PermissionError, OSError) as e:
+                raise S2DMExporterException(f"Failed to write pluralized fields file {pluralized_output}: {e}") from e
+
         # Generate README.md for provenance documentation
-        generate_reference_readme(reference_dir, vspec_file, actual_units, actual_quantities)
+        has_plural_warnings = mapping_metadata and bool(mapping_metadata.get("plural_type_warnings"))
+        generate_reference_readme(reference_dir, vspec_file, actual_units, actual_quantities, has_plural_warnings)
 
     except S2DMExporterException:
         # Re-raise our custom exceptions
@@ -168,6 +220,7 @@ def generate_reference_readme(
     vspec_file: Path,
     units_files: tuple[Path, ...] | None,
     quantities_files: tuple[Path, ...] | None,
+    has_plural_warnings: bool = False,
 ) -> None:
     """
     Generate README.md documenting the provenance of reference files.
@@ -177,6 +230,7 @@ def generate_reference_readme(
         vspec_file: Original vspec input file
         units_files: Units files used (explicit or implicit)
         quantities_files: Quantities files used (explicit or implicit)
+        has_plural_warnings: Whether plural type warnings were generated
 
     Raises:
         S2DMExporterException: If README generation fails
@@ -211,6 +265,10 @@ def generate_reference_readme(
             readme_content += """
 * **vspec_quantities.yaml** - Quantity definitions categorizing measurements."""
 
+        if has_plural_warnings:
+            readme_content += """
+* **plural_type_warnings.txt** - VSS branches with plural type names (GraphQL prefers singular)."""
+
         readme_content += """
 
 ## Documentation

src/vss_tools/exporters/s2dm/type_builders.py

@@ -22,6 +22,7 @@
 from typing import Any
 
 import caseconverter
+import inflect
 import pandas as pd
 from graphql import (
     GraphQLArgument,
@@ -64,6 +65,42 @@ def _extract_extended_attributes(row: pd.Series, extended_attributes: tuple[str,
     return extracted
 
 
+# Initialize inflect engine for pluralization (singleton)
+_inflect_engine = inflect.engine()
+
+
+def _check_and_collect_plural_type_name(
+    converted_type_name: str, fqn: str, original_name: str, plural_name_warnings: dict[str, dict[str, Any]]
+) -> None:
+    """
+    Check if a name appears to be plural and collect for reporting.
+
+    Uses inflect library to detect potential plural forms. Reports all cases where
+    a singular form is detected, without filtering. This allows downstream tools
+    to decide which cases are true issues vs. acceptable exceptions.
+
+    Args:
+        converted_type_name: The converted type name (for schema)
+        fqn: The fully qualified VSS name for context
+        original_name: The original VSS branch/struct name (before conversion)
+        plural_name_warnings: Dictionary to store metadata (adds to "plural_type_warnings" key)
+    """
+    # Check if inflect detects a singular form
+    # Returns False if already singular, or the singular form if plural
+    singular = _inflect_engine.singular_noun(original_name)
+
+    if singular:
+        plural_name_warnings.setdefault("plural_type_warnings", []).append(
+            {"type_name": converted_type_name, "fqn": fqn, "plural_word": original_name, "suggested_singular": singular}
+        )
+
+        # Also log to console for immediate visibility
+        log.warning(
+            f"Type '{converted_type_name}' uses potential plural name '{original_name}'. "
+            f"Suggested singular: '{singular}' (VSS FQN: {fqn})"
+        )
+
+
 def create_unit_enums() -> tuple[dict[str, GraphQLEnumType], dict[str, dict[str, dict[str, str]]]]:
     """
     Create GraphQL enum types for VSS units grouped by quantity.
@@ -415,8 +452,13 @@ def create_object_type(
         GraphQL object type for the branch
     """
     branch_row = branches_df.loc[fqn]
+    original_name = branch_row["name"]
     type_name = convert_name_for_graphql_schema(fqn, GraphQLElementType.TYPE, S2DM_CONVERSIONS)
 
+    # Check if branch name is plural and collect for reporting
+    # Pass original VSS branch name (before any conversion)
+    _check_and_collect_plural_type_name(type_name, fqn, original_name, vspec_comments)
+
     def get_fields() -> dict[str, GraphQLField]:
         fields = {}
 
@@ -478,7 +520,15 @@ def get_fields() -> dict[str, GraphQLField]:
             fields.update(hoisted_fields)
 
             if child_row.get("instances"):
-                fields[f"{field_name}_s"] = GraphQLField(GraphQLList(child_type))
+                # Use natural plural form for list fields (using inflect directly)
+                plural_field_name = _inflect_engine.plural(field_name)
+                fields[plural_field_name] = GraphQLField(GraphQLList(child_type))
+
+                # Collect pluralized field name for reporting
+                field_path = build_field_path(type_name, plural_field_name)
+                vspec_comments.setdefault("pluralized_field_names", []).append(
+                    {"fqn": child_fqn, "plural_field_name": plural_field_name, "path_in_graphql_model": field_path}
+                )
             else:
                 fields[field_name] = GraphQLField(child_type)
 

tests/test_s2dm_exporter.py

@@ -16,6 +16,7 @@
     get_metadata_df,
     print_schema_with_vspec_directives,
 )
+from vss_tools.exporters.s2dm.type_builders import _sanitize_enum_value_for_graphql
 from vss_tools.main import get_trees
 from vss_tools.utils.graphql_utils import GraphQLElementType, convert_name_for_graphql_schema
 
@@ -308,8 +309,8 @@ def test_instance_tag_support(self):
         assert "id: ID!" in sdl
 
         # Verify the complete structure matches the reference pattern
-        # The seat should be a list field (seat_s) because it has instances
-        assert "seat_s: [Vehicle_Cabin_Seat]" in sdl
+        # The seat should be a list field (seats) with natural plural because it has instances
+        assert "seats: [Vehicle_Cabin_Seat]" in sdl
 
     def test_allowed_value_enums_generation(self):
         """Test that allowed value enums are generated correctly."""
@@ -536,13 +537,11 @@ def test_non_instantiated_property_hoisting(self, tmp_path: Path):
         assert "someSignal" in cabin_type_content
         # Verify it has the instantiate=false metadata
         assert 'metadata: [{key: "instantiate", value: "false"}]' in cabin_type_content
-        # And door_s array field should also be there
-        assert "door_s" in cabin_type_content
+        # And doors array field should also be there (natural plural)
+        assert "doors" in cabin_type_content
 
     def test_enum_value_sanitization_with_spaces(self):
-        """Test that enum values with spaces are properly sanitized and annotated."""
-        from vss_tools.exporters.s2dm.type_builders import _sanitize_enum_value_for_graphql
-
+        """Test that enum values with spaces are sanitized correctly."""
         # Test the sanitization function
         assert _sanitize_enum_value_for_graphql("some value") == ("SOME_VALUE", True)
         assert _sanitize_enum_value_for_graphql("SOME VALUE") == ("SOME_VALUE", True)