Open Design

Octopus documentation

Octopus is a JSON-based universal design format that can represent any design element in any of its supported formats. You will work with the Octopus file format when you need to read design data or individual layers. This page describes types and properties that are available in the Octopus.

Type

Properties

OctopusDocument

Octopus Document

versionobject

Object describing versions of tools participating in creation of the Octopus document. Should contain octopus-common (required) and at least one additional adapter. Version strings follow SemVer notation.

timeStampinteger

Octopus document creation time as Unix timestamp.

boundsBounds

Document bounds. Top/Left values of document bounds are always 0, only document width and height is stored in the object.

symbolIDstring

If the document (artboard) is a Sketch symbol master, then this field contains its ID.

Identifier unique within the whole document.

frameobject

Artboard position

backgroundColorColor
default: { "r": 0, "g": 0, "b": 0, "a": 0 }

Artboard background color as RGBA.

hasBackgroundColorboolean

A flag indicating whether backgroundColor should be applied as a background color of the artboard.

guidesobject

Horizontal and vertical ruler guides for the artboard.

includeBackgroundColorInInstancenumber
enums: 01

Describes whether the background color is to be used in the symbol instances.

exportablesExportableItem[]

Array of export descriptors. Each entry is assigned to a slice or layer.

flowobject

Describes interactions on the artboard.

smartLayoutstring
enums: RIGHT_TO_LEFTHORIZONTAL_CENTERTOP_TO_BOTTOMBOTTOM_TO_TOPHORIZONTAL_CENTERLEFT_TO_RIGHT

[Sketch only] Smart layout applied to a symbol

[Sketch only] Describes a smart layout configuration.

layersLayer[]
required

Array of the document's layers.

Type

Properties

Bounds

Bounds object describes position (top and left) and size (width and height) of a rectangular area in a document. In addition, it contains right (width + left) and bottom (top + height) values.

topnumber <float>
required

Instance top edge.

Number with precision of two decimal places.

leftnumber <float>
required

Instance left edge.

Number with precision of two decimal places.

rightnumber <float>
required

Instance right edge.

Number with precision of two decimal places.

bottomnumber <float>
required

Instance bottom edge.

Number with precision of two decimal places.

widthnumber <float>
required

Instance width.

Non-negative number with precision of two decimal places.

heightnumber <float>
required

Instance height.

Non-negative number with precision of two decimal places.

Type

Properties

Offset

Horizontal and vertical offset of a given entity.

horizontalnumber <float>
required

X-axis offset.

verticalnumber <float>
required

Y-axis offset.

Type

Properties

EffectAbstractGradient

Gradient effect descriptor.

stopsobject

An array of the gradient's stop points. Each element is an object containing color and location values.

invertboolean

Flag describing if gradient has been inverted.

typestring
required
enums: linearradial

Gradient type.

offsetOffset
required

Gradient offset relative to relativeTo value.

scalenumber <float>
default: 1

Gradient scale.

Uniform (down)scale factor.

anglenumber <float>

Gradient angle in degrees.

relativeTostring
required
enums: layerdocument

Determines what is the gradient's configuration relative to (layer or document).

Describes en effect configuration origin.

fromnumber[]

Descriptor of the first gradient direction point.

tonumber[]

Descriptor of the second gradient direction point.

ellipseLengthnumber <float>
default: 1

For elliptic gradients describes ratio of major to minor semi-axis of the ellipse

Type

Properties

EffectAbstractPattern

Pattern descriptor.

filenamestring
required

URI reference of the pattern file (URL or relative filename)

opacitynumber <float>
default: 1

Pattern opacity.

Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.

offsetOffset
required

Pattern offset relative to relativeTo value.

relativeTostring
required
enums: layerdocument

Determines what is the gradient's configuration relative to (layer or document).

Describes en effect configuration origin.

scalenumber <float>
default: 1

Pattern scale.

Uniform (down)scale factor.

typestring
required
enums: fillfitstretchtile

Pattern type.

Type

Properties

EffectFill

Fill effect descriptor.

idstring

undefined

Effect's unique identifier

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

If true, the effect is applied to the layer geometry (shape layers), otherwise it's applied to the rasterized content.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

Blend mode of the effect.

Blend mode.

Type

Properties

EffectBorder

Border effect descriptor.

idstring

undefined

Effect's unique identifier

widthnumber <float>
required

Width of the border.

colorColor

Color (RGBA) of the border.

stylestring
default: "solid"
enums: soliddotteddashed

Type of the border style, the dashed style is further specified in dashedOffset and dashedSet

lineAlignmentstring
enums: outsideinsidecenter

Border alignment relative to the shape outline.

lineJoinstring
default: "miter"
enums: bevelroundmiter

A style of a connection between adjacent border segments.

lineCapstring
default: "butt"
enums: roundbuttsquare

A style of the endings of border segments.

miterLimitnumber <float>
default: 20

A value limiting the extension of a sharp tip created by adjacent border segments using 'miter' join.

dashOffsetnumber <float>

Border dash initial offset. (applies to 'dashed' borders)

dashSetnumber[]

A set of alternating dashes (filled regions) and gaps (empty regions). (applies to 'dashed' borders)

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 border (false).

defaultboolean

If true, the effect is applied to the layer geometry (shape layers), otherwise it's applied to the rasterized content.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

Blend mode mode of the effect.

Blend mode.

A pattern descriptor for the border.

A gradient descriptor for the border.

Type

Properties

EffectBlur

Blur effect descriptor.

idstring

undefined

Effect's unique identifier

typestring
required
enums: GAUSSIANMOTIONZOOMBACKGROUND

Blur type.

radiusnumber <float>

Blur radius.

anglenumber <float>

Motion blur angle (in degrees).

centerobject

The center of the zoom blur.

brightnessnumber <float>
default: 100

Brightness level of the blur (in [%]).

opacitynumber <float>
default: 1

Opacity of the blur.

Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.

Type

Properties

EffectShadow

Shadow effect descriptor.

idstring

undefined

Effect's unique identifier

xnumber

Horizontal offset of the shadow.

ynumber

Vertical offset of the shadow.

blurnumber

Blur value of the shadow.

chokenumber

Spread amount of the shadow contour.

insetboolean

Flag specifying if the shadow is cast onto the inner portion of the object.

glowboolean

Flag specifying the effect being 'glow' instead of a shadow.

An array describing the shadow contour function.

colorColor

The color of the shadow.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

Blend mode of the shadow.

Blend mode.

Type

Properties

ContourItem

A segment in a shadow contour function.

floornumber <float>
required

The contour function segment bottom limit.

ceilnumber <float>
required

The contour function segment top limit.

pointsobject[]
required

An array of contour function segment points

Type

Properties

ExportableLocation

Location of an export descriptor. Consists of id, parent and index. In case of slices, parent's ID and index should be used to localize the slice, otherwise, layer ID is sufficient.

idstring

ID of a layer the export is assigned to.

Identifier unique within the whole document.

parentstring

ID of layer's parent.

Identifier unique within the whole document.

indexnumber

Index of the layer in parent's layers array.

Type

Properties

ExportableFormatItem

Export format descriptor.

namingobject

Describes value of the export's name prefix/suffix.

formatstring
required
enums: PNGJPGTIFFWEBPPDFEPSSVG

Format of the export.

sizeobject

Resizing constraint.

Type

Properties

ExportableItem

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

typestring
required
enums: LAYERSLICE

Export descriptor type.

In case of SLICE there is just area (specified by bounds) and location of given slice (specified 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 the 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 interaction.

animationobject
required

Descriptor of the interaction animation properties.

boundsBounds
required

Bounds of the interaction area.

preserveScrollboolean

If true, then artboard should preserve current scroll position.

triggerstring

Trigger (e.g. gesture) that initiates the interaction.

ownerIdstring

Id of a layer the interaction origins from.

Identifier unique within the whole document.

Type

Properties

Color

Color descriptor (RGBA).

rinteger
required

Color channel for RED color.

Color channel value (ranged 0-255).

ginteger
required

Color channel for GREEN color.

Color channel value (ranged 0-255).

binteger
required

Color channel for BLUE color.

Color channel value (ranged 0-255).

anumber <float>
requireddefault: 1

Alpha channel.

Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.

Type

Properties

Font

Text style descriptor.

alignstring
enums: leftcenterrightjustify

Horizontal alignment of the text.

namestring

Common name of font.

typestring

Font type (called 'subfamily' in OpenType specification).

sizenumber <float>
required

Font's size.

kerningboolean

Describes if kerning feature is enabled in the text.

letterSpacingnumber <float>

Text letter spacing (can be negative).

underlinenumber
0
enums: 012

Text underline type.

  • 0 none
  • 1 single line
  • 2 double lines
linethroughboolean

Describes if the text has line through.

boldboolean

Describes if the text is bold. If missing the information is not known.

italicboolean

Describes if the text is italic. If missing the information is not known.

ligaturesnumber
default: 1
enums: 0123

Describes a ligature category.

  • 0 none
  • 1 standard
  • 2 discretionary and historical
  • 3 all
uppercaseboolean

Describes if the text is transformed to upper case.

lowercaseboolean

Describes if the text is transformed to lower case.

smallcapsboolean

Describes if the text is written in small capitals.

baselinestring
default: "normal"
enums: subScriptsuperScriptnormal

Describes baseline's position type.

postScriptNamestring
required

PostScript name of the used font.

syntheticPostScriptNameboolean

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

lineHeightnumber

Line height of the text. If 0 a default line height (for a given font size) is taken directly from the font file.

An array of OpenType features configuration.

Type

Properties

OpenTypeFeature

Representation of a typographic feature as described in OpenType specification.

tagstring
required

Feature tag, typically a 4 letter abbreviation of the feature's name.

valueinteger <int32>
required

For most features, the value is either 1 or 0 standing for the feature to be enabled or disabled respectively. Specific OpenType features might be assigned an arbitrary value.

Type

Properties

ShapePoint

A single point descriptor.

typestring
required
enums: pointquadcubicbezier

Describes a type of the point.

  • point simple point
  • quad point has a single control point, adjacent segment represents quadratic Bézier curve
  • cubic point has two control points, adjacent segment represent cubic Bézier curve
  • bezier alias for cubic
coordinatesnumber[]
required

An array of point's data, x and y coords alternate in the array.

If the point is of type cubic (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. For type quad the format is [c.x c.y p.x p.y], for type point it is [p.x p.y].

radiusnumber <float>

Corner radius at the point.

Type

Properties

ShapeRectCornerRadius

Corner radius description (legacy, for rectangles only).

topLeftnumber <float>

Radius of the top left corner.

topRightnumber <float>

Radius of the top right corner.

bottomRightnumber <float>

Radius of the bottom right corner.

bottomLeftnumber <float>

Radius of the bottom left corner.

Type

Properties

ShapeSubpath

A single subpath (contour) descriptor.

closedboolean

Describes if the path is opened or closed

required

An array of points in the path.

Type

Properties

ShapePath

A single vector path descriptor.

typestring
enums: rectellipsepath

Type of a shape the vector path represents. If missing, the represented shape is not known.

required

An array of subpaths (contours) the path consists of.

boundsBounds

Bounds of the path. If missing, bounds are not known.

booleanOperationstring
default: "none"
enums: unionsubtractionintersectionexclusionnone

Boolean operation combining this and next-in-the-array path.

rotationnumber <float>

Path rotation (in degrees).

Value of rotation in degrees.

isFlippedVerticalboolean

Vertical flip transformation flag. If true, path should be reversed across y-axis.

isFlippedHorizontalboolean

Horizontal flip transformation flag. If true, path should be reversed across x-axis.

resizingContraintsstring[]

[Sketch only] Layer resizing constraints applied when the path takes part in symbol instantiation process.

[Sketch only] List of constraints specifying object behaviour when resized.

Type

Properties

Shape

Shape descriptor.

required

An array of vector paths in the shape.

enabledboolean
default: true

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

windingRulestring
default: "even-odd"
enums: non-zeroeven-odd

The value describes the shape's 'winding rule' (policy determining how overlapping contours fill an area).

Type

Properties

BitmapMask

[Photoshop only] Bitmap mask is a grayscale bitmap attached to the layer that masks layer's content based on the its pixel values, 0 removes the layer pixel completely, 255 does not affect the pixel.

boundsBounds

Bitmap mask bounds. If missing, the value of layer.bitmap is used instead.

filenamestring
required

URI reference of the bitmap mask file (URL or relative filename)

enabledboolean

Determines whether the mask is applied.

extendWithWhiteboolean

If the value is true, the mask bitmap needs be resized to match the size of a layer it masks, the extended area is to be filled with solid white color.

Type

Properties

Bitmap

Bitmap descriptor.

duplicateOfstring

A reference to the layer ID the bitmap descriptor should be copied from.

Identifier unique within the whole document.

boundsBounds

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

blankboolean

True if the layer is completely blank. Such layer does not have any non-transparent pixels.

simpleFillColor

If set, the bitmap is just a rectangle (specified by bitmap.bounds) filled by a given color. Such layers do not have any bitmap.filename.

filenamestring

URI reference of the bitmap mask file (URL or relative filename)

premultipliedboolean

[internal] Describes if the bitmap channels has been alpha pre-multiplied.

metadataobject

[internal] Mostly used for layer 'pre-rendering', contains various information of the render configuration.

spriteCoordsobject

[deprecated] If the bitmap.filename is a sprite atlas, these are coordinates of the this layer's sprite in the atlas.

effectsAppliedboolean

Describes if the bitmap already contains all the effects.

Type

Properties

TransformMatrix

A text transformation matrix (relative to the document).

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

Type

Properties

TextStyleItem

Text style defined for particular fragments of the text (text ranges).

fontFont

Font style descriptor for the style range.

colorColor

Color descriptor for the style range.

rangesobject[]

An array of objects describing the text ranges. A single range is pair of from and to indices into the text.value string, the range is semi-open interval, value at index to is not part of the range.

Type

Properties

Text

Text descriptor.

An array containing font style ranges.

ignoreFirstLineHeightboolean

[Photoshop only, deprecated] Describes whether the first line's height is considered in the layer bounds calculation.

defaultStyleobject

Text style that is used as a default when no explicit style range covers a particular fragment of a text. Every font style range in text.styles array overrides the defaultStyle value.

transformobject

[Photoshop only] Text transform scale factors.

transformMatrixTransformMatrix
valuestring
required

Text content of the text layer.

boundsBounds

[deprecated, use frame instead] Bounds of the text. Text bounds are not always same as layer bounds.

frameBounds

Describes an area the text layer should be typeset into. In case of auto bounds mode, width and height might be 0 as the dimension might not be specified.

boundsModestring
default: "auto"
enums: autofixed

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

verticalAlignmentstring
default: "top"
enums: topcenterbottom

Text vertical alignment relative to the whole layer.

baselinePolicystring
default: "center"
enums: fixedcenter

Defines a way the baseline position is determined.

  • fixed - baseline distance from a layer top is given only by font properties
  • center - baseline is centered within the line (i.e. depends on lineHeight)

Type

Properties

LayerBase

Common layer description.

idstring
required

Unique layer identifier.

ID format:

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

Identifier unique within the whole document.

namestring

Name of the layer.

originstring
enums: sketchxdphotoshopfigmaillustrator

Describes a software the layer originally cames from.

visibleboolean
default: true

Describes the layer visibility.

boundsBounds

Bounds of the layer (without effects).

shapeShape

Specifies vector geometry of the layer. For non-shape layers acts like a vector mask.

clippedboolean

The value is true for layers that are being masked by another layer, such layers should have maskedBy property as well.

maskedBystring

The value is ID of a layer that is a clipping mask of this layer. Different layers might be masked by the same clipping mask.

Identifier unique within the whole document.

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 could be used instead of a rectangular clipping mask of the same position and size.

opacitynumber <float>
default: 1

Opacity level of the layer, 1.0 - fully opaque, 0.0 - fully transparent.

Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.

fillOpacitynumber <float>
default: 1

Fill opacity level of the layer.

Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.

blendModestring
enums: BLEND_DIVIDEBLEND_SUBTRACTIONCOLORCOLOR_BURNCOLOR_DODGEDARKENDARKER_COLORDIFFERENCEDISSOLVEEXCLUSIONHARD_LIGHTHARD_MIXHUELIGHTENLIGHTER_COLORLIGHTEN_BURNLIGHTEN_DODGELIGHTEN_LIGHTLUMINOSITYMULTIPLYOVERLAYPASS_THROUGHPIN_LIGHTSATURATIONSCREENSOFT_LIGHTVIVID_LIGHTNORMAL

Blend mode of the layer.

Blend mode.

effectsobject

Layer effects descriptor.

bitmapBitmap

Layer content rasterized as a bitmap image.

rotationnumber <float>

Rotation of the layer in degrees.

Value of rotation in degrees.

isFlippedVerticalboolean

Vertical flip transformation flag. If true, the layer should be reversed across y-axis (flopped).

isFlippedHorizontalboolean

Horizontal flip transformation flag. If true, the layer should be reversed across x-axis.

blankboolean

True if the layer is completely blank. Such layer does not have any non-transparent pixels.

rotatedBoundsBounds

[deprecated] Layer bounds with applied transformations (such as rotation and flips).

useLayerBlendModeOnlyboolean

[deprecated]

symbolIDstring

ID of the symbol master this layer refers to.

Identifier unique within the whole document.

overridesobject[]

Values in symbol master that are overridden in the instance.

[Sketch only] If a layer is a symbol instance, then this object describes the values that are overridden on used symbol master. There are different types of overrides:

  • bitmap
  • text
  • symbol instance id
  • flow destination
  • shared style (layer & text)
  • tint (fillColor)
resizingContraintsstring[]

[Sketch only] Layer resizing constraints applied when the layer takes part in symbol instantiation process.

[Sketch only] List of constraints specifying object behaviour when resized.

isVirtualboolean

Flag denoting a layer that has been artifitially added to the document and which doesn't exist in the original source (e.g. a background layers in Figma).

Type

Properties

ShapeLayer

Shape layer represents a vector geometry which is formed by individual paths combined together via boolean operations. At least on of shape or borderShape fields is required to be present.

typestring
required
enums: shapeLayer

Specifies the layer to be a shape layer.

borderShapeShape

Layer border represented as a custom geometry.

shapeRadiusnumber[]

An array of corner radii assigned to the vertices in (the only) shape path. This is just a meta-information as the shape's geometry already takes radii into account.

inherits from LayerBase

Type

Properties

TextLayer

Text layer represents a piece of text with its formatting and positioning.

typestring
required
enums: textLayer

Specifies the layer to be a text layer.

textText
required
inherits from LayerBase

Type

Properties

DocumentLayer

Document layer represents a content of a foreign document as a local layer.

typestring
required
enums: document

Specifies the layer to be a document layer.

documentIdstring

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

Identifier unique within the whole document.

inherits from LayerBase

Type

Properties

AdjustmentLayer

[Photoshop only] Adjustment layer represents a color and tonal adjustment configuration.

typestring
required
enums: adjustmentLayer

[Photoshop only] Specifies the layer to be an adjustment layer.

adjustmentobject

[incomplete] Adjustment configuration

inherits from LayerBase

Type

Properties

LayerLayer

Layer of this type represents a bitmap layer or a symbol instance layer.

typestring
required
enums: layer

Specifies the layer to be of type 'layer'.

inherits from LayerBase

Type

Properties

BackgroundLayer

Background layer is an artificial layer representing background configuration of a document.

typestring
required
enums: backgroundLayer

Specifies the layer to be a background layer.

inherits from LayerBase

Type

Properties

GroupLayer

Group layer is a composite layer containing other layers as components.

typestring
required
enums: groupLayer

Specifies the layer to be a group layer.

layersLayer[]
required

An array containing sub-layers of the group layer.

artboardobject

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

smartLayoutstring
enums: RIGHT_TO_LEFTHORIZONTAL_CENTERTOP_TO_BOTTOMBOTTOM_TO_TOPHORIZONTAL_CENTERLEFT_TO_RIGHT

[Sketch only] Smart layout applied to group layer

[Sketch only] Describes a smart layout configuration.

inherits from LayerBase

Type

Properties

Layer

A layer is a building block of a document. Can be of various types and can form hierarchies.