feat(vdp): extend component definitions (#262)

Because - Basic connector / operator definition view doesn't contain the information needed to render a summary of the available tasks at Instill AI Design in Figma [here](https://www.figma.com/file/M4vNxW6o4FCs9qSvmUuin1/Landing-Page?type=design&mode=design&t=WE3uddPT5jA4Shj1-0). ![image](https://github.com/instill-ai/protobufs/assets/3977183/1c3fee0e-9aff-4ca8-8a44-6c22c54e65d7) This commit - Extends the connector and operator definition information with fields that will be used to render a summary of the available components and tasks. - Component version - Available tasks - Source code URL --------- Co-authored-by: droplet-bot <[email protected]>
instill-ai · Feb 6, 2024 · d93f8e5 · d93f8e5
1 parent 0e4e9e6
commit d93f8e5
Show file tree

Hide file tree

Showing 4 changed files with 119 additions and 22 deletions.
diff --git a/openapiv2/vdp/service.swagger.yaml b/openapiv2/vdp/service.swagger.yaml
@@ -2160,7 +2160,8 @@ paths:
  description: |-
  View allows clients to specify the desired resource view in the response.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  in: query
  required: false
@@ -2208,7 +2209,8 @@ paths:
  description: |-
  View allows clients to specify the desired resource view in the response.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  in: query
  required: false
@@ -2255,7 +2257,8 @@ paths:
  description: |-
  View allows clients to specify the desired resource view in the response.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  in: query
  required: false
@@ -2303,7 +2306,8 @@ paths:
  description: |-
  View allows clients to specify the desired resource view in the response.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  in: query
  required: false
@@ -4042,6 +4046,24 @@ definitions:
  required:
  - id
  - definition_name
+ v1betaComponentTask:
+ type: object
+ properties:
+ name:
+ type: string
+ description: The task name, e.g. `TASK_TEXT_GENERATION`.
+ readOnly: true
+ title:
+ type: string
+ description: Title is the task name in a human-friendly format.
+ readOnly: true
+ description:
+ type: string
+ description: Description contains information about the task.
+ readOnly: true
+ description: |-
+ ComponentTask contains information about a task that a component can
+ perform.
  v1betaComponentType:
  type: string
  enum:
@@ -4184,7 +4206,10 @@ definitions:
  readOnly: true
  icon:
  type: string
- description: Connector definition icon.
+ description: |-
+ Connector definition icon. This is a path that's relative to the root of
+ the connector implementation (see `source_url`) and that allows clients
+ frontend applications to pull and locate the icons.
  readOnly: true
  spec:
  $ref: '#/definitions/v1betaConnectorSpec'
@@ -4212,10 +4237,6 @@ definitions:
  Connector definition custom flag, i.e., whether this is a custom
  connector definition.
  readOnly: true
- icon_url:
- type: string
- description: Connector definition icon URL.
- readOnly: true
  vendor:
  type: string
  description: Connector definition vendor name.
@@ -4224,6 +4245,25 @@ definitions:
  type: object
  description: Vendor-specific attributes.
  readOnly: true
+ source_url:
+ type: string
+ description: |-
+ Source code URL. This points to the source code where the connector is
+ implemented.
+ readOnly: true
+ version:
+ type: string
+ description: |-
+ Connector definition version. This is a string that fulfills the SemVer
+ specification (e.g. `1.0.0-beta`).
+ readOnly: true
+ tasks:
+ type: array
+ items:
+ type: object
+ $ref: '#/definitions/v1betaComponentTask'
+ description: List of tasks that can be executed by the connector.
+ readOnly: true
  description: |-
  A Connector is a type of pipeline component that queries, processes or sends
  the ingested unstructured data to a service or app. Users need to configure
@@ -4241,7 +4281,8 @@ definitions:
  description: |-
  View defines how a connector definition is presented.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  v1betaConnectorSpec:
  type: object
@@ -4803,7 +4844,10 @@ definitions:
  readOnly: true
  icon:
  type: string
- description: Operator definition icon.
+ description: |-
+ Operator definition icon. This is a path that's relative to the root of
+ the operator implementation (see `source_url`) and that allows clients
+ frontend applications to pull and locate the icons.
  readOnly: true
  spec:
  $ref: '#/definitions/v1betaOperatorSpec'
@@ -4825,9 +4869,24 @@ definitions:
  type: boolean
  description: The custom flag determines whether this is a custom operator definition.
  readOnly: true
- icon_url:
+ source_url:
  type: string
- description: Operator definition icon URL.
+ description: |-
+ Source code URL. This points to the source code where the operator is
+ implemented.
+ readOnly: true
+ version:
+ type: string
+ description: |-
+ Operator definition version. This is a string that fulfills the SemVer
+ specification (e.g. `1.0.0-beta`).
+ readOnly: true
+ tasks:
+ type: array
+ items:
+ type: object
+ $ref: '#/definitions/v1betaComponentTask'
+ description: List of tasks that can be executed by the operator.
  readOnly: true
  description: |-
  An Operator is a type of pipeline component that performs data injection and
@@ -4844,7 +4903,8 @@ definitions:
  description: |-
  View defines how an operator definition is presented.
 
- - VIEW_BASIC: Default view, only includes basic information.
+ - VIEW_BASIC: Default view, only includes basic information (removes the `spec`
+ field).
  - VIEW_FULL: Full representation.
  v1betaOperatorSpec:
  type: object

diff --git a/vdp/pipeline/v1beta/common.proto b/vdp/pipeline/v1beta/common.proto
@@ -90,3 +90,14 @@ message CheckNameResponse {
  // The availability of the requested name.
  Name availability = 1;
 }
+
+// ComponentTask contains information about a task that a component can
+// perform.
+message ComponentTask {
+ // The task name, e.g. `TASK_TEXT_GENERATION`.
+ string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // Title is the task name in a human-friendly format.
+ string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // Description contains information about the task.
+ string description = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+}
diff --git a/vdp/pipeline/v1beta/connector_definition.proto b/vdp/pipeline/v1beta/connector_definition.proto
@@ -8,6 +8,8 @@ import "google/api/resource.proto";
 // Protocol Buffers Well-Known Types
 import "google/protobuf/struct.proto";
 import "protoc-gen-openapiv2/options/annotations.proto";
+// VDP definitions
+import "vdp/pipeline/v1beta/common.proto";
 
 ////////////////////////////////////
 
@@ -60,7 +62,8 @@ message ConnectorDefinition {
  enum View {
  // Unspecified, equivalent to BASIC.
  VIEW_UNSPECIFIED = 0;
- // Default view, only includes basic information.
+ // Default view, only includes basic information (removes the `spec`
+ // field).
  VIEW_BASIC = 1;
  // Full representation.
  VIEW_FULL = 2;
@@ -80,7 +83,9 @@ message ConnectorDefinition {
  string title = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Connector definition documentation URL.
  string documentation_url = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
- // Connector definition icon.
+ // Connector definition icon. This is a path that's relative to the root of
+ // the connector implementation (see `source_url`) and that allows clients
+ // frontend applications to pull and locate the icons.
  string icon = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Connector definition specification.
  ConnectorSpec spec = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -95,12 +100,20 @@ message ConnectorDefinition {
  // Connector definition custom flag, i.e., whether this is a custom
  // connector definition.
  bool custom = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
- // Connector definition icon URL.
- string icon_url = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // field 12 is reserved for 'icon_url'.
+ reserved 12;
  // Connector definition vendor name.
  string vendor = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Vendor-specific attributes.
  google.protobuf.Struct vendor_attributes = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // Source code URL. This points to the source code where the connector is
+ // implemented.
+ string source_url = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // Connector definition version. This is a string that fulfills the SemVer
+ // specification (e.g. `1.0.0-beta`).
+ string version = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // List of tasks that can be executed by the connector.
+ repeated ComponentTask tasks = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 ///////////////////////////////////////////////////////////////////////

diff --git a/vdp/pipeline/v1beta/operator_definition.proto b/vdp/pipeline/v1beta/operator_definition.proto
@@ -9,6 +9,8 @@ import "google/api/resource.proto";
 import "google/protobuf/struct.proto";
 // OpenAPI definition
 import "protoc-gen-openapiv2/options/annotations.proto";
+// VDP definitions
+import "vdp/pipeline/v1beta/common.proto";
 
 // OperatorSpec represents a specification data model.
 message OperatorSpec {
@@ -37,7 +39,8 @@ message OperatorDefinition {
  enum View {
  // Unspecified, equivalent to BASIC.
  VIEW_UNSPECIFIED = 0;
- // Default view, only includes basic information.
+ // Default view, only includes basic information (removes the `spec`
+ // field).
  VIEW_BASIC = 1;
  // Full representation.
  VIEW_FULL = 2;
@@ -57,7 +60,9 @@ message OperatorDefinition {
  string title = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Operator definition documentation URL.
  string documentation_url = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
- // Operator definition icon.
+ // Operator definition icon. This is a path that's relative to the root of
+ // the operator implementation (see `source_url`) and that allows clients
+ // frontend applications to pull and locate the icons.
  string icon = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Operator definition specification.
  OperatorSpec spec = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -69,8 +74,16 @@ message OperatorDefinition {
  bool public = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The custom flag determines whether this is a custom operator definition.
  bool custom = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
- // Operator definition icon URL.
- string icon_url = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // field 11 is reserved for 'icon_url'.
+ reserved 11;
+ // Source code URL. This points to the source code where the operator is
+ // implemented.
+ string source_url = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // Operator definition version. This is a string that fulfills the SemVer
+ // specification (e.g. `1.0.0-beta`).
+ string version = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
+ // List of tasks that can be executed by the operator.
+ repeated ComponentTask tasks = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 ///////////////////////////////////////////////////////////////////////