Convert request bindings to gremlin-lang string format

Moving parameters from binary-serialized maps to string representations
makes the request side pure text, decoupling Gremlin language evolution
from GraphBinary versioning. New types can be introduced in minor/patch
versions without touching GraphBinary, eliminating the need for a major
version bump across the ecosystem for every new request-side type.

The asParameter() fallback is replaced with an unsupportedType flag that
records the class name and falls back to toString(). A flag is used
rather than throwing because embedded Traversals build GremlinLang as a
side effect but never send it, so unknown types must not break
execution.

Author: kenhuuu

CHANGELOG.asciidoc

@@ -25,6 +25,8 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 [[release-4-0-0]]
 === TinkerPop 4.0.0 (Release Date: NOT OFFICIALLY RELEASED YET)
 
+* Modified request parameters from `Map<String, Object>` to gremlin-lang compatible `String`.
+
 [[release-4-0-0-beta-2]]
 === TinkerPop 4.0.0-beta.2 (April 1, 2026)
 

docs/src/upgrade/release-4.x.x.asciidoc

@@ -30,6 +30,15 @@ image::gremlins-wildest-dreams.png[width=185]
 Please see the link:https://github.com/apache/tinkerpop/blob/4.0.0/CHANGELOG.asciidoc#release-4-0-0[changelog] for a
 complete list of all the modifications that are part of this release.
 
+=== Upgrading for Users
+
+==== Parameter Format
+
+Parameters have replaced bindings. Parameters are no longer `Map<String, Object>` instead they are `String`. The string is gremlin-lang map.
+
+Notably, because parameters now travel as maps, these maps must be gremlin-lang compatible. One of the things that aren't is
+`#jsr223` control flags. This means there will be gaps in gremlin-groovy support.
+
 == TinkerPop 4.0.0-beta.2
 
 *Release Date: April 1, 2026*

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/GremlinQueryParser.java

@@ -18,14 +18,17 @@
  */
 package org.apache.tinkerpop.gremlin.language.grammar;
 
-import org.antlr.v4.runtime.CharStream;
 import org.antlr.v4.runtime.CharStreams;
 import org.antlr.v4.runtime.CommonTokenStream;
 import org.antlr.v4.runtime.atn.PredictionMode;
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.util.Collection;
+import java.util.Map;
+import javax.lang.model.SourceVersion;
+
 /**
  * Parses Gremlin strings to an {@code Object}, typically to a {@link Traversal}.
  */
@@ -44,21 +47,15 @@ public static Object parse(final String query) {
      * Parse Gremlin string using a specified {@link GremlinAntlrToJava} object.
      */
     public static Object parse(final String query, final GremlinVisitor<Object> visitor)  {
-        final CharStream in = CharStreams.fromString(query);
-        final GremlinLexer lexer = new GremlinLexer(in);
-        lexer.removeErrorListeners();
-        lexer.addErrorListener(errorListener);
-
+        final GremlinLexer lexer = createLexer(query);
         final CommonTokenStream tokens = new CommonTokenStream(lexer);
 
         // Setup error handler on parser
-        final GremlinParser parser = new GremlinParser(tokens);
+        final GremlinParser parser = createParser(tokens);
         // SLL prediction mode is faster than the LL prediction mode when parsing the grammar,
         // but it does not cover parsing all types of input.  We use the SLL by default, and fallback
         // to LL mode if fails to parse the query.
         parser.getInterpreter().setPredictionMode(PredictionMode.SLL);
-        parser.removeErrorListeners();
-        parser.addErrorListener(errorListener);
 
         GremlinParser.QueryListContext queryContext;
         try {
@@ -91,4 +88,94 @@ public static Object parse(final String query, final GremlinVisitor<Object> visi
             throw new GremlinParserException("Failed to interpret Gremlin query: " + ex.getMessage(), ex);
         }
     }
+
+    /**
+     * Parses a gremlin-lang map literal string into a {@code Map<String, Object>} for use as parameters.
+     * <p>
+     * Uses {@link ParameterMapVisitor} to prevent traversal injection and validates that all keys are strings
+     * and no values contain traversals.
+     *
+     * @param parameterMapString the gremlin-lang map literal string (e.g. {@code [x:1,y:"marko"]}) or {@code null}/empty
+     * @return the parsed and validated parameter map
+     * @throws GremlinParserException if parsing fails or validation detects invalid content
+     */
+    public static Map<String, Object> parseParameters(final String parameterMapString) {
+        if (parameterMapString == null || parameterMapString.isEmpty()) {
+            return Map.of();
+        }
+
+        final GremlinParser parser = createParser(parameterMapString);
+        final GremlinParser.GenericMapLiteralContext mapCtx = parser.genericMapLiteral();
+
+        final ParameterMapVisitor visitor = new ParameterMapVisitor(new GremlinAntlrToJava());
+        final Map<Object, Object> rawMap = (Map<Object, Object>) visitor.visitGenericMapLiteral(mapCtx);
+
+        if (rawMap == null) {
+            return Map.of();
+        }
+
+        for (final Map.Entry<?, ?> entry : rawMap.entrySet()) {
+            if (!(entry.getKey() instanceof String)) {
+                throw new GremlinParserException(
+                        String.format("Parameter map keys must be String, found: %s",
+                                entry.getKey() == null ? "null" : entry.getKey().getClass().getSimpleName()));
+            }
+            final String key = (String) entry.getKey();
+            if (!SourceVersion.isIdentifier(key)) {
+                throw new GremlinParserException(
+                        String.format("Parameter map key must be a valid identifier: %s", key));
+            }
+            validateParameterValue(entry.getValue());
+        }
+
+        return (Map<String, Object>) (Map<?, ?>) rawMap;
+    }
+
+    /**
+     * Recursively validates that a parameter value does not contain a {@link Traversal}. Nested validation is needed
+     * because steps like mergeV iterate map values, so a Traversal hiding inside a nested map or collection would still
+     * be dangerous.
+     */
+    private static void validateParameterValue(final Object value) {
+        if (value instanceof Traversal) {
+            throw new GremlinParserException("Traversals are not allowed as parameter values");
+        }
+        if (value instanceof Map) {
+            for (final Object v : ((Map<?, ?>) value).values()) {
+                validateParameterValue(v);
+            }
+        }
+        if (value instanceof Collection) {
+            for (final Object v : (Collection<?>) value) {
+                validateParameterValue(v);
+            }
+        }
+    }
+
+    /**
+     * Creates a {@link GremlinParser} from the given input string.
+     */
+    private static GremlinParser createParser(final String input) {
+        return createParser(new CommonTokenStream(createLexer(input)));
+    }
+
+    /**
+     * Creates a {@link GremlinParser} from the given {@link GremlinLexer}.
+     */
+    private static GremlinParser createParser(final CommonTokenStream tokens) {
+        final GremlinParser parser = new GremlinParser(tokens);
+        parser.removeErrorListeners();
+        parser.addErrorListener(errorListener);
+        return parser;
+    }
+
+    /**
+     * Creates a {@link GremlinLexer} from the given input string with error listeners configured.
+     */
+    private static GremlinLexer createLexer(final String input) {
+        final GremlinLexer lexer = new GremlinLexer(CharStreams.fromString(input));
+        lexer.removeErrorListeners();
+        lexer.addErrorListener(errorListener);
+        return lexer;
+    }
 }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/ParameterMapVisitor.java

@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.tinkerpop.gremlin.language.grammar;
+
+/**
+ * A visitor for parsing parameter map strings that prevents traversal injection.
+ * <p>
+ * Extends {@link GenericLiteralVisitor} and overrides traversal-related visit methods
+ * to throw, ensuring that no traversal can be constructed or executed during the
+ * parameter map parsing walk. This is critical for security because
+ * {@code visitTerminatedTraversal} in the base class would execute the traversal
+ * immediately via {@link TraversalTerminalMethodVisitor}.
+ */
+public class ParameterMapVisitor extends GenericLiteralVisitor {
+
+    private static final int DEFAULT_MAX_NESTING_DEPTH = 32;
+
+    private final int maxNestingDepth;
+    private int currentNestingDepth = 0;
+
+    public ParameterMapVisitor(final GremlinAntlrToJava antlr) {
+        this(antlr, DEFAULT_MAX_NESTING_DEPTH);
+    }
+
+    public ParameterMapVisitor(final GremlinAntlrToJava antlr, final int maxNestingDepth) {
+        super(antlr);
+        this.maxNestingDepth = maxNestingDepth;
+    }
+
+    /**
+     * Overridden to prevent nested traversal construction in parameter maps.
+     */
+    @Override
+    public Object visitNestedTraversal(final GremlinParser.NestedTraversalContext ctx) {
+        throw new GremlinParserException("Traversals are not allowed in parameter maps");
+    }
+
+    /**
+     * Overridden to prevent terminated traversal execution in parameter maps.
+     * This is the critical override because the base class would execute the traversal
+     * immediately via {@link TraversalTerminalMethodVisitor}.
+     */
+    @Override
+    public Object visitTerminatedTraversal(final GremlinParser.TerminatedTraversalContext ctx) {
+        throw new GremlinParserException("Traversals are not allowed in parameter maps");
+    }
+
+    @Override
+    public Object visitGenericMapLiteral(final GremlinParser.GenericMapLiteralContext ctx) {
+        currentNestingDepth++;
+        if (currentNestingDepth > maxNestingDepth) {
+            throw new GremlinParserException("Parameter map nesting depth exceeds maximum of " + maxNestingDepth);
+        }
+        try {
+            return super.visitGenericMapLiteral(ctx);
+        } finally {
+            currentNestingDepth--;
+        }
+    }
+
+    @Override
+    public Object visitGenericCollectionLiteral(final GremlinParser.GenericCollectionLiteralContext ctx) {
+        currentNestingDepth++;
+        if (currentNestingDepth > maxNestingDepth) {
+            throw new GremlinParserException("Parameter map nesting depth exceeds maximum of " + maxNestingDepth);
+        }
+        try {
+            return super.visitGenericCollectionLiteral(ctx);
+        } finally {
+            currentNestingDepth--;
+        }
+    }
+
+    @Override
+    public Object visitGenericSetLiteral(final GremlinParser.GenericSetLiteralContext ctx) {
+        currentNestingDepth++;
+        if (currentNestingDepth > maxNestingDepth) {
+            throw new GremlinParserException("Parameter map nesting depth exceeds maximum of " + maxNestingDepth);
+        }
+        try {
+            return super.visitGenericSetLiteral(ctx);
+        } finally {
+            currentNestingDepth--;
+        }
+    }
+}