Merge pull request #39237 from Srivaralakshmi/DataModelSBO

Document data model

Author: Preeticp

applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc

@@ -11,7 +11,7 @@ Application developers need access to backing services to build and connect work
 The {servicebinding-title} enables application developers to easily bind workloads together with operator-managed backing services, without any manual procedures to configure the binding connection. For the {servicebinding-title} to provide the binding data, as an Operator provider or user who creates backing services, you must expose the binding data to be automatically detected by the {servicebinding-title}. Then, the {servicebinding-title} automatically collects the binding data from the backing service and shares it with a workload to provide a consistent and predictable experience.
 
 include::modules/sbo-methods-of-exposing-binding-data.adoc[leveloffset=+1]
-
+include::modules/sbo-data-model.adoc[leveloffset=+1]
 include::modules/sbo-categories-of-exposable-binding-data.adoc[leveloffset=+1]
 
 == Additional resources

modules/sbo-data-model.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service
+[id="sbo-data-model_{context}"]
+= Data model
+
+Service binding annotations must use the following convention:
+
+[source,yaml]
+----
+service.binding(/<NAME>)?:
+    "<VALUE>|(path=<JSONPATH_TEMPLATE>(,objectType=<OBJECT_TYPE>)?(,elementType=<ELEMENT_TYPE>)?(,sourceKey=<SOURCE_KEY>)?(,sourceValue=<SOURCE_VALUE>)?)"
+----
+where:
+[horizontal]
+`<NAME>`:: Specifies the name under which the binding value is to be exposed. You can exclude it only when the `objectType` parameter is set to `Secret` or `ConfigMap`.
+`<VALUE>`:: Specifies the constant value exposed when no `path` is set.
+
+This section explains the data model used in the annotations and OLM descriptors. The data model is the same for custom resource definition (CRD) or custom resource (CR) annotations and Operator Lifecycle Manager (OLM) descriptors, but the syntax differs.
+
+The data model provides the details on the allowed values and semantic for the `path`, `elementType`, `objectType`, `sourceKey`, and `sourceValue` parameters.
+
+.Parameters and their descriptions
+[cols="3,6,4",options="header"]
+|===
+|Parameter
+|Description
+|Default value
+
+|`path`
+|JSONPath template that consists JSONPath expressions enclosed by curly braces {}.
+|N/A
+
+|`elementType`
+a|Specifies whether the value of the element referenced in the `path` parameter complies with any one of the following types:
+
+* `string`
+* `sliceOfStrings`
+* `sliceOfMaps`
+|`string`
+
+|`objectType`
+|Specifies whether the value of the element indicated in the `path` parameter refers to a `ConfigMap`, `Secret`, or plain string in the current namespace.
+|`Secret`, if `elementType` is non-string.
+
+
+|`sourceKey`
+a|Specifies the key in the `ConfigMap` or `Secret` resource to be added to the binding secret when collecting the binding data. +
+
+Note:
+
+* When used in conjunction with `elementType`=`sliceOfMaps`, the `sourceKey` parameter specifies the key in the slice of maps whose value is used as a key in the binding secret.
+* Use this optional parameter to expose a specific entry in the referenced `Secret` or `ConfigMap` resource as binding data.
+* When not specified, all keys and values from the `Secret` or `ConfigMap` resource are exposed and are added to the binding secret.
+|N/A
+
+|`sourceValue`
+a|Specifies the key in the slice of maps. +
+
+Note:
+
+* The value of this key is used as the base to generate the value of the entry for the key-value pair to be added to the binding secret.
+* In addition, the value of the `sourceKey` is used as the key of the entry for the key-value pair to be added to the binding secret.
+* It is mandatory only if `elementType`=`sliceOfMaps`.
+|N/A
+|===
+
+[NOTE]
+====
+The `sourceKey` and `sourceValue` parameters are applicable only if the element indicated in the `path` parameter refers to a `ConfigMap` or `Secret` resource.
+====