Skip to content

Commit 9f81c6d

Browse files
eeberhardeeberhard
authored
feat(schema): use versioned common interfaces schema (#205)
* feat(schema): add static bundled draft/1-0-0 common interfaces * feat(schema): reference draft common interfaces schema * docs: update schema links to use static versioned schemas
1 parent f1b308a commit 9f81c6d

File tree

5 files changed

+343
-20
lines changed

5 files changed

+343
-20
lines changed

‎docs/docs/reference/custom-components/03-component-descriptions.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,9 @@ Components have various interfaces that need to be described:
2020
Aside from interfaces, a component description should also include information on the type of component (regular or
2121
lifecycle), the general component behavior or purpose, and other metadata such as name and registration details.
2222

23-
<!-- FIXME: link to the schema on GitHub once it is on main; relative paths will break if the doc is versioned -->
2423
The elements of a component description are written as a standardized JSON file for each component. The expected
2524
structure of the component description is defined by
26-
the [Component Description JSON schema](../../../../schemas/component-descriptions/schema/component.schema.json)
25+
the [Component Description JSON schema](../../../static/schemas/1-1-1/component.schema.json)
2726

2827
:::info
2928

@@ -101,9 +100,8 @@ components, as they provide no meaningful behavior if directly instantiated.
101100

102101
## Signals
103102

104-
<!-- FIXME: link to the schema on GitHub once it is on main; relative paths will break if the doc is versioned -->
105103
The expected structure of the signal description is defined by
106-
the [Signal Description JSON schema](../../../../schemas/interfaces/schema/common/signal.schema.json).
104+
the [Signal Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal).
107105

108106
Component inputs and outputs are described with a signal name and type, matching the name and type in the implementation
109107
when using the respective `add_input` or `add_output` function. Additionally, a human-readable display name and
@@ -134,16 +132,16 @@ An example description of a component with one input and one output, both as joi
134132

135133
## Parameters
136134

137-
<!-- FIXME: link to the schemas on GitHub once they are on main; relative paths will break if the doc is versioned -->
138135
The expected structure of the parameter description is defined by
139-
the [Parameter Description JSON schema](../../../../schemas/interfaces/schema/common/parameter.schema.json).
136+
the [Parameter Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter).
140137

141138
Parameters contain a value of a certain type, described by the `parameter_type` property. Valid parameter types are
142-
defined in the [Parameter Type JSON schema](../../../../schemas/interfaces/schema/common/parameter_type.schema.json).
139+
defined in
140+
the [Parameter Type JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter_type).
143141

144142
If the `parameter_type` property is `state`, then the `parameter_state_type` property must also be defined as a member
145143
of the enumeration
146-
in [Encoded State Type JSON schema](../../../../schemas/interfaces/schema/common/encoded_state_type.schema.json).
144+
in [Encoded State Type JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/encoded_state_type.schema.json).
147145

148146
Parameters generally have a default value which renders them optional in some cases. When a parameter has no valid
149147
default state and must be set by the user for the component to function, the `default_value` property in the component
@@ -177,6 +175,9 @@ An example parameter description is shown below.
177175

178176
## Predicates
179177

178+
The expected structure of the predicate description is defined by
179+
the [Predicate Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/predicate).
180+
180181
Predicates are crucial to drive the event logic of the Dynamic State Engine, but they are very simple to declare
181182
and describe. Each predicate of a component indicates a particular run-time state or configuration that is either
182183
"true" or "false". In the implementation, a predicate is a publisher with a boolean type. The component is responsible
@@ -201,6 +202,9 @@ An example predicate description is shown below.
201202

202203
## Services
203204

205+
The expected structure of the service description is defined by
206+
the [Service Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/service).
207+
204208
Services are endpoints provided by a component that can trigger certain behaviours. In the backend implementation,
205209
they are created as ROS2 services with a specific `service_name` using one of two service message types. The first
206210
type is simply an empty trigger service that has no payload, which is the default case. The second type is a trigger

‎docs/static/schemas/draft/1-0-0/interfaces.schema.json

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
{
2+
"$id": "/draft/1-0-0/interfaces.schema.json",
3+
"$schema": "https://json-schema.org/draft/2020-12/schema",
4+
"title": "Common Interfaces",
5+
"description": "This schema includes definitions for common interfaces across the AICA System",
6+
"$defs": {
7+
"encoded_state_type": {
8+
"$schema": "https://json-schema.org/draft/2020-12/schema",
9+
"title": "Encoded State Type",
10+
"description": "The state type of an encoded value from a collection of supported types, as defined in clproto.",
11+
"type": "string",
12+
"enum": [
13+
"state",
14+
"spatial_state",
15+
"cartesian_state",
16+
"cartesian_pose",
17+
"cartesian_twist",
18+
"cartesian_acceleration",
19+
"cartesian_wrench",
20+
"jacobian",
21+
"joint_state",
22+
"joint_positions",
23+
"joint_velocities",
24+
"joint_accelerations",
25+
"joint_torques",
26+
"shape",
27+
"ellipsoid",
28+
"parameter",
29+
"digital_io_state",
30+
"analog_io_state"
31+
]
32+
},
33+
"parameter": {
34+
"$schema": "https://json-schema.org/draft/2020-12/schema",
35+
"title": "Parameter",
36+
"description": "A dynamic parameter that is publicly configurable.",
37+
"type": "object",
38+
"additionalProperties": false,
39+
"properties": {
40+
"display_name": {
41+
"description": "The human-readable parameter name.",
42+
"examples": [
43+
"Reference Frame",
44+
"Gain"
45+
],
46+
"type": "string"
47+
},
48+
"description": {
49+
"description": "A brief description of the parameter.",
50+
"type": "string"
51+
},
52+
"parameter_name": {
53+
"description": "The lower_snake_case parameter name as it is declared in the implementation.",
54+
"examples": [
55+
"reference_frame",
56+
"gain"
57+
],
58+
"type": "string"
59+
},
60+
"parameter_type": {
61+
"description": "The parameter value type.",
62+
"$ref": "#/$defs/parameter_type"
63+
},
64+
"parameter_state_type": {
65+
"description": "The state type of the parameter, if the value type is an encoded state.",
66+
"$ref": "#/$defs/encoded_state_type"
67+
},
68+
"default_value": {
69+
"description": "The string representation of the default parameter value, or null if the parameter has no valid default value.",
70+
"examples": [
71+
"foo",
72+
"[ 1.0, 2.0, 3.0 ]",
73+
null
74+
],
75+
"anyOf": [
76+
{
77+
"type": "string"
78+
},
79+
{
80+
"type": "null"
81+
}
82+
]
83+
},
84+
"optional": {
85+
"description": "Specify if this parameter is optional (only applicable if the default value is null)",
86+
"type": "boolean"
87+
},
88+
"dynamic": {
89+
"description": "Specify if this parameter can be dynamically reconfigured.",
90+
"type": "boolean"
91+
},
92+
"internal": {
93+
"description": "Specify if this parameter is for internal use only and should be hidden from public users.",
94+
"type": "boolean",
95+
"default": false
96+
}
97+
},
98+
"required": [
99+
"display_name",
100+
"description",
101+
"parameter_name",
102+
"parameter_type",
103+
"default_value"
104+
],
105+
"allOf": [
106+
{
107+
"if": {
108+
"properties": {
109+
"default_value": {
110+
"not": {
111+
"const": null
112+
}
113+
}
114+
}
115+
},
116+
"then": {
117+
"not": {
118+
"required": [
119+
"optional"
120+
]
121+
}
122+
}
123+
},
124+
{
125+
"if": {
126+
"properties": {
127+
"parameter_type": {
128+
"const": "state"
129+
}
130+
}
131+
},
132+
"then": {
133+
"required": [
134+
"parameter_state_type"
135+
]
136+
}
137+
}
138+
]
139+
},
140+
"parameter_type": {
141+
"$schema": "https://json-schema.org/draft/2020-12/schema",
142+
"title": "Parameter Type",
143+
"description": "The value type of a parameter from a collection of supported types.",
144+
"type": "string",
145+
"enum": [
146+
"bool",
147+
"bool_array",
148+
"int",
149+
"int_array",
150+
"double",
151+
"double_array",
152+
"string",
153+
"string_array",
154+
"vector",
155+
"matrix",
156+
"state"
157+
]
158+
},
159+
"predicate": {
160+
"$schema": "https://json-schema.org/draft/2020-12/schema",
161+
"title": "Predicate",
162+
"description": "A predicate of a component or controller.",
163+
"type": "object",
164+
"properties": {
165+
"display_name": {
166+
"description": "The human-readable predicate name.",
167+
"type": "string"
168+
},
169+
"description": {
170+
"description": "A brief description of the predicate.",
171+
"type": "string"
172+
},
173+
"predicate_name": {
174+
"description": "The lower_snake_case predicate name as it is declared in the component or controller.",
175+
"type": "string"
176+
}
177+
},
178+
"required": [
179+
"display_name",
180+
"description",
181+
"predicate_name"
182+
]
183+
},
184+
"service": {
185+
"$schema": "https://json-schema.org/draft/2020-12/schema",
186+
"title": "Service",
187+
"description": "A service endpoint of a component or controller.",
188+
"type": "object",
189+
"properties": {
190+
"display_name": {
191+
"description": "The human-readable service name.",
192+
"type": "string"
193+
},
194+
"description": {
195+
"description": "A brief description of the service.",
196+
"type": "string"
197+
},
198+
"service_name": {
199+
"description": "The lower_snake_case service name as it is declared in the component or controller.",
200+
"type": "string"
201+
},
202+
"payload_format": {
203+
"description": "Optional description of the payload format if the service has a string payload. If omitted, the service is assumed to be an empty trigger.",
204+
"type": "string"
205+
}
206+
},
207+
"required": [
208+
"display_name",
209+
"description",
210+
"service_name"
211+
]
212+
},
213+
"signal": {
214+
"$schema": "https://json-schema.org/draft/2020-12/schema",
215+
"title": "Signal",
216+
"description": "A continuous data signal in the AICA framework that can be an input or an output.",
217+
"type": "object",
218+
"properties": {
219+
"display_name": {
220+
"description": "The short name of this signal (to be displayed on the edge of the node in the graph view).",
221+
"examples": [
222+
"Target Pose",
223+
"Sum",
224+
"Command Torque"
225+
],
226+
"type": "string"
227+
},
228+
"description": {
229+
"description": "A description of the signal for tool-tips and documentation.",
230+
"type": "string"
231+
},
232+
"signal_name": {
233+
"description": "The registered name of the signal from which the default topic and parameter '<$signal_name>_topic' are determined.",
234+
"examples": [
235+
"target_pose",
236+
"sum",
237+
"command_torque"
238+
],
239+
"type": "string"
240+
},
241+
"default_topic": {
242+
"description": "The default topic name assigned to this signal. If unspecified, it is assumed to be '~/<$signal_name>'. Setting the parameter '<$signal_name>_topic' will override the default value.",
243+
"default": "~/signal_name",
244+
"type": "string"
245+
},
246+
"reconfigurable_topic": {
247+
"description": "Indicate if the signal topic is reconfigurable and can be renamed while the parent node is inactive through the '<$signal_name>_topic' parameter.",
248+
"default": false,
249+
"type": "boolean"
250+
},
251+
"signal_type": {
252+
"description": "The fixed type of this signal.",
253+
"$ref": "#/$defs/signal_type"
254+
},
255+
"signal_types": {
256+
"description": "An array of signal types supported by configurable typing. The active type is set through the '<$signal_name>_type' parameter, and the default type is determined by the `signal_type` property.",
257+
"type": "array",
258+
"items": {
259+
"$ref": "#/$defs/signal_type"
260+
},
261+
"minItems": 1,
262+
"uniqueItems": true
263+
},
264+
"reconfigurable_type": {
265+
"description": "Indicate if the signal type is reconfigurable and can be renamed while the parent node is inactive through the '<$signal_name>_type' parameter.",
266+
"default": false,
267+
"type": "boolean"
268+
},
269+
"custom_signal_type": {
270+
"description": "The custom signal type of the signal",
271+
"examples": [
272+
"sensor_msgs::msg::JointState",
273+
"geometry_msgs::msg::Pose"
274+
],
275+
"type": "string"
276+
}
277+
},
278+
"required": [
279+
"display_name",
280+
"description",
281+
"signal_name",
282+
"signal_type"
283+
],
284+
"if": {
285+
"properties": {
286+
"signal_type": {
287+
"const": "other"
288+
}
289+
}
290+
},
291+
"then": {
292+
"required": [
293+
"custom_signal_type"
294+
]
295+
}
296+
},
297+
"signal_type": {
298+
"$schema": "https://json-schema.org/draft/2020-12/schema",
299+
"title": "Signal Type",
300+
"description": "Supported signal value types as simple atomic types or encoded state types.",
301+
"anyOf": [
302+
{
303+
"type": "string",
304+
"enum": [
305+
"bool",
306+
"int",
307+
"double",
308+
"double_array",
309+
"string",
310+
"other"
311+
]
312+
},
313+
{
314+
"$ref": "#/$defs/encoded_state_type"
315+
}
316+
]
317+
}
318+
}
319+
}

0 commit comments

Comments
 (0)