Add kubebuilder annotations and fix model descriptions

model/action.go

@@ -22,27 +22,43 @@ import (
 
 // Action specify invocations of services or other workflows during workflow execution.
 type Action struct {
-	// ID defines Unique action identifier
+	// Defines Unique action identifier.
+	// +optional
 	ID string `json:"id,omitempty"`
-	// Name defines Unique action definition name
+	// Defines Unique action name.
+	// +optional
 	Name string `json:"name,omitempty"`
-	// FunctionRef references a reusable function definition
+	// References a reusable function definition.
+	// +optional
 	FunctionRef *FunctionRef `json:"functionRef,omitempty"`
-	// EventRef references a 'trigger' and 'result' reusable event definitions
+	// References a 'trigger' and 'result' reusable event definitions.
+	// +optional
 	EventRef *EventRef `json:"eventRef,omitempty"`
-	// References a sub-workflow to be executed
+	// References a workflow to be invoked.
+	// +optional
 	SubFlowRef *WorkflowRef `json:"subFlowRef,omitempty"`
-	// Sleep Defines time period workflow execution should sleep before / after function execution
+	// Defines time period workflow execution should sleep before / after function execution.
+	// +optional
 	Sleep *Sleep `json:"sleep,omitempty"`
-	// RetryRef References a defined workflow retry definition. If not defined the default retry policy is assumed
+	// References a defined workflow retry definition. If not defined uses the default runtime retry definition.
+	// +optional
 	RetryRef string `json:"retryRef,omitempty"`
-	// List of unique references to defined workflow errors for which the action should not be retried. Used only when `autoRetries` is set to `true`
+	// List of unique references to defined workflow errors for which the action should not be retried.
+	// Used only when `autoRetries` is set to `true`
+	// +optional
 	NonRetryableErrors []string `json:"nonRetryableErrors,omitempty" validate:"omitempty,min=1"`
-	// List of unique references to defined workflow errors for which the action should be retried. Used only when `autoRetries` is set to `false`
+	// List of unique references to defined workflow errors for which the action should be retried.
+	// Used only when `autoRetries` is set to `false`
+	// +optional
 	RetryableErrors []string `json:"retryableErrors,omitempty" validate:"omitempty,min=1"`
-	// Action data filter
+	// Filter the state data to select only the data that can be used within function definition arguments
+	// using its fromStateData property. Filter the action results to select only the result data that should
+	// be added/merged back into the state data using its results property. Select the part of state data which
+	// the action data results should be added/merged to using the toStateData property.
+	// +optional
 	ActionDataFilter ActionDataFilter `json:"actionDataFilter,omitempty"`
-	// Workflow expression evaluated against state data. Must evaluate to true or false
+	// Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded.
+	// +optional
 	Condition string `json:"condition,omitempty"`
 }
 
@@ -65,16 +81,20 @@ func (a *Action) UnmarshalJSON(data []byte) error {
 
 // FunctionRef defines the reference to a reusable function definition
 type FunctionRef struct {
-	// Name of the referenced function
+	// Name of the referenced function.
+	// +kubebuilder:validation:Required
 	RefName string `json:"refName" validate:"required"`
-	// Function arguments
+	// Arguments (inputs) to be passed to the referenced function
+	// +optional
 	// TODO: validate it as required if function type is graphql
 	Arguments map[string]Object `json:"arguments,omitempty"`
-	// String containing a valid GraphQL selection set
+	// Used if function type is graphql. String containing a valid GraphQL selection set.
 	// TODO: validate it as required if function type is graphql
+	// +optional
 	SelectionSet string `json:"selectionSet,omitempty"`
-	// Invoke specifies if the subflow should be invoked sync or async.
-	// Defaults to sync.
+	// Specifies if the function should be invoked sync or async. Default is sync.
+	// +kubebuilder:validation:Enum=async;sync
+	// +kubebuilder:default=sync
 	Invoke InvokeKind `json:"invoke,omitempty" validate:"required,oneof=async sync"`
 }
 
@@ -113,8 +133,12 @@ func (f *FunctionRef) UnmarshalJSON(data []byte) error {
 
 // Sleep defines time periods workflow execution should sleep before & after function execution
 type Sleep struct {
-	// Before defines amount of time (ISO 8601 duration format) to sleep before function/subflow invocation. Does not apply if 'eventRef' is defined.
+	// Defines amount of time (ISO 8601 duration format) to sleep before function/subflow invocation.
+	// Does not apply if 'eventRef' is defined.
+	// +optional
 	Before string `json:"before,omitempty" validate:"omitempty,iso8601duration"`
-	// After defines amount of time (ISO 8601 duration format) to sleep after function/subflow invocation. Does not apply if 'eventRef' is defined.
+	// Defines amount of time (ISO 8601 duration format) to sleep after function/subflow invocation.
+	// Does not apply if 'eventRef' is defined.
+	// +optional
 	After string `json:"after,omitempty" validate:"omitempty,iso8601duration"`
 }

model/action_data_filter.go

@@ -21,17 +21,23 @@ import (
 )
 
 // ActionDataFilter used to filter action data results.
+// +optional
+// +optional
 type ActionDataFilter struct {
-	// Workflow expression that selects state data that the state action can use
+	// Workflow expression that filters state data that can be used by the action.
+	// +optional
+	// +optional
 	FromStateData string `json:"fromStateData,omitempty"`
-
-	// UseResults represent where action data results is added/merged to state data. If it's false, results & toStateData should be ignored.
-	// Defaults to true.
+	// If set to false, action data results are not added/merged to state data. In this case 'results'
+	// and 'toStateData' should be ignored. Default is true.
+	// +optional
 	UseResults bool `json:"useResults,omitempty"`
-
-	// Workflow expression that filters the actions' data results
+	// Workflow expression that filters the actions data results.
+	// +optional
 	Results string `json:"results,omitempty"`
-	// Workflow expression that selects a state data element to which the action results should be added/merged into. If not specified, denote, the top-level state data element
+	// Workflow expression that selects a state data element to which the action results should be
+	// added/merged into. If not specified denotes the top-level state data element.
+	// +optional
 	ToStateData string `json:"toStateData,omitempty"`
 }
 

model/auth.go

@@ -20,7 +20,7 @@ import (
 	"strings"
 )
 
-// AuthType ...
+// AuthType can be "basic", "bearer", or "oauth2". Default is "basic"
 type AuthType string
 
 const (
@@ -44,13 +44,21 @@ const (
 	GrantTypeTokenExchange GrantType = "tokenExchange"
 )
 
-// Auth ...
+// Auth definitions can be used to define authentication information that should be applied to resources
+// defined in the operation property of function definitions. It is not used as authentication information
+// for the function invocation, but just to access the resource containing the function invocation information.
 type Auth struct {
-	// Name Unique auth definition name
+	// Unique auth definition name.
+	// +kubebuilder:validation:Required
 	Name string `json:"name" validate:"required"`
-	// Scheme Defines the auth type
-	Scheme AuthType `json:"scheme,omitempty" validate:"omitempty,min=1"`
-	// Properties ...
+	// Auth scheme, can be "basic", "bearer", or "oauth2". Default is "basic"
+	// +kubebuilder:validation:Enum=basic;bearer;oauth2
+	// +kubebuilder:default=basic
+	// +kubebuilder:validation:Required
+	Scheme AuthType `json:"scheme" validate:"min=1"`
+	// Auth scheme properties. Can be one of "Basic properties definition", "Bearer properties definition",
+	// or "OAuth2 properties definition"
+	// +kubebuilder:validation:Required
 	Properties AuthProperties `json:"properties" validate:"required"`
 }
 
@@ -145,10 +153,13 @@ type AuthProperties struct {
 type BasicAuthProperties struct {
 	Common `json:",inline"`
 	// Secret Expression referencing a workflow secret that contains all needed auth info
+	// +optional
 	Secret string `json:"secret,omitempty"`
 	// Username String or a workflow expression. Contains the username
+	// +kubebuilder:validation:Required
 	Username string `json:"username" validate:"required"`
 	// Password String or a workflow expression. Contains the user password
+	// +kubebuilder:validation:Required
 	Password string `json:"password" validate:"required"`
 }
 
@@ -177,8 +188,10 @@ func (b *BasicAuthProperties) UnmarshalJSON(data []byte) error {
 type BearerAuthProperties struct {
 	Common `json:",inline"`
 	// Secret Expression referencing a workflow secret that contains all needed auth info
+	// +optional
 	Secret string `json:"secret,omitempty"`
 	// Token String or a workflow expression. Contains the token
+	// +kubebuilder:validation:Required
 	Token string `json:"token" validate:"required"`
 }
 
@@ -203,29 +216,42 @@ func (b *BearerAuthProperties) UnmarshalJSON(data []byte) error {
 // OAuth2AuthProperties OAuth2 information
 type OAuth2AuthProperties struct {
 	Common `json:",inline"`
-	// Secret Expression referencing a workflow secret that contains all needed auth info
+	// Expression referencing a workflow secret that contains all needed auth info.
+	// +optional
 	Secret string `json:"secret,omitempty"`
-	// Authority String or a workflow expression. Contains the authority information
+	// String or a workflow expression. Contains the authority information.
+	// +optional
 	Authority string `json:"authority,omitempty" validate:"omitempty,min=1"`
-	// GrantType Defines the grant type
+	// 	Defines the grant type. Can be "password", "clientCredentials", or "tokenExchange"
+	// +kubebuilder:validation:Enum=password;clientCredentials;tokenExchange
+	// +kubebuilder:validation:Required
 	GrantType GrantType `json:"grantType" validate:"required"`
-	// ClientID String or a workflow expression. Contains the client identifier
+	// String or a workflow expression. Contains the client identifier.
+	// +kubebuilder:validation:Required
 	ClientID string `json:"clientId" validate:"required"`
-	// ClientSecret Workflow secret or a workflow expression. Contains the client secret
+	// Workflow secret or a workflow expression. Contains the client secret.
+	// +optional
 	ClientSecret string `json:"clientSecret,omitempty" validate:"omitempty,min=1"`
-	// Scopes Array containing strings or workflow expressions. Contains the OAuth2 scopes
+	// Array containing strings or workflow expressions. Contains the OAuth2 scopes.
+	// +optional
 	Scopes []string `json:"scopes,omitempty" validate:"omitempty,min=1"`
-	// Username String or a workflow expression. Contains the username. Used only if grantType is 'resourceOwner'
+	// String or a workflow expression. Contains the username. Used only if grantType is 'resourceOwner'.
+	// +optional
 	Username string `json:"username,omitempty" validate:"omitempty,min=1"`
-	// Password String or a workflow expression. Contains the user password. Used only if grantType is 'resourceOwner'
+	// String or a workflow expression. Contains the user password. Used only if grantType is 'resourceOwner'.
+	// +optional
 	Password string `json:"password,omitempty" validate:"omitempty,min=1"`
-	// Audiences Array containing strings or workflow expressions. Contains the OAuth2 audiences
+	// Array containing strings or workflow expressions. Contains the OAuth2 audiences.
+	// +optional
 	Audiences []string `json:"audiences,omitempty" validate:"omitempty,min=1"`
-	// SubjectToken String or a workflow expression. Contains the subject token
+	// String or a workflow expression. Contains the subject token.
+	// +optional
 	SubjectToken string `json:"subjectToken,omitempty" validate:"omitempty,min=1"`
-	// RequestedSubject String or a workflow expression. Contains the requested subject
+	// String or a workflow expression. Contains the requested subject.
+	// +optional
 	RequestedSubject string `json:"requestedSubject,omitempty" validate:"omitempty,min=1"`
-	// RequestedIssuer String or a workflow expression. Contains the requested issuer
+	// String or a workflow expression. Contains the requested issuer.
+	// +optional
 	RequestedIssuer string `json:"requestedIssuer,omitempty" validate:"omitempty,min=1"`
 }
 

model/callback_state.go

@@ -18,16 +18,19 @@ import (
 	"encoding/json"
 )
 
-// CallbackState executes a function and waits for callback event that indicates
-// completion of the task.
+// CallbackState executes a function and waits for callback event that indicates completion of the task.
 type CallbackState struct {
-	// Defines the action to be executed
+	// Defines the action to be executed.
+	// +kubebuilder:validation:Required
 	Action Action `json:"action" validate:"required"`
-	// References a unique callback event name in the defined workflow events
+	// References a unique callback event name in the defined workflow events.
+	// +kubebuilder:validation:Required
 	EventRef string `json:"eventRef" validate:"required"`
 	// Time period to wait for incoming events (ISO 8601 format)
+	// +optional
 	Timeouts *CallbackStateTimeout `json:"timeouts,omitempty"`
-	// Event data filter
+	// Event data filter definition.
+	// +optional
 	EventDataFilter *EventDataFilter `json:"eventDataFilter,omitempty"`
 }
 
@@ -45,7 +48,13 @@ func (c *CallbackState) MarshalJSON() ([]byte, error) {
 
 // CallbackStateTimeout defines timeout settings for callback state
 type CallbackStateTimeout struct {
-	StateExecTimeout  *StateExecTimeout `json:"stateExecTimeout,omitempty"`
-	ActionExecTimeout string            `json:"actionExecTimeout,omitempty" validate:"omitempty,iso8601duration"`
-	EventTimeout      string            `json:"eventTimeout,omitempty" validate:"omitempty,iso8601duration"`
+	// Default workflow state execution timeout (ISO 8601 duration format)
+	// +optional
+	StateExecTimeout *StateExecTimeout `json:"stateExecTimeout,omitempty"`
+	// Default single actions definition execution timeout (ISO 8601 duration format)
+	// +optional
+	ActionExecTimeout string `json:"actionExecTimeout,omitempty" validate:"omitempty,iso8601duration"`
+	// Default timeout for consuming defined events (ISO 8601 duration format)
+	// +optional
+	EventTimeout string `json:"eventTimeout,omitempty" validate:"omitempty,iso8601duration"`
 }

model/common.go

@@ -17,6 +17,7 @@ package model
 // Common schema for Serverless Workflow specification
 type Common struct {
 	// Metadata information
+	// +optional
 	Metadata Metadata `json:"metadata,omitempty"`
 }
 

model/delay_state.go

@@ -19,6 +19,7 @@ import "encoding/json"
 // DelayState Causes the workflow execution to delay for a specified duration
 type DelayState struct {
 	// Amount of time (ISO 8601 format) to delay
+	// +kubebuilder:validation:Required
 	TimeDelay string `json:"timeDelay" validate:"required,iso8601duration"`
 }
 

model/event.go

@@ -32,19 +32,25 @@ const (
 // Event used to define events and their correlations
 type Event struct {
 	Common `json:",inline"`
-	// Unique event name
+	// Unique event name.
+	// +kubebuilder:validation:Required
 	Name string `json:"name" validate:"required"`
-	// CloudEvent source
+	// CloudEvent source.
+	// +optional
 	Source string `json:"source,omitempty"`
-	// CloudEvent type
+	// CloudEvent type.
+	// +kubebuilder:validation:Required
 	Type string `json:"type" validate:"required"`
-	// Defines the CloudEvent as either 'consumed' or 'produced' by the workflow.
-	// Defaults to `consumed`
+	// Defines the CloudEvent as either 'consumed' or 'produced' by the workflow. Defaults to `consumed`.
+	// +kubebuilder:validation:Enum=consumed;produced
+	// +kubebuilder:default=consumed
 	Kind EventKind `json:"kind,omitempty"`
-	// If `true`, only the Event payload is accessible to consuming Workflow states. If `false`, both event payload and context attributes should be accessible"
-	// Defaults to true
+	// If `true`, only the Event payload is accessible to consuming Workflow states. If `false`, both event payload
+	// and context attributes should be accessible. Defaults to true.
+	// +optional
 	DataOnly bool `json:"dataOnly,omitempty"`
-	// CloudEvent correlation definitions
+	// Define event correlation rules for this event. Only used for consumed events.
+	// +optional
 	Correlation []Correlation `json:"correlation,omitempty" validate:"omitempty,dive"`
 }
 
@@ -68,26 +74,36 @@ func (e *Event) UnmarshalJSON(data []byte) error {
 // Correlation define event correlation rules for an event. Only used for `consumed` events
 type Correlation struct {
 	// CloudEvent Extension Context Attribute name
+	// +kubebuilder:validation:Required
 	ContextAttributeName string `json:"contextAttributeName" validate:"required"`
 	// CloudEvent Extension Context Attribute value
+	// +optional
 	ContextAttributeValue string `json:"contextAttributeValue,omitempty"`
 }
 
 // EventRef defining invocation of a function via event
 type EventRef struct {
-	// Reference to the unique name of a 'produced' event definition
+	// Reference to the unique name of a 'produced' event definition,
+	// +kubebuilder:validation:Required
 	TriggerEventRef string `json:"triggerEventRef" validate:"required"`
 	// Reference to the unique name of a 'consumed' event definition
+	// +kubebuilder:validation:Required
 	ResultEventRef string `json:"resultEventRef" validate:"required"`
-	// ResultEventTimeout defines maximum amount of time (ISO 8601 format) to wait for the result event. If not defined it be set to the actionExecutionTimeout
+	// Maximum amount of time (ISO 8601 format) to wait for the result event. If not defined it be set to the
+	// actionExecutionTimeout
+	// +optional
 	ResultEventTimeout string `json:"resultEventTimeout,omitempty" validate:"omitempty,iso8601duration"`
-	// If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by 'triggerEventRef'.
-	// If object type, a custom object to become the data (payload) of the event referenced by 'triggerEventRef'.
+	// If string type, an expression which selects parts of the states data output to become the data (payload)
+	// of the event referenced by triggerEventRef. If object type, a custom object to become the data (payload)
+	// of the event referenced by triggerEventRef.
+	// +optional
 	Data *Object `json:"data,omitempty"`
-	// Add additional extension context attributes to the produced event
+	// Add additional extension context attributes to the produced event.
+	// +optional
 	ContextAttributes map[string]Object `json:"contextAttributes,omitempty"`
-	// Invoke specifies if the subflow should be invoked sync or async.
-	// Defaults to sync.
+	// Specifies if the function should be invoked sync or async. Default is sync.
+	// +kubebuilder:validation:Enum=async;sync
+	// +kubebuilder:default=sync
 	Invoke InvokeKind `json:"invoke,omitempty" validate:"required,oneof=async sync"`
 }