feat: ComponentProperty / ComponentPropertyDefinition を type 別スキーマに分割#46
Conversation
plainbrew/figma-rest-api-spec#2 の変更を適用。 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe OpenAPI spec replaces a single ComponentPropertyType enum and monolithic property schemas with discriminated oneOf unions, adding four type-specific Definition and Property public schemas: Boolean, Text, Variant, and InstanceSwap, with discriminator mappings on Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/figma-rest-api-spec/openapi.yaml`:
- Around line 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.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 1aac072c-75f1-4075-aa42-5294b5168545
📒 Files selected for processing (1)
packages/figma-rest-api-spec/openapi.yaml
| 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 |
There was a problem hiding this comment.
🧩 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 forVARIANT)preferredValues?(only exists forINSTANCE_SWAP) [1]
- Required:
-
ComponentProperty(property values on an instance)- Required:
typevalue
- Optional:
preferredValues?(only exists forINSTANCE_SWAP) [1]
- Required:
-
preferredValueselement shape:InstanceSwapPreferredValue- Required fields:
type:COMPONENTorCOMPONENT_SETkey: string (the component/component-set key) [1]
- Required fields:
So, for INSTANCE_SWAP, preferredValues may be present, but clients should treat it as optional and handle it being absent. [1]
Sources
- [1] Figma Developer Docs — “Property types” (REST API schemas) https://developers.figma.com/docs/rest-api/file-property-types/
🌐 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):
ComponentPropertyDefinitionsnotes that a component property can optionally be bound to a Variable; when it is, theboundVariablesstructure is populated with aVariableAlias(otherwise it’s absent/empty). [1] - REST API (nodes in file JSON): nodes expose a
boundVariablesmap that may include acomponentPropertiessub-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:
boundVariablesis 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_SWAPdefaultValue:string(the initial value for instances; REST type isBoolean | String)preferredValues?: array ofInstanceSwapPreferredValue(only present forINSTANCE_SWAP)- each preferred value includes:
type:"COMPONENT"or"COMPONENT_SET"key: the component / component set key
- each preferred value includes:
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:
- 1: https://developers.figma.com/docs/rest-api/file-property-types/
- 2: https://developers.figma.com/docs/plugins/api/ComponentPropertyDefinitions/
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
- - preferredValuesApplies 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.
amotarao
changed the title
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
packages/figma-rest-api-spec/openapi.yaml (1)
5546-5566:⚠️ Potential issue | 🟠 MajorKeep
preferredValuesoptional, and don't narrowboundVariablesto onlyVARIANT.Line 5566 and Line 5653 make
preferredValuesrequired even though Figma documents it as anINSTANCE_SWAP-only optional field. After the split,boundVariablesis also both required on Line 5632 and only present onVariantComponentProperty, while Figma documents it as an optional field onComponentPropertygenerally, populated only when a variable is actually bound. In this shape, valid responses will fail validation, and valid BOOLEAN/TEXT/INSTANCE_SWAP properties can no longer carryboundVariables. (developers.figma.com)🛠️ Proposed fix
InstanceSwapComponentPropertyDefinition: ... required: - type - defaultValue - - preferredValues VariantComponentProperty: ... required: - type - value - - boundVariables InstanceSwapComponentProperty: ... required: - type - value - - preferredValuesAlso move the existing
boundVariablesshape into a shared optional base for allComponentPropertyvariants, or duplicate it ontoBooleanComponentProperty,TextComponentProperty, andInstanceSwapComponentProperty.Also applies to: 5581-5653
🤖 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 5546 - 5566, The schema incorrectly makes preferredValues required on InstanceSwapComponentPropertyDefinition and restricts boundVariables to VariantComponentProperty; update the OpenAPI definitions so preferredValues is optional in InstanceSwapComponentPropertyDefinition (remove it from required) and move or duplicate the boundVariables schema into the shared ComponentProperty base (or add it as an optional property on BooleanComponentProperty, TextComponentProperty, and InstanceSwapComponentProperty) so boundVariables remains optional for all component property types; locate and edit InstanceSwapComponentPropertyDefinition, VariantComponentProperty, ComponentProperty (and BooleanComponentProperty/TextComponentProperty) to apply these changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@packages/figma-rest-api-spec/openapi.yaml`:
- Around line 5546-5566: The schema incorrectly makes preferredValues required
on InstanceSwapComponentPropertyDefinition and restricts boundVariables to
VariantComponentProperty; update the OpenAPI definitions so preferredValues is
optional in InstanceSwapComponentPropertyDefinition (remove it from required)
and move or duplicate the boundVariables schema into the shared
ComponentProperty base (or add it as an optional property on
BooleanComponentProperty, TextComponentProperty, and
InstanceSwapComponentProperty) so boundVariables remains optional for all
component property types; locate and edit
InstanceSwapComponentPropertyDefinition, VariantComponentProperty,
ComponentProperty (and BooleanComponentProperty/TextComponentProperty) to apply
these changes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b85b1c8f-eb57-4634-9207-fe639119f420
📒 Files selected for processing (2)
.changeset/young-islands-open.mdpackages/figma-rest-api-spec/openapi.yaml
✅ Files skipped from review due to trivial changes (1)
- .changeset/young-islands-open.md
2 participants
Summary
fix #44
ComponentPropertyDefinitionとComponentPropertyをtypeフィールドの値ごとに専用スキーマへ分割oneOf+discriminatorによる判別子ユニオン構造に変更ComponentPropertyDefinition
BooleanComponentPropertyDefinitionBOOLEANbooleanTextComponentPropertyDefinitionTEXTstringVariantComponentPropertyDefinitionVARIANTstringvariantOptions(required)InstanceSwapComponentPropertyDefinitionINSTANCE_SWAPstringpreferredValues(required)ComponentProperty
BooleanComponentPropertyBOOLEANbooleanTextComponentPropertyTEXTstringVariantComponentPropertyVARIANTstringboundVariables(required)InstanceSwapComponentPropertyINSTANCE_SWAPstringpreferredValues(required)🤖 Generated with Claude Code