Schemas

A schema defines the attributes and types expected from an extension to work correctly on a given extension point. They are created using a .graphql file and graphql-style syntax.

In order to use the schemas, it's necessary to install and configure the @atlassian/clientside-extensions-schema webpack loader.

Follow the How to setup CSE schema-loader guide to do so.

Schema definition

At minimum, a schema definition needs to have the name of the extension point and a type named Schema:

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    # schema definition
}

Context schema

Schemas can also used to define the shape of a valid context object to be shared with extensions. They are useful in order to prevent breaking changes caused by unexpected changes in the context provided:

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    # schema definition
}

type ContextSchema {
    # schema definition
}

Available graphql syntax

The following parts of the graphql syntax are available to define schemas:

Provided scalars

The following scalars can be used in any schema and are provided by the schema package:

Provided types

The following predefined types are provided by the schema package:

Icon

An Icon object with a glyph that allows to customize its colors and CSS class.

1
2
type Icon {
    """
    Icon to render
    """
    glyph: IconGlyph!

    """
    Custom CSS class name passed to icon wrapper
    """
    className: String

    """
    String to use as the aria-label for the icon.
    Set to an empty string if you are rendering the icon with visible text to prevent accessibility label duplication.
    """
    label: String

    """
    Primary colour of the icons
    """
    primaryColor: String

    """
    Secondary colour of the two-color icons
    """
    secondaryColor: String
}

IconGlyph

The value must be either the name of the glyph or a functional React component returning an SVG glyph.

1
2
union IconGlyph = String | Function

Usage notes

1. Schema definition with an icon

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    type: ButtonExtension!

    """
    Text to render on the button
    """
    label: String

    """
    Callback will be run when user clicks the button
    """
    onAction: Function

    """
    An icon to show on the button if provided
    """
    icon: Icon
}

2. Schema definition that supports modal extensions

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    type: ModalExtension!

    """
    Text to render on the button
    """
    label: String

    """
    The value should be a callback function expecting to receive the modal extension API
    """
    onAction: ModalOnAction
}

3. Context schema definition with custom type

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    type: LinkExtension!

    label: String
}

"""
It's also possible to define custom types in graphql syntax
"""
type User {
    name: String

    age: Number

    lastLogin: Number

    isAdmin: Boolean
}

type ContextSchema {
    """
    Using custom type to define a property of context
    """
    user: User

    unreadMessages: Number
}