Open Design

Octopus Format

Open Design API returns a JSON-based representation of a design file. We call this output Octopus 🐙. To learn more about how to use the API to generate it, check out the quickstart.

Once you call the artboard content endpoint, you'll see a block of JSON output with layers, colors, styles, etc. You can use the schema below to learn more about the format.

If you have any questions or feedback, please don't hestiate to contact us and we'll be happy to help.

Type

Properties

OctopusDocument

Octopus Document

versionobject

Object describing current Octopus versions. Should contain octopus-common (required) and any other adapter. Versions should follow semver notation. Version series differ by each implementation.

timeStampinteger

Unix timestamp describing the time when Octopus has been generated.

boundsBounds

Document bounds. Top/Left values of document bounds are always 0, so, in fact, it describes only document width and height.

symbolIDstring

If current document (artboard) is a sketch symbol master, then it has this id.

Unique identifier (for the whole document) of an instance.

frameobject

Artboard offset (x/y) relative to the original document.

backgroundColorColor

Background color as RGBA (if exists) of current document.

hasBackgroundColorboolean

Boolean flag describing if current document has background color activated or not.

guidesobject

Object describing horizontal and vertical rulers guides for the current artboard.

includeBackgroundColorInInstancenumber
enums: 01

Property describes occurrence of background color for Symbol instances.

exportablesExportableItem[]

Array with export descriptors. Each entry is assigned to some slice or layer.

flowobject

Object describing interactions on the current artboard.

layersLayer[]

An array of current document layers.

Type

Properties

Bounds

Bounds object describes offset (top and left values) and size (width and height values) of the current instance. Furthermore, it contains right (width + left) and bottom (top + height) values.

topnumber

Instance top edge.

Number with only two digits after float point.

leftnumber

Instance left edge.

Number with only two digits after float point.

rightnumber

Instance right edge.

Number with only two digits after float point.

bottomnumber

Instance bottom edge.

Number with only two digits after float point.

widthnumber

Instance width.

Number with only two digits after float point.

heightnumber

Instance height.

Number with only two digits after float point.

Type

Properties

Offset

Horizontal and vertical offset for the given instance.

horizontalnumber
required

Horizontal offset for the given instance.

verticalnumber
required

Vertical offset for the given instance.

Type

Properties

EffectAbstractGradient

Gradient descriptor.

stopsobject

An array of the current gradient stops. Each element is an object containing color and location values.

invertboolean

Flag describing if gradient has been inverted.

typestring
enums: linearradial

Type of the current gradient.

offsetOffset

Gradient offset relative to relativeTo value.

scalenumber

Gradient scale.

Scale for the current instance.

anglenumber

Gradient angle in degrees.

relativeTostring
enums: layerdocument

An instance the current gradient has offset relative to.

The value of current property describes an instance (layer or document) another instnace is relative to.

fromnumber[]

Descriptor of the first gradient direction point.

tonumber[]

Descriptor of the second gradient direction point.

ellipseLengthnumber

If the current gradient is elliptic, then it has ellipseLength property describing the length of the given ellipse.

Type

Properties

EffectAbstractPattern

Pattern descriptor.

filenamestring

Absolute or relative path to the pattern file.

opacitynumber <float>

Opacity of the current pattern.

Float number from 0 (including) to 1 (including) describing alpha channel (opacity) value.

offsetOffset

An offset of the current pattern relative to relativeTo value.

relativeTostring
enums: layerdocument

Value describes an instance the current pattern is relative to.

The value of current property describes an instance (layer or document) another instnace is relative to.

scalenumber

Scale of the current pattern.

Scale for the current instance.

typestring
enums: fillfitstretchtile

Type of the current pattern.

Type

Properties

EffectFill

Fill effect descriptor.

colorColor

The color descriptor (for the color fill).

The gradient descriptor (for the gradient fill).

The pattern descriptor (for the pattern fill).

nocolorboolean

Boolean value describing the empty fill (for the shape layers).

defaultboolean

Boolean value describing if the current fill is the original effect or an additional effect (FX menu in PS).

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

The blending mode for the current fill.

Blending mode for the current instance.

Type

Properties

EffectBorder

Border effect descriptor.

widthnumber

The width of the current border.

colorColor

The color (RGBA) of the current border.

stylestring
enums: soliddotteddashedgradientpattern

The style of the current border.

lineAlignmentstring
enums: outsideinsidecenter

The alignment of the line of the current border.

lineJoinstring
enums: bevelroundmiter

The type of the line join of the current border.

lineCapstring
enums: roundbuttsquare

The type of the line cap of the current border.

miterLimitnumber
default: 20

The miter limit controls when the rendering switches from a mitered (pointed) join to a beveled (squared-off) join.

dashOffsetnumber

The offset of the current border dash.

dashSetnumber[]

The set of current border dashes/gaps.

overprintboolean

Boolean value describing if inside/centered border with transparency still makes visible the underlying instance (true) or the instance is being cut by the current border (false).

defaultboolean

Boolean value describing if the current border is the original effect or an additional effect (FX menu in PS).

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

The blending mode of the current border.

Blending mode for the current instance.

The pattern descriptor for the current border.

The gradient descriptor for the current border.

Type

Properties

EffectBlur

Blur effect descriptor.

radiusnumber

The radius of the current blur.

anglenumber

The angle of the current blur.

typestring
enums: GAUSSIANMOTIONZOOMBACKGROUND

The type of the current blur.

centerobject

The center point of the current blur.

brightnessnumber

The brightness of the current blur.

opacitynumber <float>

The opacity of the current blur.

Float number from 0 (including) to 1 (including) describing alpha channel (opacity) value.

Type

Properties

EffectShadow

Shadow effect descriptor.

xnumber

Horizontal offset of the current shadow.

ynumber

Vertical offset of the current shadow.

blurnumber

The width of the blur of the current shadow.

chokenumber

The width of the shadow line (choke) of the current shadow.

insetboolean

Boolean flag describing if the current shadow is inset.

glowboolean

Boolean flag describing if the current effect is glow instead of shadow.

An array describing the map of the countour points. WIP.

colorColor

The color descriptor of the current shadow.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

The blending mode of the current shadow.

Blending mode for the current instance.

Type

Properties

ContourItem

floornumber
required
ceilnumber
required
pointsobject[]
required

Type

Properties

ExportableLocation

Location of given export descriptor. Consists of id, parent and index. In case of slices you should use parent's id and index to localize slice, otherwise layer id is enough.

idstring

Id of layer export is assigned to.

Unique identifier (for the whole document) of an instance.

parentstring

Id of layer's parent.

Unique identifier (for the whole document) of an instance.

indexnumber

Index of given layer in parent's layers array.

Type

Properties

ExportableFormatItem

Export format descriptor.

namingobject

Object describing prefix/suffix when naming export.

formatstring
enums: PNGJPGTIFFWEBPPDFEPSSVG

Format of export.

sizeobject

Resizing constraint.

Type

Properties

ExportableItem

Export descriptor (slice or layer) with assigned export formats.

typestring
enums: LAYERSLICE

Export descriptor type.

In case of SLICE there is just area (specified by bounds) and location of given slice (specifed by location.parent and location.index).

In case of LAYER there is location.id for assigned layer to export.

trimTransparentPixelsboolean

Boolean describing if transparent pixels should be trimmed when exporting.

backgroundobject

Background of an export.

boundsBounds

Export descriptor's bounds (mainly useful for slices).

limitTostring
enums: ARTBOARDSELF

Property describes what should be included in export.

Array describing export formats (its type, size and naming).

Type

Properties

FlowInteractionItem

An interaction descriptor.

destinationobject
required

An object describing the target of the current interaction.

animationobject
required

Descriptor of the current interaction animation properties.

boundsBounds
required

Bounds of the current interaction area.

preserveScrollboolean

If true, then artboard should preserve the current scroll position.

triggerstring

WIP. Trigger (gesture or smth) that triggers current interaction.

ownerIdstring

Id of the layer current interaction origins from.

Unique identifier (for the whole document) of an instance.

Type

Properties

Color

Color descriptor (RGBA).

rinteger
required

Color channel for RED color.

The number describing color channel (ranged 0-255).

ginteger
required

Color channel for GREEN color.

The number describing color channel (ranged 0-255).

binteger
required

Color channel for BLUE color.

The number describing color channel (ranged 0-255).

anumber <float>
required

Alpha channel.

Float number from 0 (including) to 1 (including) describing alpha channel (opacity) value.

Type

Properties

Font

Text style descriptor.

alignstring
enums: leftcenterrightjustify

Align of the text.

namestring

Name of the used font.

typestring

Type of the used font.

sizenumber

Size of the used font.

kerningboolean

Boolean value describing if the font kerning has been applied.

letterSpacingnumber

Letter spacing for the given text range.

underlineboolean

Boolean value describing if the current text has been underlined.

linethroughboolean

Boolean value describing if the current text has line through.

boldboolean

Boolean value describing if the current text is bold.

italicboolean

Boolean value describing if the current text is italic.

ligaturesnumber
enums: 0123

Boolean value describing the way ligatures has been applied.

uppercaseboolean

Boolean value describing if the current text is transformed to upper case.

smallcapsboolean

Boolean value describing if the current text is transformed to lower case.

baselinestring
enums: subScriptsuperScriptnormal

Boolean value describing if the current text is transformed to upper case.

postScriptNamestring

The full name of the used font.

syntheticPostScriptNameboolean

Whether the postScriptName was generated (+) due to absence of an actual one.

lineHeightnumber

The line height for the current text range.

Type

Properties

ShapePoint

A single subpath point descriptor.

typestring
enums: bezierpoint

The value describes type of the current subpath point descriptor.

coordinatesnumber[]
required

An array of coordinates for the current subpath point descriptor. Two-numbers array is used for point type of the point descriptor and six-numbers array is used for bezier type of the point descriptor. If a point is of type bezier, the items are stored as [c1.x c1.y c2.x c2.y p.x p.y], where p is the point on the curve and c1 and c2 are its neighbouring control points.

Type

Properties

ShapeRectCornerRadius

The object describing corner radiuses. WIP, probably deprecated.

topLeftnumber

The radius of the top left corner.

topRightnumber

The radius of the top right corner.

bottomRightnumber

The radius of the bottom right corner.

bottomLeftnumber

The radius of the bottom left corner.

Type

Properties

ShapeSubpath

A single subpath descriptor.

closedboolean

Boolean value describing if the current subpath is closed.

An array of point descriptors for the current subpath descriptor.

Type

Properties

ShapePath

A single vector path descriptor.

typestring
enums: rectellipsepath

Type of vector path.

An array of the subpaths for the current path descriptor.

boundsBounds

The bounds of the current path. The path bounds differs from layer bounds the way shape bounds are calculated before application of transformations. Layer bounds include transformations application.

booleanOperationstring
enums: unionsubtractionintersectionexclusion

The boolean operation type of the current path descriptor.

rotationnumber

The rotation of the current path descriptor.

Rotation transformation in degrees.

isFlippedVerticalboolean

The vertical flip transformation flag of the current path descriptor.

Boolean value describing if vertical flip transformation has been applied.

isFlippedHorizontalboolean

The horizontal flip transformation flag of the current path descriptor.

Boolean value describing if horizontal flip transformation has been applied.

Type

Properties

Shape

Shape descriptor.

An array of the vector paths used for the current shape.

enabledboolean
default: true

If the current shape is vector mask, this value describes if it is enabled or not.

windingRulestring
enums: non-zeroeven-odd

The value describes how to fill shape with overlapping paths.

Type

Properties

BitmapMask

Bitmap mask descriptor. Bitmap mask is PS-only feature that masks the layer with another bitmap. The bitmap has just single black and white channel, so each pixel has a single value of 0-255. Zero value removes the pixel completely, 255 does not affect the pixel.

boundsBounds

Bounds of the current bitmap mask descriptor.

filenamestring

An absolute or relative path to the bitmap file.

enabledboolean

Boolean value that describes if the current bitmap mask descriptor is enabled.

extendWithWhiteboolean

If the following value is true, you should extend the mask image with white color before masking (if not present, defaults to false).

Type

Properties

Bitmap

Bitmap descriptor.

duplicateOfstring

Reference to the layer ID the current bitmap descriptor should be copied from.

Unique identifier (for the whole document) of an instance.

boundsBounds

Bitmap bounds includes effects, such as shadows, blurs, outside borders etc.

blankboolean

True if the current layer is completely blank. Such layers do not have any pixels.

simpleFillColor

Value describes bitmap descriptor that is just a rectangle (specified by bitmap.bounds) filled by the specified color. Such layers do not have any bitmap.filename.

filenamestring

An absolute or relative path to the bitmap file.

premultipliedboolean

Injected by rendering, describes if the bitmap channels has been premultiplied by alpha.

metadataobject

Injected by rendering, this object can contain various data, described in separate schema (wip).

spriteCoordsobject

If the bitmap.filename is a sprite, these are coordinates of the this layer in the sprite.

effectsAppliedboolean

Boolean value that describes if the current bitmap descriptor already contains all the effects.

Type

Properties

Adjustment

WIP.

typestring
enums: hueSaturationbrightnessEventblackAndWhite
descriptorobject

Type

Properties

TransformMatrix

The transformation matrix applied on the current text layer.

anumber
required
bnumber
required
cnumber
required
dnumber
required
txnumber
required
tynumber
required

Type

Properties

TextStyleItem

Style range object defined by ranges (an array of objects with from & to values), font style descriptor and color descriptor.

fontFont

Font style descriptor for the current style range.

colorColor

Color descriptor for the current style range.

rangesobject[]

An array with objects describing from and to values for the current style range.

Type

Properties

Text

Text ranges descriptor.

An array containing font style ranges.

ignoreFirstLineHeightboolean

The boolean flag that describes PS only way of the bounds calculation for the text layers (ignores height of the first text line).

defaultStyleobject

An abstract style range without from-to ranges that is used for the whole text as default value. Every single font style range from text.styles array overrides the given defaultStyle value.

transformobject

Photoshop only value describing text scaling by X and Y axes.

transformMatrixTransformMatrix
valuestring

The text value of the current text layer.

boundsBounds

The bounds for the current text. Text bounds are not always same as layer bounds.

frameBounds

In case of fixed text area, these are the text bounds representing an area the current text should be typeset into.

boundsModestring
enums: autofixed

Specifies the text bounds semantics. 'fixed' mode sets the typeset area acording to the text bounds, 'auto' mode expands bounds as needed.

verticalAlignmentstring
enums: topcenterbottom

Vertical alignment of the text regarding the whole layer.

baselinePolicystring
enums: fixedcenter

Defines the way baseline should be rendered.

fixed - old way of figma's text rendering

center - new way of figma's text rendering

Type

Properties

LayerBase

Layer descriptor.

idstring
required

The unique layer ID.

  • In Photoshop: numeric
  • In Sketch: UUID string
  • In Adobe XD: UUID string
  • In Figma: string like 3:5:3, represention of hirerachy of layers
  • In Illustrator: similar to Figma - hierarchy of layers.

Unique identifier (for the whole document) of an instance.

namestring

The name of the current layer.

originstring
enums: sketchxdphotoshopfigmaillustrator

The value describes the software the current layer has been parsed from.

visibleboolean

Boolean values describes the layer visibility.

boundsBounds

The bounds of the current layer (without effects).

clippedboolean

Value is true for PSD layers that are clipped to a mask. Such layers should have maskedBy property as well.

maskedBystring

The value is an ID of the layer that is a clipping mask of the current layer. Multiple layers can have the same maskedBy value.

Unique identifier (for the whole document) of an instance.

maskTypestring
enums: alphainverse-luminosityluminosityoutlinepsdsvgfigmaOutline

The type of the mask.

  • alpha - ...
  • inverse-luminosity - The result alpha of masked layer is derived from mask grayscale values where black is alpha = 1 and white is alpha = 0.
  • luminosity - The result alpha of masked layer is derived from mask grayscale values where black is alpha = 0 and white is alpha = 1.
  • outline - ...
  • psd - ...
  • svg - ...
  • figmaOutline - type of the mask for figma's outlines
bitmapMaskBitmapMask
clipBoundsBounds

Clip bounds should be used instead of rectangular clipping mask.

opacitynumber <float>

The opacity of the current layer.

Float number from 0 (including) to 1 (including) describing alpha channel (opacity) value.

fillOpacitynumber <float>

The fill opacity of the current layer.

Float number from 0 (including) to 1 (including) describing alpha channel (opacity) value.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

The blending mode of the current layer.

Blending mode for the current instance.

effectsobject

Current layer effects descriptor.

bitmapBitmap
blankboolean

Contains the same value as bitmap.blank. Value is true if the layer is completely blank. Such layers do not have any pixels.

rotatedBoundsBounds

Layer bounds with applied transformations (such as rotation and flips). WIP.

symbolIDstring

The ID of the symbol master this layer refers to.

Unique identifier (for the whole document) of an instance.

useLayerBlendModeOnlyboolean

If the value is true, then the only blending mode that should be used is layer blend mode.

overridesobject[]

Values that should be overriden on the symbol master.

Sketch only property.

If the current layer is symbol instance, then this object describes the values that are overriden on used symbol master. There are different types of overrides:

  • bitmap
  • text
  • symbol instance id
  • flow destination
  • shared styles (layer & text)
  • tints

Older Sketch versions used object to represent overrides, but since Sketch started to support text shared styles array is used instead.

Type

Properties

ShapeLayer

typestring
enums: shapeLayer

Defines what type of layer this is. You can use this to distinguish between different layer types.

shapeShape

Shape descriptor.

borderShapeShape

Figma describes borders of shapes as separate shape instances, borderShape is used to represent it for rendering separately from shape descriptor.

inherits from LayerBase

Type

Properties

TextLayer

typestring
enums: textLayer

Defines what type of layer this is. You can use this to distinguish between different layer types.

textText
inherits from LayerBase

Type

Properties

DocumentLayer

typestring
enums: document

Defines what type of layer this is. You can use this to distinguish between different layer types.

documentIdstring

An ID of the Smart-object (Photoshop) or Artboard (Sketch).

Unique identifier (for the whole document) of an instance.

inherits from LayerBase

Type

Properties

AdjustmentLayer

typestring
enums: adjustmentLayer

Defines what type of layer this is. You can use this to distinguish between different layer types.

adjustmentAdjustment
inherits from LayerBase

Type

Properties

LayerLayer

typestring
enums: layer

Defines what type of layer this is. You can use this to distinguish between different layer types.

inherits from LayerBase

Type

Properties

BackgroundLayer

typestring
enums: backgroundLayer

Defines what type of layer this is. You can use this to distinguish between different layer types.

inherits from LayerBase

Type

Properties

GroupLayer

typestring
enums: groupLayer

Defines what type of layer this is. You can use this to distinguish between different layer types.

layersLayer[]

An array with sublayers of the current layer.

artboardobject

Photoshop groupLayer can be an artboard, in such case there will be a artboard object with its bounds.

inherits from LayerBase