This service transforms a user-defined JSONSchema into a Kubernetes Custom Resource Definition (CRD) that defines the structure and behavior of UI components.
It's designed for front-end developers to describe component configuration declaratively, while enabling runtime enrichment and action handling via a companion service called Snowplow.
Front-end developers use Smithery to define the properties of a UI component using JSONSchema, specifically under the widgetData section.
Smithery:
- Parses and validates the user-defined schema.
- Injects additional schema sections that enable runtime logic, templating, and remote interactions.
- Outputs a complete CRD that is Kubernetes-compatible.
Before generating the CRD, Smithery automatically injects the following three JSONSchema sections into the root level of the user’s schema. These allow CRs to be dynamically enriched and to interact with external systems at runtime.
| Field | Type | Description |
|---|---|---|
apiRef |
object | Defines a RESTAction that acts as a data source. The response (JSON) will be available for JQ expression resolution in templates. |
widgetDataTemplate |
object | A template layer on top of widgetData using JQ expressions. These are evaluated at runtime by Snowplow, with data from apiRef. |
resourcesRefs |
object | Describes a set of runtime actions (e.g., REST operations) triggered by the component (e.g., onClick for a button). |
resourcesRefsTemplate |
object | Describes one or more templates to generate set of runtime actions (e.g., REST operations) triggered by the component (e.g., onClick for a button). |
These sections are located in the Smithery repo under
/assets.
- Located at:
apiRef.json - Defines a single REST request (method, URL, headers, body) with optional parameters.
- Snowplow executes this and stores the result as a JSON object, accessible to templates and logic elsewhere in the CR.
Example Use Case:
Fetching a list of users from an external API to populate a dropdown.
-
Located at:
widgetDataTemplate.json -
Defines an array of pairs of path to
widgetDataproperties and a related JQ expression. -
At runtime, Snowplow evaluates these using the
apiRefresult as input and merges the evaluated data intowidgetDataspecs.
Example Use Case:
Filling a widget fields with data from an external remote HTTP service (or internal Kubernetes API call).
- Located at:
resourcesRefs.json - Defines runtime actions triggered by the widget, such as HTTP POST requests when a button is clicked.
- These can be tied to UI events and can have different HTTP methods, payloads, etc.
Example Use Case:
When a button is clicked, send a POST request to submit form data to an external API (or to Kubernetes API Server).
-
Located at:
resourcesRefs.json -
Allows for the definition of one or more templates to dynamically generate
resourcesRefsobjects. In this context, "dynamically" means that the properties (i.e., their values) are the results of JQ expressions evaluated against the output obtained from a previous resolution of anapiRef.
This mechanism enables the flexible and automated creation of resource references based on dynamic data, facilitating more adaptable and efficient workflows.