From 9f81c6ddd6192ec285de8fbafd290520db3126da Mon Sep 17 00:00:00 2001 From: Enrico Eberhard <32450951+eeberhard@users.noreply.github.com> Date: Fri, 10 Jan 2025 13:57:35 +0100 Subject: [PATCH] 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 --- .../03-component-descriptions.md | 20 +- .../draft/1-0-0/interfaces.schema.json | 319 ++++++++++++++++++ .../schema/component.schema.json | 10 +- .../schema/signal_collection.schema.json | 4 +- .../schema/controller.schema.json | 10 +- 5 files changed, 343 insertions(+), 20 deletions(-) create mode 100644 docs/static/schemas/draft/1-0-0/interfaces.schema.json diff --git a/docs/docs/reference/custom-components/03-component-descriptions.md b/docs/docs/reference/custom-components/03-component-descriptions.md index af59fda2..f0c0a2b6 100644 --- a/docs/docs/reference/custom-components/03-component-descriptions.md +++ b/docs/docs/reference/custom-components/03-component-descriptions.md @@ -20,10 +20,9 @@ Components have various interfaces that need to be described: Aside from interfaces, a component description should also include information on the type of component (regular or lifecycle), the general component behavior or purpose, and other metadata such as name and registration details. - The elements of a component description are written as a standardized JSON file for each component. The expected structure of the component description is defined by -the [Component Description JSON schema](../../../../schemas/component-descriptions/schema/component.schema.json) +the [Component Description JSON schema](../../../static/schemas/1-1-1/component.schema.json) :::info @@ -101,9 +100,8 @@ components, as they provide no meaningful behavior if directly instantiated. ## Signals - The expected structure of the signal description is defined by -the [Signal Description JSON schema](../../../../schemas/interfaces/schema/common/signal.schema.json). +the [Signal Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal). Component inputs and outputs are described with a signal name and type, matching the name and type in the implementation 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 ## Parameters - The expected structure of the parameter description is defined by -the [Parameter Description JSON schema](../../../../schemas/interfaces/schema/common/parameter.schema.json). +the [Parameter Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter). Parameters contain a value of a certain type, described by the `parameter_type` property. Valid parameter types are -defined in the [Parameter Type JSON schema](../../../../schemas/interfaces/schema/common/parameter_type.schema.json). +defined in +the [Parameter Type JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter_type). If the `parameter_type` property is `state`, then the `parameter_state_type` property must also be defined as a member of the enumeration -in [Encoded State Type JSON schema](../../../../schemas/interfaces/schema/common/encoded_state_type.schema.json). +in [Encoded State Type JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/encoded_state_type.schema.json). Parameters generally have a default value which renders them optional in some cases. When a parameter has no valid 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. ## Predicates +The expected structure of the predicate description is defined by +the [Predicate Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/predicate). + Predicates are crucial to drive the event logic of the Dynamic State Engine, but they are very simple to declare and describe. Each predicate of a component indicates a particular run-time state or configuration that is either "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. ## Services +The expected structure of the service description is defined by +the [Service Description JSON schema](../../../static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/service). + Services are endpoints provided by a component that can trigger certain behaviours. In the backend implementation, they are created as ROS2 services with a specific `service_name` using one of two service message types. The first type is simply an empty trigger service that has no payload, which is the default case. The second type is a trigger diff --git a/docs/static/schemas/draft/1-0-0/interfaces.schema.json b/docs/static/schemas/draft/1-0-0/interfaces.schema.json new file mode 100644 index 00000000..d559ea0d --- /dev/null +++ b/docs/static/schemas/draft/1-0-0/interfaces.schema.json @@ -0,0 +1,319 @@ +{ + "$id": "/draft/1-0-0/interfaces.schema.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Common Interfaces", + "description": "This schema includes definitions for common interfaces across the AICA System", + "$defs": { + "encoded_state_type": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Encoded State Type", + "description": "The state type of an encoded value from a collection of supported types, as defined in clproto.", + "type": "string", + "enum": [ + "state", + "spatial_state", + "cartesian_state", + "cartesian_pose", + "cartesian_twist", + "cartesian_acceleration", + "cartesian_wrench", + "jacobian", + "joint_state", + "joint_positions", + "joint_velocities", + "joint_accelerations", + "joint_torques", + "shape", + "ellipsoid", + "parameter", + "digital_io_state", + "analog_io_state" + ] + }, + "parameter": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Parameter", + "description": "A dynamic parameter that is publicly configurable.", + "type": "object", + "additionalProperties": false, + "properties": { + "display_name": { + "description": "The human-readable parameter name.", + "examples": [ + "Reference Frame", + "Gain" + ], + "type": "string" + }, + "description": { + "description": "A brief description of the parameter.", + "type": "string" + }, + "parameter_name": { + "description": "The lower_snake_case parameter name as it is declared in the implementation.", + "examples": [ + "reference_frame", + "gain" + ], + "type": "string" + }, + "parameter_type": { + "description": "The parameter value type.", + "$ref": "#/$defs/parameter_type" + }, + "parameter_state_type": { + "description": "The state type of the parameter, if the value type is an encoded state.", + "$ref": "#/$defs/encoded_state_type" + }, + "default_value": { + "description": "The string representation of the default parameter value, or null if the parameter has no valid default value.", + "examples": [ + "foo", + "[ 1.0, 2.0, 3.0 ]", + null + ], + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "optional": { + "description": "Specify if this parameter is optional (only applicable if the default value is null)", + "type": "boolean" + }, + "dynamic": { + "description": "Specify if this parameter can be dynamically reconfigured.", + "type": "boolean" + }, + "internal": { + "description": "Specify if this parameter is for internal use only and should be hidden from public users.", + "type": "boolean", + "default": false + } + }, + "required": [ + "display_name", + "description", + "parameter_name", + "parameter_type", + "default_value" + ], + "allOf": [ + { + "if": { + "properties": { + "default_value": { + "not": { + "const": null + } + } + } + }, + "then": { + "not": { + "required": [ + "optional" + ] + } + } + }, + { + "if": { + "properties": { + "parameter_type": { + "const": "state" + } + } + }, + "then": { + "required": [ + "parameter_state_type" + ] + } + } + ] + }, + "parameter_type": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Parameter Type", + "description": "The value type of a parameter from a collection of supported types.", + "type": "string", + "enum": [ + "bool", + "bool_array", + "int", + "int_array", + "double", + "double_array", + "string", + "string_array", + "vector", + "matrix", + "state" + ] + }, + "predicate": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Predicate", + "description": "A predicate of a component or controller.", + "type": "object", + "properties": { + "display_name": { + "description": "The human-readable predicate name.", + "type": "string" + }, + "description": { + "description": "A brief description of the predicate.", + "type": "string" + }, + "predicate_name": { + "description": "The lower_snake_case predicate name as it is declared in the component or controller.", + "type": "string" + } + }, + "required": [ + "display_name", + "description", + "predicate_name" + ] + }, + "service": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Service", + "description": "A service endpoint of a component or controller.", + "type": "object", + "properties": { + "display_name": { + "description": "The human-readable service name.", + "type": "string" + }, + "description": { + "description": "A brief description of the service.", + "type": "string" + }, + "service_name": { + "description": "The lower_snake_case service name as it is declared in the component or controller.", + "type": "string" + }, + "payload_format": { + "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.", + "type": "string" + } + }, + "required": [ + "display_name", + "description", + "service_name" + ] + }, + "signal": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Signal", + "description": "A continuous data signal in the AICA framework that can be an input or an output.", + "type": "object", + "properties": { + "display_name": { + "description": "The short name of this signal (to be displayed on the edge of the node in the graph view).", + "examples": [ + "Target Pose", + "Sum", + "Command Torque" + ], + "type": "string" + }, + "description": { + "description": "A description of the signal for tool-tips and documentation.", + "type": "string" + }, + "signal_name": { + "description": "The registered name of the signal from which the default topic and parameter '<$signal_name>_topic' are determined.", + "examples": [ + "target_pose", + "sum", + "command_torque" + ], + "type": "string" + }, + "default_topic": { + "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.", + "default": "~/signal_name", + "type": "string" + }, + "reconfigurable_topic": { + "description": "Indicate if the signal topic is reconfigurable and can be renamed while the parent node is inactive through the '<$signal_name>_topic' parameter.", + "default": false, + "type": "boolean" + }, + "signal_type": { + "description": "The fixed type of this signal.", + "$ref": "#/$defs/signal_type" + }, + "signal_types": { + "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.", + "type": "array", + "items": { + "$ref": "#/$defs/signal_type" + }, + "minItems": 1, + "uniqueItems": true + }, + "reconfigurable_type": { + "description": "Indicate if the signal type is reconfigurable and can be renamed while the parent node is inactive through the '<$signal_name>_type' parameter.", + "default": false, + "type": "boolean" + }, + "custom_signal_type": { + "description": "The custom signal type of the signal", + "examples": [ + "sensor_msgs::msg::JointState", + "geometry_msgs::msg::Pose" + ], + "type": "string" + } + }, + "required": [ + "display_name", + "description", + "signal_name", + "signal_type" + ], + "if": { + "properties": { + "signal_type": { + "const": "other" + } + } + }, + "then": { + "required": [ + "custom_signal_type" + ] + } + }, + "signal_type": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Signal Type", + "description": "Supported signal value types as simple atomic types or encoded state types.", + "anyOf": [ + { + "type": "string", + "enum": [ + "bool", + "int", + "double", + "double_array", + "string", + "other" + ] + }, + { + "$ref": "#/$defs/encoded_state_type" + } + ] + } + } +} \ No newline at end of file diff --git a/schemas/component-descriptions/schema/component.schema.json b/schemas/component-descriptions/schema/component.schema.json index f2ec7b26..58f6075c 100644 --- a/schemas/component-descriptions/schema/component.schema.json +++ b/schemas/component-descriptions/schema/component.schema.json @@ -71,7 +71,7 @@ "description": "The fixed input signals (subscriptions) of the component.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal" }, "uniqueItems": true }, @@ -89,7 +89,7 @@ "description": "The output signals (publications) of the component.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal_type" }, "uniqueItems": true }, @@ -98,7 +98,7 @@ "description": "The parameters declared by the component.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/parameters/schema/parameter.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter" }, "uniqueItems": true }, @@ -107,7 +107,7 @@ "description": "The predicates provided by the component.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/predicates/schema/predicate.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/predicate" }, "uniqueItems": true }, @@ -116,7 +116,7 @@ "description": "The services provided by the component.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/services/schema/service.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/service" }, "uniqueItems": true } diff --git a/schemas/component-descriptions/schema/signal_collection.schema.json b/schemas/component-descriptions/schema/signal_collection.schema.json index 53628f0c..4a62a9b7 100644 --- a/schemas/component-descriptions/schema/signal_collection.schema.json +++ b/schemas/component-descriptions/schema/signal_collection.schema.json @@ -31,13 +31,13 @@ }, "signal_type": { "description": "The default type of the signals (signals in a collection must have the same type).", - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal_type.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal_type" }, "signal_types": { "description": "An array of signal types supported by configurable typing. The active type is set through the '<$input_collection_name>_type' parameter, and the default type is determined by the `signal_type` property.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal_type.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal_type" }, "minItems": 1, "uniqueItems": true diff --git a/schemas/controller-descriptions/schema/controller.schema.json b/schemas/controller-descriptions/schema/controller.schema.json index 714e93fa..1792ca12 100644 --- a/schemas/controller-descriptions/schema/controller.schema.json +++ b/schemas/controller-descriptions/schema/controller.schema.json @@ -84,7 +84,7 @@ "description": "The fixed input signals (subscriptions) of the controller.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal_type" }, "uniqueItems": true }, @@ -93,7 +93,7 @@ "description": "The output signals (publications) of the controller.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/signals/schema/signal.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/signal" }, "uniqueItems": true }, @@ -102,7 +102,7 @@ "description": "The parameters declared by the controller.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/parameters/schema/parameter.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/parameter" }, "uniqueItems": true }, @@ -111,7 +111,7 @@ "description": "The predicates provided by the controller.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/predicates/schema/predicate.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/predicate" }, "uniqueItems": true }, @@ -120,7 +120,7 @@ "description": "The services provided by the controller.", "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/schemas/services/schema/service.schema.json" + "$ref": "https://raw.githubusercontent.com/aica-technology/api/main/docs/static/schemas/draft/1-0-0/interfaces.schema.json#/$defs/service" }, "uniqueItems": true }