From 9ee291afd9ae63327a5474e075c9de7e5c1b807b Mon Sep 17 00:00:00 2001 From: Hans-Joachim Krauch Date: Wed, 25 Oct 2023 18:07:06 -0300 Subject: [PATCH 1/3] spec: Allow specifying service schema names & encodings --- docs/spec.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index e1c80b51..02c3d884 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -206,8 +206,14 @@ Informs the client about available services. Only supported if the server declar - `id`: number. The server may reuse ids when services disappear and reappear, but only if the services keeps the exact same name, type, and schema. Clients will use this unique id to cache schema info and deserialization routines. - `name`: string - `type`: string - - `requestSchema`: string - - `responseSchema`: string + - `requestSchema`: string (schema data only) or object with the fields below. If given as string, schema name and encoding will be derived from `type` (by appending `_Request`) and the previously advertised [supportedEncodings](#server-info). + - `name`: string + - `encoding`: string + - `data`: string + - `responseSchema`: string (schema data only) or object with the fields below. If given as string, schema name and encoding will be derived from `type` (by appending `_Response`) and the previously advertised [supportedEncodings](#server-info). + - `name`: string + - `encoding`: string + - `data`: string #### Example @@ -218,9 +224,16 @@ Informs the client about available services. Only supported if the server declar { "id": 1, "name": "foo", - "type": "std_srvs/srv/Empty", + "type": "std_srvs/Empty", "requestSchema": "", "responseSchema": "" + }, + { + "id": 2, + "name": "set_bool", + "type": "std_srvs/SetBool", + "requestSchema": { "name": "std_srvs/SetBool_Request", "encoding": "ros1msg", "data": "bool data" }, + "responseSchema": { "name": "std_srvs/SetBool_Response", "encoding": "ros1msg", "data": "bool success\nstring message" } } ] } From b24e5ea4bbf2a565e6fbc4de26cb6a028c50ce17 Mon Sep 17 00:00:00 2001 From: Hans-Joachim Krauch Date: Thu, 26 Oct 2023 12:26:04 -0300 Subject: [PATCH 2/3] comments --- docs/spec.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index 02c3d884..fced3fae 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -206,14 +206,19 @@ Informs the client about available services. Only supported if the server declar - `id`: number. The server may reuse ids when services disappear and reappear, but only if the services keeps the exact same name, type, and schema. Clients will use this unique id to cache schema info and deserialization routines. - `name`: string - `type`: string - - `requestSchema`: string (schema data only) or object with the fields below. If given as string, schema name and encoding will be derived from `type` (by appending `_Request`) and the previously advertised [supportedEncodings](#server-info). - - `name`: string + - `requestSchema`: string, required if `request` is not given. Field is present for backwards compatibilty, prefer using `request` instead. + - `request`: object, required if `requestSchema` is not given. - `encoding`: string - - `data`: string - - `responseSchema`: string (schema data only) or object with the fields below. If given as string, schema name and encoding will be derived from `type` (by appending `_Response`) and the previously advertised [supportedEncodings](#server-info). - - `name`: string + - `schemaName`: string + - `schemaEncoding`: string + - `schema`: string + - `responseSchema`: string, required if `response` is not given. Field is present for backwards compatibilty, prefer using `response` instead. + - `response`: object, required if `responseSchema` is not given. - `encoding`: string - - `data`: string + - `schemaName`: string + - `schemaEncoding`: string + - `schema`: string + #### Example @@ -232,8 +237,8 @@ Informs the client about available services. Only supported if the server declar "id": 2, "name": "set_bool", "type": "std_srvs/SetBool", - "requestSchema": { "name": "std_srvs/SetBool_Request", "encoding": "ros1msg", "data": "bool data" }, - "responseSchema": { "name": "std_srvs/SetBool_Response", "encoding": "ros1msg", "data": "bool success\nstring message" } + "request": { "encoding": "ros1", "schemaName": "std_srvs/SetBool_Request", "schemaEncoding": "ros1msg", "schema": "bool data" }, + "response": { "encoding": "ros1", "schemaName": "std_srvs/SetBool_Response", "schemaEncoding": "ros1msg", "schema": "bool success\nstring message" } } ] } From d099476126900eacb8de76ed48c6cee750e2d06e Mon Sep 17 00:00:00 2001 From: Hans-Joachim Krauch Date: Fri, 3 Nov 2023 13:03:31 -0300 Subject: [PATCH 3/3] improve field documentation --- docs/spec.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index fced3fae..04a96e3d 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -204,20 +204,20 @@ Informs the client about available services. Only supported if the server declar - `op`: string `"advertiseServices"` - `services`: array of: - `id`: number. The server may reuse ids when services disappear and reappear, but only if the services keeps the exact same name, type, and schema. Clients will use this unique id to cache schema info and deserialization routines. - - `name`: string - - `type`: string - - `requestSchema`: string, required if `request` is not given. Field is present for backwards compatibilty, prefer using `request` instead. - - `request`: object, required if `requestSchema` is not given. - - `encoding`: string - - `schemaName`: string - - `schemaEncoding`: string - - `schema`: string - - `responseSchema`: string, required if `response` is not given. Field is present for backwards compatibilty, prefer using `response` instead. - - `response`: object, required if `responseSchema` is not given. - - `encoding`: string - - `schemaName`: string - - `schemaEncoding`: string - - `schema`: string + - `name`: string, name used to identify the service. + - `type`: string, type of the service. May be used to derive request & response schema names if `request` or `response` are not given. + - `request`: object describing the request. Required if `requestSchema` is not given. + - `encoding`: string, type of encoding used for request message encoding. + - `schemaName`: string, name of the request schema. + - `schemaEncoding`: string, type of encoding used for schema encoding. + - `schema`: string, schema definition in a format matching the `schemaEncoding`. + - `response`: object describing the response. Required if `responseSchema` is not given. + - `encoding`: string, type of encoding used for response message encoding. + - `schemaName`: string, name of the response schema. + - `schemaEncoding`: string, type of encoding used for schema encoding. + - `schema`: string, schema definition in a format matching the `schemaEncoding`. + - `requestSchema`: string | undefined, request schema definition. The schema encoding will be derived from the [`supportedEncodings`](#server-info) sent by the server. Required if `request` is not given. Field is present for backwards compatibilty, prefer using `request` instead. + - `responseSchema`: string | undefined, response schema definition. The schema encoding will be derived from the [`supportedEncodings`](#server-info) sent by the server. Required if `response` is not given. Field is present for backwards compatibilty, prefer using `response` instead. #### Example