feat: update Software Catalog items manifests doc (#2105)

* feat: update Software Catalog items manifests doc

* fix link

Author: epessina

docs/software-catalog/items-manifest/example.md

@@ -9,6 +9,10 @@ import SchemaViewer from "../snippets/schema_viewer.mdx";
 
 Examples works no differently than [templates](/software-catalog/items-manifest/template.md), in the sense that they too provide an **archive** with base configurations. Unlike templates, examples should come with some features already implemented and tailored to help the user better familiarize with the development environment.
 
+:::tip
+Any additional information presented in the [template section](/software-catalog/items-manifest/template.md) will work for example items.
+:::
+
 To [create or edit](/software-catalog/items-management/overview.md) an example, you need to provide a [manifest](/software-catalog/items-manifest/overview.md), whose `resources` property should adhere to the following JSON schema.
 
 :::tip

docs/software-catalog/items-manifest/extension.md

@@ -7,7 +7,7 @@ sidebar_label: Extension
 import { catalogWellKnownItems } from "@mia-platform/console-types";
 import SchemaViewer from "../snippets/schema_viewer.mdx";
 
-Extensions are **custom pages** that enhances Console capabilities by integrating it into the sidebar navigation. Since extensions have their own [dedicated section](/console/company-configuration/extensions.md), they are left out by the [Software Catalog UI][ui]. Extensions can still be managed with [miactl][miactl], and API calls.
+Extensions are **custom pages** that enhances Console capabilities by integrating it into the sidebar navigation.
 
 To [create or edit](/software-catalog/items-management/overview.md) an extension, you need to provide a [manifest](/software-catalog/items-manifest/overview.md), whose `resources` property should adhere to the following JSON schema.
 

docs/software-catalog/items-manifest/img/type-array-validation.png

@@ -4,6 +4,9 @@ title: Infrastructure resource
 sidebar_label: Infrastructure resource
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 import { catalogWellKnownItems } from "@mia-platform/console-types";
 import SchemaViewer from "../snippets/schema_viewer.mdx";
 
@@ -16,3 +19,248 @@ The JSON schemas of the [infrastructure resource resources](https://raw.githubus
 :::
 
 <SchemaViewer schema={catalogWellKnownItems['custom-resource'].resourcesSchema} />
+
+## Monitor a Custom Kubernetes Resource in the Runtime area
+
+If you've upgraded to Console release `v13.3.0`, you can now view the status of your Current Kubernetes Resources directly in the Runtime section. To enable this feature, [publish a new version](/software-catalog/items-management/ui.md#create-a-new-version) of your infrastructure resource that include the fields `runtime`.
+
+## Generate dynamic form to customize validation
+
+If you have upgraded the Console to version `v13.6.1`, you can now generate a dynamic form. This documentation serves as a guide for users to understand and effectively utilize the dynamic form fields generated from a JSON schema. By following the examples and descriptions provided, users can create forms that are both functional and user-friendly, ensuring a smooth data entry experience. 
+
+:::info
+In the next versions of the Console we want to add dynamic form generation also in the details section.
+:::
+
+The Frontend of the Console generate the Form using the roles below:
+
+### Supported JSON Schema Types
+
+<Tabs groupId="types" queryString>
+  <TabItem value="type-object" label="type Object" default>
+
+#### Object field
+
+Visualized as Editor
+
+![type-object](./img/type-object.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "required": ["mirroring"],
+        "properties" {
+          "mirroring": { "type": "object", "description": "Mirroring defines the Mirroring service configuration" }
+        }
+      }
+    }
+    ```
+
+##### Validation
+
+The editor generated from this type can validate with [ajv library](https://ajv.js.org/) the sub schema used to fields
+
+![type-object-validation](img/type-object-validation.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "required": ["mirroring"],
+        "properties" {
+          "mirroring": { 
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" }
+            } 
+          }
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+  <TabItem value="type-array" label="type Array">
+
+#### Array field
+
+Visualized as Editor
+
+![type-array](img/type-array.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "services": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "healthCheck": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "followRedirects": { "type": "boolean" },
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+    
+##### Validation
+
+The editor generated from this type can validate with [ajv library](https://ajv.js.org/) the sub schema used to fields
+
+![type-array-validation](img/type-array-validation.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "services": {
+            "items": {
+              "type": "object",
+              "properties": {
+                "healthCheck": {
+                  "type": "object",
+                  "properties": {
+                    "followRedirects": { "type": "boolean" },
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+
+  <TabItem value="type-string" label="type String">
+
+#### String type
+
+Used for textual input. It can include various validations such as minimum and maximum length.
+When using a string field, ensure that the input meets the specified length requirements.
+
+![type-string](img/type-string.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "type": "string",
+          "minLength": 5,
+          "maxLength": 100,
+          "description": "Enter your full name."
+        }
+      }
+    }
+    ```
+
+
+  </TabItem>
+
+  <TabItem value="type-boolean" label="type Boolean">
+
+The boolean type is used for true/false values. This is typically represented as a switch in the form.
+    
+![boolean](img/type-boolean.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "boolean": {
+            "type": "boolean",
+            "description": "Do you agree to the terms and conditions?"
+          }
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+
+  <TabItem value="type-integer" label="type Integer">
+
+#### Integer type
+
+Specifically for whole numbers. It behaves similarly to the number type but restricts input to integers.
+
+![type-int-or-number](img/type-int-or-number.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "integer": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10,
+            "description": "Enter an integer between 1 and 10."
+          }
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+  <TabItem value="type-number" label="type Number">
+
+#### Number type
+
+Used for numerical input, which can include both integers and floating-point numbers.
+
+![type-int-or-number](img/type-int-or-number.png)
+
+    ```json
+    {
+      "jsonSchema": {
+        "type": "object",
+        "properties": {
+          "number": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Enter a value between 0 and 100"
+          }
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+</Tabs>
+
+### Unsupported JSON Schema Features
+
+While our dynamic form fields support a wide range of JSON schema features, there are certain features that are not supported. 
+Additionally, being aware of the unsupported features will help users avoid potential issues when designing their schemas.
+Below is a list of unsupported features:
+
+- **$ref**: Reference to external schemas
+- **oneOf**: Validation against one of the specified schemas
+- **allOf**: Validation against all of the specified schemas
+- **anyOf**: Validation against any of the specified schemas
+- **not**: Validation against the negation of the specified schema
+- **string** format: Specific string formats such as email, date, etc
+- **number** exclusiveMinimum and exclusiveMaximum: Exclusive range validation for numbers
+- **dependencies**: Conditional validation based on the presence of other fields
+
+#### Partially supported JSON Schema Features
+
+- **additionalProperties**: Validation of additional properties work only for types array or object in the schema
+- **patternProperties**: Validation of properties matching a specific pattern

docs/software-catalog/items-manifest/img/type-array.png

@@ -18,6 +18,10 @@ The full JSON schema is available [on GitHub](https://raw.githubusercontent.com/
 
 <SchemaViewer schema={catalogItemManifestSchema} />
 
+## Categories
+
+Items can be organized in categories with the field `catagoryId`. The available categories are pre-defined, and can be found [here](https://raw.githubusercontent.com/mia-platform-marketplace/public-catalog/refs/heads/main/assets/categories.json).
+
 ## Permissions
 
 To create or edit items, users must have the [role](/development_suite/identity-and-access-management/console-levels-and-permission-management.md#identity-capabilities-inside-console) of **Company Owner** or **Project Administrator** in the Company the item belongs to.

docs/software-catalog/items-manifest/img/type-boolean.png

@@ -17,3 +17,38 @@ The JSON schemas of the [plugin resources](https://raw.githubusercontent.com/mia
 :::
 
 <SchemaViewer schema={catalogWellKnownItems['plugin'].resourcesSchema} />
+
+## Values interpolation
+
+The values of the `defaultLabels`, `defaultAnnotations`, and `defaultEnvironmentVariables` fields can contain **placeholders** that will be replaced with the actual values when a Console user creates the service.
+
+Here is an exhaustive list of the placeholders that can be used:
+
+- `%MICROSERVICE_NAME%`: the name of the created microservice.
+- `%PROJECT_ID%`: the human-readable ID of the project. It is a dash-separated string generated by the Console when a project is created, based on the project name.
+- `%COMPANY_ID%`: the ID of the company that owns the project.
+- `%TENANT_ID%`: alias for `%COMPANY_ID%`.
+
+:::info
+Any unrecognized placeholder will be left as is in the final value.
+:::
+
+As example, consider a plugin with the following `defaultEnvironmentVariables`:
+
+```json
+[
+  {
+    "name": "SOME_ENV_VAR",
+    "value": "ms name: %MICROSERVICE_NAME%; project id: %PROJECT_ID%; company id: %COMPANY_ID%"
+  }
+]
+```
+
+Given a Project with the id `my-project`, and a Company with the ID `my-company`, if user creates a microservice named `my-ms` from such plugin, the result will be:
+
+```json
+{
+   "name": "SOME_ENV_VAR",
+   "value": "ms name: my-ms; project id: my-project; company id: my-company"
+}
+```