diff --git a/docs/learnservice_oas.yaml b/docs/learnservice_oas.yaml
index 96856f5..b7a0daa 100644
--- a/docs/learnservice_oas.yaml
+++ b/docs/learnservice_oas.yaml
@@ -62,7 +62,7 @@ x-kong-name: awesome_learnservice
 # the service and upstream objects in Kong. If not given it will use the 'info.title'
 # field above to name them, or a random UUID if the 'info.title' field is misssing.
 # Names are converted into valid identifiers. For example,
-# "Learn Service" becomes "Learn_Service".
+# "Learn Services" becomes "learn-services".
 # This directive can also be used on "path" and "operation" objects to name them.
 # Similar to operationId, each x-kong-name must be unique within the spec file.
 
@@ -125,14 +125,12 @@ paths:
       summary: Upsert tracks
       operationId: upsertTracks
       # Kong routes are generated from the top-level Service name (x-kong-name or info.title
-      # if x-kong-name is not set), and then the operationId gets appended (with '-' as separator)
-      # so the generated route name here is "awesome_learnservice-upserttracks".
+      # if x-kong-name is not set), and then the operationId gets appended (with '_' as separator)
+      # so the generated route name here is "awesome-learnservice_upserttracks"
       # If operationId is not specified, the default name will be the global x-kong-name
-      # with the path name and operation type. On this level the operationId can also be overridden
-      # by an x-kong-name directive.
-      # [specname]-[x-kong-name(operation)]               - if x-kong-name is provided on operation level
-      # [specname]-[operationId]                          - if operationId is provided (and no x-kong-name)
-      # [specname]-[x-kong-name(path) | path]-[operation] - if neither is provided
+      # with the path name and operation type.
+      # [specname]_[operationId]
+      # [specname]_[x-kong-name on path level]_[operation] --> if no "operationId" provided
       # where [specname] is the x-kong-name on global level (or in its absence "info.title")
       x-kong-plugin-request-termination:
         # the "x-kong-plugin-<plugin name>" directive can be used to add plugins