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:

Syntax	Description
`scalar`	Used for simple values or primitives.
`type`	Used to describe more complex key/value shapes, similar to an `Object` in javascript.
`enum`	Enumeration of predefined values.
`union`	Used as an `or` to allow e.g. a key within an input to have multiple possible correct values. A union can consist of `type`, `enum`, `scalars`, or another `union`.
`!`	A `!` behind a type makes it *required*.
`[]`	Surrounding a type with square brackets (`[]`) means an array of that type is expected.

Provided scalars

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

Name	Description	Example
`Boolean`	Represents `true` or `false`.	`false`
`Date`	A javascript Date object.	`new Date()`
`Function`	Represents any javascript function.	`function () { }`
`Number`	Represents a numeric value. Can be an integer or floating point.	`3.14`
`ModalOnAction`	The value should be a callback function expecting to receive the `Modal` extension API	`function () { }`
`PanelOnAction`	The value should be a callback function expecting to receive the `Panel` extension API	`function () { }`
`Promise`	A javascript Promise object.	`Promise.resolve()`
`RegExp`	A regexp pattern, that can be used for matching against text.	`/foo.+bar/`
`String`	The `String` type represents textual data.	`"foo"`
`AsyncPanelExtension`	The value must be the constant "async-panel".	`N/A`
`ButtonExtension`	The value must be the constant "button".	`N/A`
`LinkExtension`	The value must be the constant "link".	`N/A`
`ModalExtension`	The value must be the constant "modal".	`N/A`
`PanelExtension`	The value must be the constant "panel".	`N/A`
`SectionExtension`	The value must be the constant "section".	`N/A`

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
}

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
}