Software Catalog manifests

A manifest is a JSON representation of an entity that can be applied to the Catalog.

Item Type Definition

The manifest of an ITD contains metadata about the definition itself and specifications regarding the items of the defined type.

tip

The full JSON schema is available on GitHub.

Schema Viewer

Loading ....

Raw JSON Schema

{
  "$id": "catalog-itd.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Software Catalog Item Type Definition",
  "description": "Data model of a Software Catalog Item Type Definition",
  "type": "object",
  "properties": {
    "apiVersion": {
      "const": "software-catalog.mia-platform.eu/v1"
    },
    "kind": {
      "const": "item-type-definition"
    },
    "metadata": {
      "description": "Descriptive properties referring to this type definition entity itself",
      "type": "object",
      "properties": {
        "namespace": {
          "description": "Read-only namespace the resource belongs to and within which its name must be unique",
          "type": "object",
          "properties": {
            "scope": {
              "const": "tenant"
            },
            "id": {
              "description": "Identifier of the tenant",
              "type": "string",
              "minLength": 1
            }
          },
          "additionalProperties": false,
          "required": [
            "scope",
            "id"
          ]
        },
        "name": {
          "description": "Read-only RFC-1035 compliant string that uniquely identifies the resource within its namespace. Must match the `spec.itemType` field",
          "type": "string",
          "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$",
          "minLength": 1,
          "maxLength": 63
        },
        "visibility": {
          "description": "Visibility on the resource",
          "oneOf": [
            {
              "description": "Resource visible to all tenants of the Console installation",
              "type": "object",
              "properties": {
                "scope": {
                  "const": "console"
                }
              },
              "required": [
                "scope"
              ]
            },
            {
              "description": "Resource visible to a subset of tenants",
              "type": "object",
              "properties": {
                "scope": {
                  "const": "tenant"
                },
                "ids": {
                  "description": "Identifies of the tenants with visibility on the resource. For now, it can only contain the namespace of the resource",
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "minItems": 1,
                  "maxItems": 1
                }
              },
              "required": [
                "scope",
                "ids"
              ]
            }
          ]
        },
        "displayName": {
          "description": "Display name of the resource. Clients may also use it as the display name associated with the items of the defined type",
          "type": "string",
          "minLength": 1
        },
        "description": {
          "description": "Display name of the resource. Clients may also use it as the description associated with the items of the defined type",
          "type": "string"
        },
        "icon": {
          "description": "Icon of the resource. Clients may also use it as the icon associated with the items of the defined type",
          "type": "object",
          "properties": {
            "mediaType": {
              "description": "MIME type of the image",
              "type": "string",
              "enum": [
                "image/png",
                "image/svg+xml"
              ]
            },
            "base64Data": {
              "description": "Image data encoded in Base64 format",
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "mediaType",
            "base64Data"
          ]
        },
        "documentation": {
          "description": "Documentation regarding the resource. Clients may also use it as the documentation associated with the items of the defined type",
          "oneOf": [
            {
              "description": "External documentation",
              "type": "object",
              "properties": {
                "type": {
                  "const": "external"
                },
                "url": {
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "type",
                "url"
              ]
            }
          ]
        },
        "labels": {
          "description": "Set of identifying key/value pairs akin to Kubernetes object labels",
          "type": "object",
          "patternProperties": {
            "^([a-zA-Z0-9][a-zA-Z0-9\\.\\-]{0,253}[\\/])?([a-zA-Z0-9][a-zA-Z0-9\\.\\-]{0,63}[a-zA-Z0-9]?)$": {
              "type": "string",
              "pattern": "^$|^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,61}[a-zA-Z0-9])?$",
              "maxLength": 63
            }
          },
          "additionalProperties": false
        },
        "annotations": {
          "description": "Set of non-identifying key/value pairs akin to Kubernetes object annotations",
          "type": "object",
          "patternProperties": {
            "^([a-zA-Z0-9][a-zA-Z0-9\\.\\-]{0,253}[\\/])?([a-zA-Z0-9][a-zA-Z0-9\\.\\-]{0,63}[a-zA-Z0-9]?)$": {
              "type": "string",
              "pattern": "^$|^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,61}[a-zA-Z0-9])?$",
              "maxLength": 63
            }
          },
          "additionalProperties": false
        },
        "tags": {
          "description": "List of single-valued strings",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9:+#]+(-[a-z0-9:+#]+)*$",
            "minLength": 1,
            "maxLength": 63
          }
        },
        "links": {
          "description": "List of external hyperlinks",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "description": "URL in standard uri format",
                "type": "string"
              },
              "displayName": {
                "description": "User friendly display name for the link",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "url"
            ]
          }
        },
        "maintainers": {
          "description": "List of organizational entities maintaining the resource",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "description": "Display name of the entity",
                "type": "string",
                "minLength": 1
              },
              "email": {
                "description": "Contact email of the entity",
                "type": "string",
                "format": "email",
                "minLength": 1
              }
            },
            "additionalProperties": false,
            "required": [
              "name"
            ]
          }
        },
        "publisher": {
          "description": "Entity providing the resource",
          "type": "object",
          "properties": {
            "name": {
              "description": "Display name of the entity",
              "type": "string",
              "minLength": 1
            },
            "url": {
              "description": "Link to the entity webpage",
              "type": "string",
              "minLength": 1
            },
            "image": {
              "description": "Entity logo or relevant image",
              "type": "object",
              "properties": {
                "mediaType": {
                  "description": "MIME type of the image",
                  "type": "string",
                  "enum": [
                    "image/png",
                    "image/svg+xml"
                  ]
                },
                "base64Data": {
                  "description": "Image data encoded in Base64 format",
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "mediaType",
                "base64Data"
              ]
            }
          },
          "additionalProperties": false,
          "required": [
            "name"
          ]
        }
      },
      "additionalProperties": true,
      "required": [
        "namespace",
        "name",
        "visibility"
      ]
    },
    "spec": {
      "description": "State definition referring to the items of the type defined by this type definition entity",
      "type": "object",
      "properties": {
        "type": {
          "description": "Read-only item type defined by the type definition. It must match the `metadata.name` field",
          "type": "string",
          "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$",
          "minLength": 1,
          "maxLength": 63
        },
        "scope": {
          "description": "Software Catalog scope where items of the defined type should be managed",
          "type": "string",
          "enum": [
            "tenant"
          ]
        },
        "isVersioningSupported": {
          "description": "Whether the defined item type supports versioning",
          "type": "boolean"
        },
        "validation": {
          "description": "Indication on how to validate the defined item type resources",
          "oneOf": [
            {
              "description": "Validation through JSON schema",
              "type": "object",
              "properties": {
                "mechanism": {
                  "const": "json-schema"
                },
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "additionalProperties": false,
              "required": [
                "mechanism",
                "schema"
              ]
            }
          ]
        },
        "controlledFields": {
          "description": "List of fields managed by the Catalog",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "jsonPath": {
                "description": "JSON path to access the marketplace item value",
                "type": "string"
              },
              "key": {
                "description": "Unique name of the field",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "key",
              "jsonPath"
            ]
          }
        }
      },
      "additionalProperties": true,
      "required": [
        "type",
        "scope",
        "validation"
      ]
    },
    "__v": {
      "description": "Read-only opaque value that represents the internal version of the document",
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false,
  "required": [
    "apiVersion",
    "kind",
    "metadata",
    "spec"
  ]
}

Example

example not provided

Item

Item manifests partially varies based on the referenced ITD: the top-level structure of the manifest is the same for any item, while the content of the resources property is specific for each ITD.

What follows is the formal definition of a generic manifest, with the other pages of this section documenting how the assets (field resources) should be shaped for each type.

tip

The full JSON schema is available on GitHub.

Schema Viewer

Loading ....

Raw JSON Schema

{
  "$id": "catalog-item-manifest.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Catalog item manifest",
  "description": "Data model of a Catalog item to apply",
  "type": "object",
  "properties": {
    "categoryId": {
      "description": "Identifier of the item's category",
      "type": "string"
    },
    "description": {
      "description": "Brief description of the item",
      "type": "string"
    },
    "documentation": {
      "description": "Documentation of the item",
      "properties": {
        "type": {
          "enum": [
            "externalLink",
            "markdown"
          ],
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "url"
      ],
      "type": "object"
    },
    "imageUrl": {
      "description": "Url of the image associated with the item",
      "type": "string"
    },
    "itemId": {
      "description": "RFC-1035 compliant identifier of the item. It forms a composite PK with tenantId and, if present, version.name",
      "minLength": 1,
      "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$",
      "type": "string"
    },
    "lifecycleStatus": {
      "description": "Lifecycle status of the item",
      "enum": [
        "coming-soon",
        "draft",
        "published",
        "maintenance",
        "deprecated",
        "archived"
      ],
      "type": "string"
    },
    "name": {
      "description": "Human-readable name of the item",
      "minLength": 1,
      "type": "string"
    },
    "providerId": {
      "description": "Identifier of the provider used to retrieve markdown documentation content and external resources, if supported by the item type",
      "type": "string"
    },
    "publishOnMiaDocumentation": {
      "description": "Flag stating if the resource documentation should be published on Mia-Platform public documentation",
      "type": "boolean"
    },
    "releaseDate": {
      "description": "Creation date of this item's release",
      "format": "date-time",
      "type": "string"
    },
    "repositoryUrl": {
      "description": "URL of the repository containing the source code of the resource created by the item",
      "type": "string"
    },
    "resources": {
      "additionalProperties": true,
      "description": "Representation of the resource that will be created starting from this item. It could be validated through the matching CRD",
      "type": "object"
    },
    "supportedBy": {
      "description": "Identifier of the company that has produced the item",
      "type": "string"
    },
    "supportedByImageUrl": {
      "description": "Url of the image associated with the company that has produced the item",
      "type": "string"
    },
    "tenantId": {
      "description": "Identifier of the tenant to which the item belongs. It forms a composite PK with itemId and, if present, version.name",
      "type": "string"
    },
    "type": {
      "description": "Type of the item. Deprecated in favour of `itemTypeDefinitionRef`. At least one among `type` and `itemTypeDefinitionRef` must be set. If both are set, `type` will be ignored",
      "type": "string",
      "deprecated": true
    },
    "itemTypeDefinitionRef": {
      "description": "Reference to an Item Type Definition in the form of its composite primary key. At least one among `type` and `itemTypeDefinitionRef` must be set. If both are set, `type` will be ignored",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the Item Type Definition (references `itd.metadata.name`)",
          "type": "string",
          "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$",
          "minLength": 1,
          "maxLength": 63
        },
        "namespace": {
          "description": "ID of the Item Type Definition namespace (references `itd.metadata.namespace.id`)",
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "name",
        "namespace"
      ],
      "additionalProperties": false
    },
    "version": {
      "description": "Version of the item following semver",
      "properties": {
        "name": {
          "description": "Semantic version",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
          "type": "string"
        },
        "releaseNote": {
          "description": "Markdown release note",
          "type": "string"
        },
        "security": {
          "description": "Flag stating if the version addresses any vulnerability",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "releaseNote"
      ],
      "type": "object"
    },
    "visibility": {
      "description": "Visibility of the item",
      "properties": {
        "allTenants": {
          "default": false,
          "description": "If true, the item will be accessible to all companies",
          "type": "boolean"
        },
        "public": {
          "default": false,
          "description": "If true, the item will be accessible from any user that access the Console, even if not authenticated",
          "type": "boolean"
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "name",
    "itemId",
    "tenantId",
    "resources",
    "lifecycleStatus"
  ]
}

Example

example not provided

Categories

Items can be organized in categories with the field catagoryId. The available categories are pre-defined, and can be found here.