Figma File

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://figma.com/schemas/figma/file.json",
  "title": "Figma File",
  "description": "A Figma design file containing a document tree with pages, frames, components, styles, and version metadata. This schema represents the response from the GET /v1/files/{file_key} endpoint.",
  "type": "object",
  "required": ["name", "role", "lastModified", "editorType", "version", "document", "components", "componentSets", "schemaVersion", "styles"],
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the file as it appears in the Figma editor and file browser."
    },
    "role": {
      "type": "string",
      "enum": ["owner", "editor", "viewer"],
      "description": "The role of the user making the API request in relation to the file."
    },
    "lastModified": {
      "type": "string",
      "format": "date-time",
      "description": "The UTC ISO 8601 time at which the file was last modified."
    },
    "editorType": {
      "type": "string",
      "enum": ["figma", "figjam"],
      "description": "The type of editor associated with this file. Figma is for design files, FigJam is for whiteboarding."
    },
    "thumbnailUrl": {
      "type": "string",
      "format": "uri",
      "description": "A URL to a thumbnail image of the file. The URL expires after a period of time."
    },
    "version": {
      "type": "string",
      "description": "The current version number of the file. This changes on every save."
    },
    "document": {
      "$ref": "#/$defs/DocumentNode"
    },
    "components": {
      "type": "object",
      "description": "A mapping from component IDs to component metadata for all components in the file.",
      "additionalProperties": {
        "$ref": "#/$defs/Component"
      }
    },
    "componentSets": {
      "type": "object",
      "description": "A mapping from component set IDs to component set metadata.",
      "additionalProperties": {
        "$ref": "#/$defs/ComponentSet"
      }
    },
    "schemaVersion": {
      "type": "integer",
      "description": "The version of the Figma file schema that this file uses.",
      "minimum": 0
    },
    "styles": {
      "type": "object",
      "description": "A mapping from style IDs to style metadata for all styles in the file.",
      "additionalProperties": {
        "$ref": "#/$defs/Style"
      }
    },
    "mainFileKey": {
      "type": "string",
      "description": "The key of the main file. Present only when this file is a branch."
    },
    "branches": {
      "type": "array",
      "description": "A list of branches for this file. Only present if branch_data was requested.",
      "items": {
        "$ref": "#/$defs/Branch"
      }
    }
  },
  "$defs": {
    "DocumentNode": {
      "type": "object",
      "description": "The root node of the Figma document tree. Contains one or more canvas (page) nodes.",
      "required": ["id", "name", "type", "children"],
      "properties": {
        "id": {
          "type": "string",
          "description": "A string uniquely identifying this node within the document. The document root is always '0:0'."
        },
        "name": {
          "type": "string",
          "description": "The name given to the node by the user in the tool."
        },
        "type": {
          "type": "string",
          "enum": ["DOCUMENT"],
          "description": "The type of the node. Always DOCUMENT for the root node."
        },
        "children": {
          "type": "array",
          "description": "An array of canvas (page) nodes attached to the document.",
          "items": {
            "$ref": "#/$defs/CanvasNode"
          }
        }
      }
    },
    "CanvasNode": {
      "type": "object",
      "description": "A canvas represents a page in the Figma file. Each canvas contains layers of design elements.",
      "required": ["id", "name", "type"],
      "properties": {
        "id": {
          "type": "string",
          "description": "A string uniquely identifying this node within the document."
        },
        "name": {
          "type": "string",
          "description": "The name of the page as displayed in the layers panel."
        },
        "type": {
          "type": "string",
          "enum": ["CANVAS"],
          "description": "The type of the node. Always CANVAS for page nodes."
        },
        "backgroundColor": {
          "$ref": "#/$defs/Color"
        },
        "children": {
          "type": "array",
          "description": "An array of top-level layers on the canvas.",
          "items": {
            "$ref": "#/$defs/Node"
          }
        },
        "prototypeStartNodeID": {
          "type": ["string", "null"],
          "description": "The ID of the node that is the starting point for prototyping on this page."
        },
        "flowStartingPoints": {
          "type": "array",
          "description": "An array of flow starting points for prototyping.",
          "items": {
            "type": "object",
            "properties": {
              "nodeId": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "Node": {
      "type": "object",
      "description": "A generic node in the Figma document tree. Nodes have different types such as FRAME, GROUP, TEXT, RECTANGLE, VECTOR, COMPONENT, INSTANCE, and others.",
      "required": ["id", "name", "type"],
      "properties": {
        "id": {
          "type": "string",
          "description": "A string uniquely identifying this node within the document."
        },
        "name": {
          "type": "string",
          "description": "The name given to the node by the user in the tool."
        },
        "type": {
          "type": "string",
          "description": "The type of the node.",
          "enum": [
            "DOCUMENT",
            "CANVAS",
            "FRAME",
            "GROUP",
            "SECTION",
            "VECTOR",
            "BOOLEAN_OPERATION",
            "STAR",
            "LINE",
            "ELLIPSE",
            "REGULAR_POLYGON",
            "RECTANGLE",
            "TABLE",
            "TABLE_CELL",
            "TEXT",
            "SLICE",
            "COMPONENT",
            "COMPONENT_SET",
            "INSTANCE",
            "STICKY",
            "SHAPE_WITH_TEXT",
            "CONNECTOR",
            "STAMP",
            "WIDGET",
            "EMBED",
            "LINK_UNFURL",
            "MEDIA",
            "WASHI_TAPE",
            "HIGHLIGHT"
          ]
        },
        "visible": {
          "type": "boolean",
          "description": "Whether the node is visible on the canvas. Defaults to true.",
          "default": true
        },
        "locked": {
          "type": "boolean",
          "description": "Whether the node is locked, preventing it from being selected and modified.",
          "default": false
        },
        "children": {
          "type": "array",
          "description": "An array of child nodes, present for node types that can contain children.",
          "items": {
            "$ref": "#/$defs/Node"
          }
        },
        "absoluteBoundingBox": {
          "$ref": "#/$defs/Rectangle"
        },
        "absoluteRenderBounds": {
          "$ref": "#/$defs/Rectangle"
        },
        "fills": {
          "type": "array",
          "description": "An array of fill paints applied to the node.",
          "items": {
            "$ref": "#/$defs/Paint"
          }
        },
        "strokes": {
          "type": "array",
          "description": "An array of stroke paints applied to the node.",
          "items": {
            "$ref": "#/$defs/Paint"
          }
        },
        "strokeWeight": {
          "type": "number",
          "description": "The weight of strokes on the node.",
          "minimum": 0
        },
        "opacity": {
          "type": "number",
          "description": "Opacity of the node, from 0 to 1.",
          "minimum": 0,
          "maximum": 1,
          "default": 1
        },
        "effects": {
          "type": "array",
          "description": "An array of effects attached to this node.",
          "items": {
            "$ref": "#/$defs/Effect"
          }
        },
        "componentId": {
          "type": "string",
          "description": "For INSTANCE nodes, the ID of the component that this instance refers to."
        },
        "characters": {
          "type": "string",
          "description": "For TEXT nodes, the raw characters in the text node."
        }
      }
    },
    "Color": {
      "type": "object",
      "description": "An RGBA color value with all channels ranging from 0 to 1.",
      "required": ["r", "g", "b", "a"],
      "properties": {
        "r": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Red channel value, between 0 and 1."
        },
        "g": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Green channel value, between 0 and 1."
        },
        "b": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Blue channel value, between 0 and 1."
        },
        "a": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Alpha channel value, between 0 and 1."
        }
      }
    },
    "Rectangle": {
      "type": "object",
      "description": "A bounding rectangle defined by its position and size.",
      "properties": {
        "x": {
          "type": "number",
          "description": "X coordinate of the top left corner."
        },
        "y": {
          "type": "number",
          "description": "Y coordinate of the top left corner."
        },
        "width": {
          "type": "number",
          "description": "Width of the rectangle.",
          "minimum": 0
        },
        "height": {
          "type": "number",
          "description": "Height of the rectangle.",
          "minimum": 0
        }
      }
    },
    "Paint": {
      "type": "object",
      "description": "A paint applied as a fill or stroke. Can be a solid color, gradient, or image.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of paint.",
          "enum": [
            "SOLID",
            "GRADIENT_LINEAR",
            "GRADIENT_RADIAL",
            "GRADIENT_ANGULAR",
            "GRADIENT_DIAMOND",
            "IMAGE",
            "EMOJI",
            "VIDEO"
          ]
        },
        "visible": {
          "type": "boolean",
          "description": "Whether the paint is visible.",
          "default": true
        },
        "opacity": {
          "type": "number",
          "description": "Overall opacity of the paint, from 0 to 1.",
          "minimum": 0,
          "maximum": 1,
          "default": 1
        },
        "color": {
          "$ref": "#/$defs/Color"
        },
        "blendMode": {
          "type": "string",
          "description": "How this paint blends with the paints below it.",
          "enum": [
            "NORMAL",
            "DARKEN",
            "MULTIPLY",
            "LINEAR_BURN",
            "COLOR_BURN",
            "LIGHTEN",
            "SCREEN",
            "LINEAR_DODGE",
            "COLOR_DODGE",
            "OVERLAY",
            "SOFT_LIGHT",
            "HARD_LIGHT",
            "DIFFERENCE",
            "EXCLUSION",
            "HUE",
            "SATURATION",
            "COLOR",
            "LUMINOSITY"
          ]
        },
        "imageRef": {
          "type": "string",
          "description": "For IMAGE paints, a reference to the image content."
        },
        "scaleMode": {
          "type": "string",
          "description": "For IMAGE paints, how the image is scaled within the node.",
          "enum": ["FILL", "FIT", "TILE", "STRETCH"]
        }
      }
    },
    "Effect": {
      "type": "object",
      "description": "A visual effect applied to a node such as a shadow or blur.",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of effect.",
          "enum": [
            "INNER_SHADOW",
            "DROP_SHADOW",
            "LAYER_BLUR",
            "BACKGROUND_BLUR"
          ]
        },
        "visible": {
          "type": "boolean",
          "description": "Whether the effect is visible.",
          "default": true
        },
        "radius": {
          "type": "number",
          "description": "Radius of the effect (blur radius for blur effects, shadow spread).",
          "minimum": 0
        },
        "color": {
          "$ref": "#/$defs/Color"
        },
        "blendMode": {
          "type": "string",
          "description": "Blend mode of the effect."
        },
        "offset": {
          "type": "object",
          "description": "Offset of the shadow effect.",
          "properties": {
            "x": {
              "type": "number"
            },
            "y": {
              "type": "number"
            }
          }
        },
        "spread": {
          "type": "number",
          "description": "Spread of the shadow effect.",
          "default": 0
        }
      }
    },
    "Component": {
      "type": "object",
      "description": "Metadata about a main component within the file.",
      "required": ["key", "name", "description", "documentationLinks", "remote"],
      "properties": {
        "key": {
          "type": "string",
          "description": "The globally unique key of the component."
        },
        "name": {
          "type": "string",
          "description": "Name of the component."
        },
        "description": {
          "type": "string",
          "description": "The description of the component as entered in the editor."
        },
        "componentSetId": {
          "type": ["string", "null"],
          "description": "The ID of the component set this component belongs to, if any."
        },
        "documentationLinks": {
          "type": "array",
          "description": "An array of documentation links attached to this component.",
          "items": {
            "type": "object",
            "required": ["uri"],
            "properties": {
              "uri": {
                "type": "string",
                "format": "uri",
                "description": "The URI of the documentation link."
              }
            }
          }
        },
        "remote": {
          "type": "boolean",
          "description": "Whether this component is a remote component from an external library."
        }
      }
    },
    "ComponentSet": {
      "type": "object",
      "description": "Metadata about a component set, which groups variants of a component together.",
      "required": ["key", "name", "description"],
      "properties": {
        "key": {
          "type": "string",
          "description": "The globally unique key of the component set."
        },
        "name": {
          "type": "string",
          "description": "Name of the component set."
        },
        "description": {
          "type": "string",
          "description": "The description of the component set."
        },
        "documentationLinks": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["uri"],
            "properties": {
              "uri": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        },
        "remote": {
          "type": "boolean",
          "description": "Whether this component set is from a remote library."
        }
      }
    },
    "Style": {
      "type": "object",
      "description": "Metadata about a style that can be applied to nodes.",
      "required": ["key", "name", "description", "remote", "styleType"],
      "properties": {
        "key": {
          "type": "string",
          "description": "The globally unique key of the style."
        },
        "name": {
          "type": "string",
          "description": "Name of the style."
        },
        "description": {
          "type": "string",
          "description": "Description of the style."
        },
        "remote": {
          "type": "boolean",
          "description": "Whether this style is from a remote library."
        },
        "styleType": {
          "type": "string",
          "description": "The type of style.",
          "enum": ["FILL", "TEXT", "EFFECT", "GRID"]
        }
      }
    },
    "Branch": {
      "type": "object",
      "description": "Information about a branch of a Figma file.",
      "required": ["key", "name", "thumbnailUrl", "lastModified"],
      "properties": {
        "key": {
          "type": "string",
          "description": "The key of the branch file."
        },
        "name": {
          "type": "string",
          "description": "The name of the branch."
        },
        "thumbnailUrl": {
          "type": "string",
          "format": "uri",
          "description": "A URL to a thumbnail image of the branch."
        },
        "lastModified": {
          "type": "string",
          "format": "date-time",
          "description": "The UTC ISO 8601 time at which the branch was last modified."
        }
      }
    },
    "User": {
      "type": "object",
      "description": "A Figma user account.",
      "required": ["id", "handle", "imgUrl"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique stable ID of the user."
        },
        "handle": {
          "type": "string",
          "description": "Display name of the user."
        },
        "imgUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL to the user's profile image."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address associated with the user's account."
        }
      }
    },
    "Version": {
      "type": "object",
      "description": "A recorded version entry in the file's version history.",
      "required": ["id", "createdAt", "label", "description", "user"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the version."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "The UTC ISO 8601 time at which the version was created."
        },
        "label": {
          "type": ["string", "null"],
          "description": "The label given to the version in the editor."
        },
        "description": {
          "type": ["string", "null"],
          "description": "The description of the version."
        },
        "user": {
          "$ref": "#/$defs/User"
        }
      }
    },
    "Comment": {
      "type": "object",
      "description": "A comment or reply left by a user on a Figma file.",
      "required": ["id", "fileKey", "user", "createdAt", "message", "reactions", "orderId"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the comment."
        },
        "fileKey": {
          "type": "string",
          "description": "The key of the file the comment belongs to."
        },
        "parentId": {
          "type": ["string", "null"],
          "description": "If present, the ID of the comment to which this is a reply."
        },
        "user": {
          "$ref": "#/$defs/User"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "The UTC ISO 8601 time at which the comment was left."
        },
        "resolvedAt": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "If set, the UTC ISO 8601 time the comment was resolved."
        },
        "message": {
          "type": "string",
          "description": "The content of the comment."
        },
        "orderId": {
          "type": ["string", "null"],
          "description": "The number displayed with the comment in the UI."
        },
        "reactions": {
          "type": "array",
          "description": "An array of emoji reactions to the comment.",
          "items": {
            "$ref": "#/$defs/Reaction"
          }
        }
      }
    },
    "Reaction": {
      "type": "object",
      "description": "An emoji reaction left on a comment.",
      "required": ["user", "emoji", "createdAt"],
      "properties": {
        "user": {
          "$ref": "#/$defs/User"
        },
        "emoji": {
          "type": "string",
          "description": "The emoji used for the reaction."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "The UTC ISO 8601 time at which the reaction was left."
        }
      }
    }
  }
}