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
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.
Octopus document creation time as Unix timestamp.
Document bounds. Top/Left values of document bounds are always 0, only document width and height is stored in the object.
If the document (artboard) is a Sketch symbol master, then this field contains its ID.
Identifier unique within the whole document.
Artboard position
A flag indicating whether backgroundColor
should be applied as a background color of the artboard.
Horizontal and vertical ruler guides for the artboard.
Describes whether the background color is to be used in the symbol instances.
Array of export descriptors. Each entry is assigned to a slice or layer.
Describes interactions on the artboard.
[Sketch only] Smart layout applied to a symbol
[Sketch only] Describes a smart layout configuration.
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.
Instance top edge.
Number with precision of two decimal places.
Instance left edge.
Number with precision of two decimal places.
Instance right edge.
Number with precision of two decimal places.
Instance bottom edge.
Number with precision of two decimal places.
Instance width.
Non-negative number with precision of two decimal places.
Instance height.
Non-negative number with precision of two decimal places.
Type
Properties
Offset
Horizontal and vertical offset of a given entity.
X-axis offset.
Y-axis offset.
Type
Properties
EffectAbstractGradient
Gradient effect descriptor.
An array of the gradient's stop points. Each element is an object containing color
and location
values.
Flag describing if gradient has been inverted.
Gradient type.
Gradient scale.
Uniform (down)scale factor.
Gradient angle in degrees.
Determines what is the gradient's configuration relative to (layer or document).
Describes en effect configuration origin.
Descriptor of the first gradient direction point.
Descriptor of the second gradient direction point.
For elliptic gradients describes ratio of major to minor semi-axis of the ellipse
Type
Properties
EffectAbstractPattern
Pattern descriptor.
URI reference of the pattern file (URL or relative filename)
Pattern opacity.
Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.
Determines what is the gradient's configuration relative to (layer or document).
Describes en effect configuration origin.
Pattern scale.
Uniform (down)scale factor.
Pattern type.
Type
Properties
EffectFill
Fill effect descriptor.
undefined
Effect's unique identifier
The color descriptor (for the color fill).
The gradient descriptor (for the gradient fill).
The pattern descriptor (for the pattern fill).
Boolean value describing the empty fill (for the shape layers).
If true, the effect is applied to the layer geometry (shape layers), otherwise it's applied to the rasterized content.
Blend mode of the effect.
Blend mode.
Type
Properties
EffectBorder
Border effect descriptor.
undefined
Effect's unique identifier
Width of the border.
Color (RGBA) of the border.
Type of the border style, the dashed
style is further specified in dashedOffset
and dashedSet
Border alignment relative to the shape outline.
A style of a connection between adjacent border segments.
A style of the endings of border segments.
A value limiting the extension of a sharp tip created by adjacent border segments using 'miter' join.
Border dash initial offset. (applies to 'dashed' borders)
A set of alternating dashes (filled regions) and gaps (empty regions). (applies to 'dashed' borders)
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).
If true, the effect is applied to the layer geometry (shape layers), otherwise it's applied to the rasterized content.
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.
undefined
Effect's unique identifier
Blur type.
Blur radius.
Motion blur angle (in degrees).
The center of the zoom blur.
Brightness level of the blur (in [%]).
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.
undefined
Effect's unique identifier
Horizontal offset of the shadow.
Vertical offset of the shadow.
Blur value of the shadow.
Spread amount of the shadow contour.
Flag specifying if the shadow is cast onto the inner portion of the object.
Flag specifying the effect being 'glow' instead of a shadow.
An array describing the shadow contour function.
The color of the shadow.
Blend mode of the shadow.
Blend mode.
Type
Properties
ContourItem
A segment in a shadow contour function.
The contour function segment bottom limit.
The contour function segment top limit.
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.
ID of a layer the export is assigned to.
Identifier unique within the whole document.
ID of layer's parent.
Identifier unique within the whole document.
Index of the layer in parent's layers
array.
Type
Properties
ExportableFormatItem
Export format descriptor.
Describes value of the export's name prefix/suffix.
Format of the export.
Resizing constraint.
Type
Properties
ExportableItem
Export descriptor (slice or layer) with assigned export formats.
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.
Boolean describing if transparent pixels should be trimmed when exporting.
Background of the export.
Export descriptor's bounds (mainly useful for slices).
Property describes what should be included in export.
Array describing export formats (its type, size and naming).
Type
Properties
FlowInteractionItem
An interaction descriptor.
An object describing the target of the interaction.
Descriptor of the interaction animation properties.
If true, then artboard should preserve current scroll position.
Trigger (e.g. gesture) that initiates the interaction.
Id of a layer the interaction origins from.
Identifier unique within the whole document.
Type
Properties
Color
Color descriptor (RGBA).
Color channel for RED color.
Color channel value (ranged 0-255).
Color channel for GREEN color.
Color channel value (ranged 0-255).
Color channel for BLUE color.
Color channel value (ranged 0-255).
Alpha channel.
Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.
Type
Properties
Font
Text style descriptor.
Horizontal alignment of the text.
Common name of font.
Font type (called 'subfamily' in OpenType specification).
Font's size.
Describes if kerning feature is enabled in the text.
Text letter spacing (can be negative).
Text underline type.
0
none1
single line2
double lines
Describes if the text has line through.
Describes if the text is bold. If missing the information is not known.
Describes if the text is italic. If missing the information is not known.
Describes a ligature category.
0
none1
standard2
discretionary and historical3
all
Describes if the text is transformed to upper case.
Describes if the text is transformed to lower case.
Describes if the text is written in small capitals.
Describes baseline's position type.
PostScript name of the used font.
Whether the postScriptName
was generated (
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.
Feature tag, typically a 4 letter abbreviation of the feature's name.
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.
Describes a type of the point.
point
simple pointquad
point has a single control point, adjacent segment represents quadratic BΓ©zier curvecubic
point has two control points, adjacent segment represent cubic BΓ©zier curvebezier
alias forcubic
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]
.
Corner radius at the point.
Type
Properties
ShapeRectCornerRadius
Corner radius description (legacy, for rectangles only).
Radius of the top left corner.
Radius of the top right corner.
Radius of the bottom right corner.
Radius of the bottom left corner.
Type
Properties
ShapeSubpath
A single subpath (contour) descriptor.
Describes if the path is opened or closed
Type
Properties
ShapePath
A single vector path descriptor.
Type of a shape the vector path represents. If missing, the represented shape is not known.
Bounds of the path. If missing, bounds are not known.
Boolean operation combining this and next-in-the-array path.
Path rotation (in degrees).
Value of rotation in degrees.
Vertical flip transformation flag. If true, path should be reversed across y-axis.
Horizontal flip transformation flag. If true, path should be reversed across x-axis.
[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.
If the shape is vector mask, this value describes if it is enabled or not.
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.
Bitmap mask bounds. If missing, the value of layer.bitmap
is used instead.
URI reference of the bitmap mask file (URL or relative filename)
Determines whether the mask is applied.
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.
A reference to the layer ID the bitmap descriptor should be copied from.
Identifier unique within the whole document.
Bitmap bounds including effects, such as shadows, blurs, outside borders etc.
True if the layer is completely blank. Such layer does not have any non-transparent pixels.
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
.
URI reference of the bitmap mask file (URL or relative filename)
[internal] Describes if the bitmap channels has been alpha pre-multiplied.
[internal] Mostly used for layer 'pre-rendering', contains various information of the render configuration.
[deprecated] If the bitmap.filename
is a sprite atlas, these are coordinates of the this layer's sprite in the atlas.
Describes if the bitmap already contains all the effects.
Type
Properties
TransformMatrix
A text transformation matrix (relative to the document).
Type
Properties
TextStyleItem
Text style defined for particular fragments of the text (text ranges).
Font style descriptor for the style range.
Color descriptor for the style range.
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.
[Photoshop only, deprecated] Describes whether the first line's height is considered in the layer bounds calculation.
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.
[Photoshop only] Text transform scale factors.
Text content of the text layer.
[deprecated, use frame
instead] Bounds of the text. Text bounds are not always same as layer bounds.
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.
Specifies the text frame semantics. fixed
mode strictly sets the typeset area according to the frame
, 'auto' mode expands bounds as needed.
Text vertical alignment relative to the whole layer.
Defines a way the baseline position is determined.
fixed
- baseline distance from a layer top is given only by font propertiescenter
- baseline is centered within the line (i.e. depends onlineHeight
)
Type
Properties
LayerBase
Common layer description.
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.
Name of the layer.
Describes a software the layer originally cames from.
Describes the layer visibility.
Bounds of the layer (without effects).
Specifies vector geometry of the layer. For non-shape layers acts like a vector mask.
The value is true
for layers that are being masked by another layer, such layers should have maskedBy
property as well.
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.
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
Clip bounds could be used instead of a rectangular clipping mask of the same position and size.
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.
Fill opacity level of the layer.
Floating-point number in the interval from 0 to 1 (inclusive) describing alpha channel (opacity) value.
Blend mode of the layer.
Blend mode.
Layer effects descriptor.
Layer content rasterized as a bitmap image.
Rotation of the layer in degrees.
Value of rotation in degrees.
Vertical flip transformation flag. If true, the layer should be reversed across y-axis (flopped).
Horizontal flip transformation flag. If true, the layer should be reversed across x-axis.
True if the layer is completely blank. Such layer does not have any non-transparent pixels.
[deprecated] Layer bounds with applied transformations (such as rotation and flips).
[deprecated]
ID of the symbol master this layer refers to.
Identifier unique within the whole document.
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)
[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.
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.
Specifies the layer to be a shape layer.
Layer border represented as a custom geometry.
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.
Type
Properties
Type
Properties
DocumentLayer
Document layer represents a content of a foreign document as a local layer.
Specifies the layer to be a document layer.
An ID of the Smart-object (Photoshop) or Artboard (Sketch).
Identifier unique within the whole document.
Type
Properties
AdjustmentLayer
[Photoshop only] Adjustment layer represents a color and tonal adjustment configuration.
[Photoshop only] Specifies the layer to be an adjustment layer.
[incomplete] Adjustment configuration
Type
Properties
LayerLayer
Layer of this type represents a bitmap layer or a symbol instance layer.
Specifies the layer to be of type 'layer'.
Type
Properties
BackgroundLayer
Background layer is an artificial layer representing background configuration of a document.
Specifies the layer to be a background layer.
Type
Properties
GroupLayer
Group layer is a composite layer containing other layers as components.
Specifies the layer to be a group layer.
Photoshop groupLayer
can be an artboard, in such case there will be a artboard object with its bounds.
[Sketch only] Smart layout applied to group layer
[Sketch only] Describes a smart layout configuration.
Type
Properties
Layer
A layer is a building block of a document. Can be of various types and can form hierarchies.
Was this article helpful?