Extensions

Currently, we define extensions with static YAML documents. The following schema describes the allowed and the required values. For more information about the individual attributes, see which information an extension consists of.

Schema documentation

• idstring (uuid)

  required

  Globally unique identifier of the extension

• contributorIdstring (uuid)

  required

  Identifier of the contributor. Identical to the identifier of the customer/organization in the mStudio

• namestring

  required

  Name of the extension

• descriptionstring

  required

  Short description of the extension. It should explain the extension concisely in less than 300 characters

• detailedDescriptionsobject

  Detailed description of the extension in different languages

  • deobject

    required

    Detailed description of the extension in german

    • markdownstring (≥ 1 characters)

      required

      A markdown text description

    • plainstring (≥ 1 characters)

      A plain text description

  • enobject

    Detailed description of the extension in english

    • markdownstring (≥ 1 characters)

      required

      A markdown text description

    • plainstring (≥ 1 characters)

      A plain text description

• extensionContextstring (one of: project, customer)

  required

  Defines, whether the extension may be added to a project or an organization

• requiredScopesarray of string

  required

  Permissions, the extension requires

  • Array[
  • *string
  ]

externalComponentsobject

required

• backendobject

  required
  • extensionAddedToContextobject

    required
    • urlstring (uri)

      required

      The URL that the mStudio calls when the extension is added to an extension context. May contain placeholders

  • extensionInstanceUpdatedobject

    required
    • urlstring (uri)

      required

      The URL that the mStudio calls when the extension instance is updated. May contain placeholders

  • extensionInstanceSecretRotatedobject

    required
    • urlstring (uri)

      required

      The URL that the mStudio calls when the extension instance secret is rotated. May contain placeholders

  • extensionInstanceRemovedFromContextobject

    required
    • urlstring (uri)

      required

      The URL that the mStudio calls when the extension instance is removed from a context. May contain placeholders

• frontendsobject
  • indexobject
    • urlstring (uri)

      required

      The URL that the user is directed to when they open the extension in the mStudio. May contain placeholders

supportobject

required

• emailstring (email)

  required

  Email address that may be used for support requests

• phonestring (phone)

  Phone number that may be used for support requests

tagsarray of string

Tags that describe the extension

• Array[
• *string
]

stateobject

required

• hiddenboolean

  Defines, whether this extension is visible in the mStudio

• disabledboolean

  Defines, whether instances of this extension may exist

• blockedboolean

  Defines, whether this extension may be added to a context

Example

id: f0f86186-0a5a-45b2-aa33-502777496347
contributorId: f0f86186-0a5a-45b2-aa33-502777496347
name: Example Extension
description: An example extension to show which information is needed to create an extension
detailedDescriptions:
  de:
    markdown: |-
      # Ein Beispiel
      Dies ist eine Beispiel Extension-Beschreibung.
      ## Weitere Informationen
      Hier könnten **weitere** Informationen stehen.
    plain: Eine ausführliche Besipiel Extension-Beschreibung. Diese enthält keine
      Formatierungen.
  en:
    markdown: |-
      # An example
      This is an example extension description.
      ## Further informations
      Here could be **further** informations.
    plain: string
extensionContext: project
requiredScopes:
  - project:read
externalComponents:
  backend:
    extensionAddedToContext:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/added
    extensionInstanceUpdated:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/updated
    extensionInstanceSecretRotated:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/secret-rotated
    extensionInstanceRemovedFromContext:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/removed
  frontends:
    index:
      url: https://example.org/:extensionInstanceId
support:
  email: email@mittwald.example
  phone: +49 170 123456
tags:
  - mail
state:
  hidden: true
  disabled: true
  blocked: true

JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "contributorId",
    "name",
    "description",
    "support",
    "state",
    "extensionContext",
    "requiredScopes",
    "externalComponents"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Globally unique identifier of the extension"
    },
    "contributorId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the contributor. Identical to the identifier of the customer/organization in the mStudio"
    },
    "name": {
      "type": "string",
      "description": "Name of the extension",
      "example": "Example Extension"
    },
    "description": {
      "type": "string",
      "description": "Short description of the extension. It should explain the extension concisely in less than 300 characters",
      "example": "An example extension to show which information is needed to create an extension"
    },
    "detailedDescriptions": {
      "type": "object",
      "description": "Detailed description of the extension in different languages",
      "required": [
        "de"
      ],
      "properties": {
        "de": {
          "type": "object",
          "description": "Detailed description of the extension in german",
          "required": [
            "markdown"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "description": "A markdown text description",
              "minLength": 1,
              "example": "# Ein Beispiel\nDies ist eine Beispiel Extension-Beschreibung.\n## Weitere Informationen\nHier könnten **weitere** Informationen stehen."
            },
            "plain": {
              "type": "string",
              "description": "A plain text description",
              "minLength": 1,
              "example": "Eine ausführliche Besipiel Extension-Beschreibung. Diese enthält keine Formatierungen."
            }
          }
        },
        "en": {
          "type": "object",
          "description": "Detailed description of the extension in english",
          "required": [
            "markdown"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "description": "A markdown text description",
              "minLength": 1,
              "example": "# An example\nThis is an example extension description.\n## Further informations\nHere could be **further** informations."
            },
            "plain": {
              "type": "string",
              "description": "A plain text description",
              "minLength": 1,
              "exmple": "A detailed example extension description. This does not contain any formatting."
            }
          }
        }
      }
    },
    "extensionContext": {
      "type": "string",
      "enum": [
        "project",
        "customer"
      ],
      "description": "Defines, whether the extension may be added to a project or an organization"
    },
    "requiredScopes": {
      "type": "array",
      "items": {
        "type": "string",
        "example": "project:read"
      },
      "description": "Permissions, the extension requires"
    },
    "externalComponents": {
      "type": "object",
      "required": [
        "backend"
      ],
      "properties": {
        "backend": {
          "type": "object",
          "required": [
            "extensionAddedToContext",
            "extensionInstanceUpdated",
            "extensionInstanceSecretRotated",
            "extensionInstanceRemovedFromContext"
          ],
          "properties": {
            "extensionAddedToContext": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "The URL that the mStudio calls when the extension is added to an extension context. May contain placeholders",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/added"
                }
              }
            },
            "extensionInstanceUpdated": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "The URL that the mStudio calls when the extension instance is updated. May contain placeholders",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/updated"
                }
              }
            },
            "extensionInstanceSecretRotated": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "The URL that the mStudio calls when the extension instance secret is rotated. May contain placeholders",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/secret-rotated"
                }
              }
            },
            "extensionInstanceRemovedFromContext": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "The URL that the mStudio calls when the extension instance is removed from a context. May contain placeholders",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/removed"
                }
              }
            }
          }
        },
        "frontends": {
          "type": "object",
          "properties": {
            "index": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "The URL that the user is directed to when they open the extension in the mStudio. May contain placeholders",
                  "example": "https://example.org/:extensionInstanceId"
                }
              }
            }
          }
        }
      }
    },
    "support": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address that may be used for support requests"
        },
        "phone": {
          "type": "string",
          "format": "phone",
          "description": "Phone number that may be used for support requests",
          "example": "+49 170 123456"
        }
      }
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "example": "mail"
      },
      "description": "Tags that describe the extension"
    },
    "state": {
      "type": "object",
      "properties": {
        "hidden": {
          "type": "boolean",
          "description": "Defines, whether this extension is visible in the mStudio"
        },
        "disabled": {
          "type": "boolean",
          "description": "Defines, whether instances of this extension may exist"
        },
        "blocked": {
          "type": "boolean",
          "description": "Defines, whether this extension may be added to a context"
        }
      }
    }
  }
}