Clarify ParamValue syntax

This commit updates the API spec docs to clarify that ParamValues can be strings, lists of strings, and maps of string to string. Since we use a custom unmarshaling function, the user-specified syntax doesn't actually contain the fields "type", "stringVal", "arrayVal", and "objectVal". This commit also removes the JSON struct tags for this field, which serve no functional purpose. This helps clarify that param values undergo custom unmarshalling. More investigation is needed to determine how to correctly display this field in autogenerated OpenAPI docs. This will happen in a later commit.
tektoncd · Apr 4, 2023 · 428166c · 428166c
1 parent ecb11fc
commit 428166c
Show file tree

Hide file tree

Showing 9 changed files with 56 additions and 53 deletions.
diff --git a/docs/api-spec.md b/docs/api-spec.md
@@ -14,13 +14,13 @@
 - [Status Signalling](#status-signalling)
 - [Listing Resources](#listing-resources)
 - [Detailed Resource Types - v1beta1](#detailed-resource-types---v1beta1)
-  * [`ParamValue`](#paramvalue)
   * [`ContainerStateRunning`](#containerstaterunning)
   * [`ContainerStateWaiting`](#containerstatewaiting)
   * [`ContainerStateTerminated`](#containerstateterminated)
   * [`EnvVar`](#envvar)
   * [`Param`](#param)
   * [`ParamSpec`](#paramspec)
+  * [`ParamValue`](#paramvalue)
   * [`Step`](#step)
   * [`StepState`](#stepstate)
   * [`TaskResult`](#taskresult)
@@ -186,15 +186,6 @@ List responses have the following fields (based on [`meta.v1/ListMeta`](https://
 
 ## Detailed Resource Types - v1beta1
 
-### `ParamValue`
-
-| Field Name  | Field Type | Requirement |
-|-------------|------------|-------------|
-| `type`      | Enum:<br>- `"string"` (default)<br>- `"array"` <br>- `"object"` | REQUIRED |
-| `stringVal` | string     | REQUIRED    |
-| `arrayVal`  | []string   | REQUIRED    |
-| `objectVal` | map<string,string>   | REQUIRED    |
-
 ### `ContainerStateRunning`
 
 | Field Name   | Field Type | Requirement |
@@ -236,7 +227,7 @@ List responses have the following fields (based on [`meta.v1/ListMeta`](https://
 | Field Name | Field Type      | Requirement |
 |------------|-----------------|-------------|
 | `name`     | string          | REQUIRED    |
-| `value`    | `ParamValue` | REQUIRED    |
+| `value`    | `ParamValue`    | REQUIRED    |
 
 ### `ParamSpec`
 
@@ -248,6 +239,10 @@ List responses have the following fields (based on [`meta.v1/ListMeta`](https://
 | `properties`  | map<string,PropertySpec> |RECOMMENDED <br><br>note: `PropertySpec` is a type that defines the spec of an individual key. See how to define the `properties` section in the [example](../examples/v1beta1/taskruns/alpha/object-param-result.yaml).|
 | `default`     | `ParamValue` | REQUIRED |
 
+### `ParamValue`
+
+A `ParamValue` may be a string, a list of string, or a map of string to string.
+
 ### `Step`
 
 | Field Name   | Field Type | Requirement |

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1788,7 +1788,7 @@ Used to distinguish between a single string and an array of strings.</p>
 <tbody>
 <tr>
 <td>
-<code>type</code><br/>
+<code>Type</code><br/>
 <em>
 <a href="#tekton.dev/v1.ParamType">
 ParamType
@@ -1800,7 +1800,7 @@ ParamType
 </tr>
 <tr>
 <td>
-<code>stringVal</code><br/>
+<code>StringVal</code><br/>
 <em>
 string
 </em>
@@ -1811,7 +1811,7 @@ string
 </tr>
 <tr>
 <td>
-<code>arrayVal</code><br/>
+<code>ArrayVal</code><br/>
 <em>
 []string
 </em>
@@ -1821,7 +1821,7 @@ string
 </tr>
 <tr>
 <td>
-<code>objectVal</code><br/>
+<code>ObjectVal</code><br/>
 <em>
 map[string]string
 </em>
@@ -9501,7 +9501,7 @@ Used to distinguish between a single string and an array of strings.</p>
 <tbody>
 <tr>
 <td>
-<code>type</code><br/>
+<code>Type</code><br/>
 <em>
 <a href="#tekton.dev/v1beta1.ParamType">
 ParamType
@@ -9513,7 +9513,7 @@ ParamType
 </tr>
 <tr>
 <td>
-<code>stringVal</code><br/>
+<code>StringVal</code><br/>
 <em>
 string
 </em>
@@ -9524,7 +9524,7 @@ string
 </tr>
 <tr>
 <td>
-<code>arrayVal</code><br/>
+<code>ArrayVal</code><br/>
 <em>
 []string
 </em>
@@ -9534,7 +9534,7 @@ string
 </tr>
 <tr>
 <td>
-<code>objectVal</code><br/>
+<code>ObjectVal</code><br/>
 <em>
 map[string]string
 </em>

diff --git a/hack/ignored-openapi-violations.list b/hack/ignored-openapi-violations.list
@@ -7,6 +7,14 @@ API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,SidecarState,ContainerName
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepState,ContainerName
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,TaskRunStatusFields,TaskRunResults
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamValue,ArrayVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamValue,ObjectVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamValue,StringVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamValue,Type
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamValue,ArrayVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamValue,ObjectVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamValue,StringVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamValue,Type
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/resource/v1alpha1,PipelineResourceSpec,SecretParams
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,Step,DeprecatedLifecycle
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,Step,DeprecatedLivenessProbe

diff --git a/pkg/apis/pipeline/v1/openapi_generated.go b/pkg/apis/pipeline/v1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1/param_types.go b/pkg/apis/pipeline/v1/param_types.go
@@ -377,11 +377,11 @@ var AllParamTypes = []ParamType{ParamTypeString, ParamTypeArray, ParamTypeObject
 // Used in JSON unmarshalling so that a single JSON field can accept
 // either an individual string or an array of strings.
 type ParamValue struct {
-	Type      ParamType `json:"type"` // Represents the stored type of ParamValues.
-	StringVal string    `json:"stringVal"`
+	Type      ParamType // Represents the stored type of ParamValues.
+	StringVal string
 	// +listType=atomic
-	ArrayVal  []string          `json:"arrayVal"`
-	ObjectVal map[string]string `json:"objectVal"`
+	ArrayVal  []string
+	ObjectVal map[string]string
 }
 
 // UnmarshalJSON implements the json.Unmarshaller interface.

diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -388,33 +388,33 @@
       "description": "ResultValue is a type alias of ParamValue",
       "type": "object",
       "required": [
-        "type",
-        "stringVal",
-        "arrayVal",
-        "objectVal"
+        "Type",
+        "StringVal",
+        "ArrayVal",
+        "ObjectVal"
       ],
       "properties": {
-        "arrayVal": {
+        "ArrayVal": {
           "type": "array",
           "items": {
             "type": "string",
             "default": ""
           },
           "x-kubernetes-list-type": "atomic"
         },
-        "objectVal": {
+        "ObjectVal": {
           "type": "object",
           "additionalProperties": {
             "type": "string",
             "default": ""
           }
         },
-        "stringVal": {
+        "StringVal": {
           "description": "Represents the stored type of ParamValues.",
           "type": "string",
           "default": ""
         },
-        "type": {
+        "Type": {
           "type": "string",
           "default": ""
         }

diff --git a/pkg/apis/pipeline/v1beta1/openapi_generated.go b/pkg/apis/pipeline/v1beta1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1beta1/param_types.go b/pkg/apis/pipeline/v1beta1/param_types.go
@@ -370,11 +370,11 @@ var AllParamTypes = []ParamType{ParamTypeString, ParamTypeArray, ParamTypeObject
 // Used in JSON unmarshalling so that a single JSON field can accept
 // either an individual string or an array of strings.
 type ParamValue struct {
-	Type      ParamType `json:"type"` // Represents the stored type of ParamValues.
-	StringVal string    `json:"stringVal"`
+	Type      ParamType // Represents the stored type of ParamValues.
+	StringVal string
 	// +listType=atomic
-	ArrayVal  []string          `json:"arrayVal"`
-	ObjectVal map[string]string `json:"objectVal"`
+	ArrayVal  []string
+	ObjectVal map[string]string
 }
 
 // ArrayOrString is deprecated, this is to keep backward compatibility

diff --git a/pkg/apis/pipeline/v1beta1/swagger.json b/pkg/apis/pipeline/v1beta1/swagger.json
@@ -647,33 +647,33 @@
       "description": "ResultValue is a type alias of ParamValue",
       "type": "object",
       "required": [
-        "type",
-        "stringVal",
-        "arrayVal",
-        "objectVal"
+        "Type",
+        "StringVal",
+        "ArrayVal",
+        "ObjectVal"
       ],
       "properties": {
-        "arrayVal": {
+        "ArrayVal": {
           "type": "array",
           "items": {
             "type": "string",
             "default": ""
           },
           "x-kubernetes-list-type": "atomic"
         },
-        "objectVal": {
+        "ObjectVal": {
           "type": "object",
           "additionalProperties": {
             "type": "string",
             "default": ""
           }
         },
-        "stringVal": {
+        "StringVal": {
           "description": "Represents the stored type of ParamValues.",
           "type": "string",
           "default": ""
         },
-        "type": {
+        "Type": {
           "type": "string",
           "default": ""
         }