Items manifest

The information needed to create or edit an item (or, better yet, an item release) must be provided through a manifest, a JSON representation of the data to store on the database.

Manifests top-level structure is the same for any item, while the content of the resources property is specific for each item type.

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": {
          "format": "uri-reference",
          "type": "string"
        }
      },
      "required": [
        "type",
        "url"
      ],
      "type": "object"
    },
    "imageUrl": {
      "description": "Url of the image associated with the item",
      "format": "uri-reference",
      "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",
      "format": "uri-reference",
      "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",
      "format": "uri-reference",
      "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. It must match a CRD resources.name property",
      "type": "string"
    },
    "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",
    "type",
    "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.

Permissions

To create or edit items, users must have the role of Company Owner or Project Administrator in the Company the item belongs to.

On top of that, the specific permission marketplace.root.manage is needed to set or edit these restricted properties:

• publishOnMiaDocumentation
• supportedBy
• supportedByImage
• visibility