Items data structure
An item (also referred to as a component) is the basic unit of the Catalog and represents a software resource that can be utilized in Mia-Platform Projects.
An item is always defined in a specific Company (field tenantId) and must have an identifier (field itemId) that is unique for that Company (i.e., two items can have the same itemId as long as they have a different tenantId).
On top of that, items have versions (filed version.name) and multiple instances of the same tenantId and itemId can occur for different version.name values.
To summarize, an item is univocally defined by the combination of its tenantId, itemId, and version.name fields.
Another defining property of an item is the type (field type) that determines how the item is handled by the Console.
Linked to the type are the assets (field resources), type-specific information needed to work with an item (e.g., the Docker image of a plugin, or the endpoints exposed by an application).
An item lives through different development phases (field lifecycleStatus), and its availability (field visibility) can be controlled for a better distribution.
Item fields
Practically speaking, an item is a JSON document containing some defining keys, a set of metadata, and the resources needed to make use of it.
The full JSON schema is available on GitHub.
- Schema Viewer
- Raw JSON Schema
- Example
{
"$id": "catalog-item.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Catalog item",
"description": "Data model of a Catalog item",
"type": "object",
"properties": {
"_id": {
"description": "Database identifier of the item",
"type": "string"
},
"category": {
"description": "Identifier of the item's category",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"label"
]
},
"componentsIds": {
"description": "List of source component ids of the services in the item's resources",
"items": {
"type": "string"
},
"type": "array"
},
"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"
},
"isLatest": {
"description": "Flag stating if the the current document is the latest version of the item",
"type": "boolean"
},
"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": [
"_id",
"name",
"itemId",
"tenantId",
"type",
"releaseDate",
"lifecycleStatus"
]
}
example not provided