Skip to content

feat: ComponentProperty / ComponentPropertyDefinition を type 別スキーマに分割 #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amotarao merged 3 commits into from
Mar 20, 2026
Merged

feat: ComponentProperty / ComponentPropertyDefinition を type 別スキーマに分割 #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
08ca3cc
feat: ComponentPropertyDefinition / ComponentProperty を type 別スキーマに分割
amotarao Mar 6, 2026
71fcd48
changeset
amotarao Mar 6, 2026
c90e1c5
chore: 不要になった ComponentPropertyType を削除
amotarao Mar 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/young-islands-open.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@plainbrew/figma-rest-api-spec": minor
---

ComponentPropertyDefinition / ComponentProperty を type 別スキーマに分割
167 changes: 139 additions & 28 deletions packages/figma-rest-api-spec/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5462,14 +5462,6 @@ components:
letterSpacing:
$ref: "#/components/schemas/VariableAlias"
- $ref: "#/components/schemas/BaseTypeStyle"
ComponentPropertyType:
type: string
description: Component property type.
enum:
- BOOLEAN
- INSTANCE_SWAP
- TEXT
- VARIANT
InstanceSwapPreferredValue:
type: object
description: Instance swap preferred value.
Expand All @@ -5487,50 +5479,147 @@ components:
- type
- key
ComponentPropertyDefinition:
type: object
description: A property of a component.
oneOf:
- $ref: "#/components/schemas/BooleanComponentPropertyDefinition"
- $ref: "#/components/schemas/TextComponentPropertyDefinition"
- $ref: "#/components/schemas/VariantComponentPropertyDefinition"
- $ref: "#/components/schemas/InstanceSwapComponentPropertyDefinition"
discriminator:
propertyName: type
mapping:
BOOLEAN: "#/components/schemas/BooleanComponentPropertyDefinition"
TEXT: "#/components/schemas/TextComponentPropertyDefinition"
VARIANT: "#/components/schemas/VariantComponentPropertyDefinition"
INSTANCE_SWAP: "#/components/schemas/InstanceSwapComponentPropertyDefinition"
BooleanComponentPropertyDefinition:
type: object
description: A boolean property of a component.
properties:
type:
$ref: "#/components/schemas/ComponentPropertyType"
type: string
enum:
- BOOLEAN
description: Type of this component property.
defaultValue:
oneOf:
- type: boolean
- type: string
type: boolean
description: Initial value of this property for instances.
required:
- type
- defaultValue
TextComponentPropertyDefinition:
type: object
description: A text property of a component.
properties:
type:
type: string
enum:
- TEXT
description: Type of this component property.
defaultValue:
type: string
description: Initial value of this property for instances.
required:
- type
- defaultValue
VariantComponentPropertyDefinition:
type: object
description: A variant property of a component.
properties:
type:
type: string
enum:
- VARIANT
description: Type of this component property.
defaultValue:
type: string
description: Initial value of this property for instances.
variantOptions:
type: array
items:
type: string
description: All possible values for this property. Only exists on VARIANT
properties.
description: All possible values for this property.
required:
- type
- defaultValue
- variantOptions
InstanceSwapComponentPropertyDefinition:
type: object
description: An instance swap property of a component.
properties:
type:
type: string
enum:
- INSTANCE_SWAP
description: Type of this component property.
defaultValue:
type: string
description: Initial value of this property for instances.
preferredValues:
type: array
items:
$ref: "#/components/schemas/InstanceSwapPreferredValue"
description: Preferred values for this property. Only applicable if type is
`INSTANCE_SWAP`.
description: Preferred values for this property.
required:
- type
- defaultValue
- preferredValues
Comment on lines 5558 to +5566

@coderabbitai coderabbitai Bot Mar 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Figma REST API property types INSTANCE_SWAP preferredValues optional required

💡 Result:

In the Figma REST API, preferredValues is only applicable to INSTANCE_SWAP component properties, and it is optional (not required).

  • ComponentPropertyDefinition

    • Required:
      • type (BOOLEAN | INSTANCE_SWAP | TEXT | VARIANT)
      • defaultValue (Boolean | String)
    • Optional:
      • variantOptions? (only exists for VARIANT)
      • preferredValues? (only exists for INSTANCE_SWAP) [1]

  • ComponentProperty (property values on an instance)

    • Required:
      • type
      • value
    • Optional:
      • preferredValues? (only exists for INSTANCE_SWAP) [1]

  • preferredValues element shape: InstanceSwapPreferredValue

    • Required fields:
      • type: COMPONENT or COMPONENT_SET
      • key: string (the component/component-set key) [1]

So, for INSTANCE_SWAP, preferredValues may be present, but clients should treat it as optional and handle it being absent. [1]

Sources

🌐 Web query:

Figma API ComponentProperty boundVariables optional documentation

💡 Result:

In Figma’s APIs, boundVariables is optional and only present/populated when something is actually bound to a Variable.

  • Plugin API (component properties): ComponentPropertyDefinitions notes that a component property can optionally be bound to a Variable; when it is, the boundVariables structure is populated with a VariableAlias (otherwise it’s absent/empty). [1]
  • REST API (nodes in file JSON): nodes expose a boundVariables map that may include a componentProperties sub-map (by property name) when component properties are variable-bound; if nothing is bound, that map/field won’t be present. [2]
  • REST API type reference: boundVariables is documented as a (custom) property type, reinforcing it as a node field that may appear depending on bindings. [3]

Docs: [1] ComponentPropertyDefinitions (Plugin API), [2] REST API “Files” / global node properties, [3] REST API “File property types”.

🌐 Web query:

site:figma.com REST API property definitions ComponentProperty INSTANCE_SWAP

💡 Result:

In the Figma REST API file JSON, component property definitions are represented as a map of ComponentPropertyDefinition objects (typically exposed under a node’s componentPropertyDefinitions for COMPONENT / COMPONENT_SET nodes).

For an instance swap property, the definition shape is:

  • type: INSTANCE_SWAP
  • defaultValue: string (the initial value for instances; REST type is Boolean | String)
  • preferredValues?: array of InstanceSwapPreferredValue (only present for INSTANCE_SWAP)
    • each preferred value includes:
      • type: "COMPONENT" or "COMPONENT_SET"
      • key: the component / component set key

The relevant REST type definitions are documented under ComponentPropertyDefinition, ComponentPropertyType, and InstanceSwapPreferredValue. [1]

The same “definitions map” concept (and the note that INSTANCE_SWAP definitions can include preferredValues) is also described in Figma’s ComponentPropertyDefinitions reference. [2]

Sources: [1] (developers.figma.com) [2] (developers.figma.com)

Citations:

Make preferredValues and boundVariables optional in schema, not required.

According to official Figma REST API documentation, preferredValues for INSTANCE_SWAP is optional and only appears when defined. Similarly, boundVariables is optional and only present when something is actually bound to a variable. The current schema incorrectly marks these as required, which breaks compatibility with the actual API behavior and will cause validation failures and client generation errors.

Required schema changes 
     InstanceSwapComponentPropertyDefinition:
       ...
       required:
         - type
         - defaultValue
-        - preferredValues

     VariantComponentProperty:
       ...
       required:
         - type
         - value
-        - boundVariables

     InstanceSwapComponentProperty:
       ...
       required:
         - type
         - value
-        - preferredValues

Applies to lines 5566-5574, 5631-5641, 5653-5661.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/figma-rest-api-spec/openapi.yaml` around lines 5566 - 5574, The
schema currently marks preferredValues and boundVariables as required which is
incorrect; update the OpenAPI components schemas that reference preferredValues
(the schema listing type, defaultValue, preferredValues and items $ref
"#/components/schemas/InstanceSwapPreferredValue") and any schema that includes
boundVariables to remove those property names from their required arrays so both
preferredValues and boundVariables become optional (leave their property
definitions intact). Locate the relevant component schemas (the one referencing
InstanceSwapPreferredValue and the schemas around the other occurrences noted)
and delete "preferredValues" and "boundVariables" from each schema's required
list so the properties remain defined but are no longer required.

ComponentProperty:
type: object
description: A property of a component.
oneOf:
- $ref: "#/components/schemas/BooleanComponentProperty"
- $ref: "#/components/schemas/TextComponentProperty"
- $ref: "#/components/schemas/VariantComponentProperty"
- $ref: "#/components/schemas/InstanceSwapComponentProperty"
discriminator:
propertyName: type
mapping:
BOOLEAN: "#/components/schemas/BooleanComponentProperty"
TEXT: "#/components/schemas/TextComponentProperty"
VARIANT: "#/components/schemas/VariantComponentProperty"
INSTANCE_SWAP: "#/components/schemas/InstanceSwapComponentProperty"
BooleanComponentProperty:
type: object
description: A boolean property of a component.
properties:
type:
$ref: "#/components/schemas/ComponentPropertyType"
type: string
enum:
- BOOLEAN
description: Type of this component property.
value:
oneOf:
- type: boolean
- type: string
type: boolean
description: Value of the property for this component instance.
required:
- type
- value
TextComponentProperty:
type: object
description: A text property of a component.
properties:
type:
type: string
enum:
- TEXT
description: Type of this component property.
value:
type: string
description: Value of the property for this component instance.
required:
- type
- value
VariantComponentProperty:
type: object
description: A variant property of a component.
properties:
type:
type: string
enum:
- VARIANT
description: Type of this component property.
value:
type: string
description: Value of the property for this component instance.
preferredValues:
type: array
items:
$ref: "#/components/schemas/InstanceSwapPreferredValue"
description: Preferred values for this property. Only applicable if type is
`INSTANCE_SWAP`.
boundVariables:
type: object
description: The variables bound to a particular field on this component property
Expand All @@ -5540,6 +5629,28 @@ components:
required:
- type
- value
- boundVariables
InstanceSwapComponentProperty:
type: object
description: An instance swap property of a component.
properties:
type:
type: string
enum:
- INSTANCE_SWAP
description: Type of this component property.
value:
type: string
description: Value of the property for this component instance.
preferredValues:
type: array
items:
$ref: "#/components/schemas/InstanceSwapPreferredValue"
description: Preferred values for this property.
required:
- type
- value
- preferredValues
Overrides:
type: object
description: Fields directly overridden on an instance. Inherited overrides are
Expand Down