feat: ComponentPropertyDefinition / ComponentProperty を type 別スキーマに分割#2
feat: ComponentPropertyDefinition / ComponentProperty を type 別スキーマに分割#2amotarao wants to merge 4 commits into
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
WalkthroughOpenAPI スキーマの Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
openapi/openapi.yaml (1)
5601-5607:boundVariablesの重複定義は共通スキーマ化を推奨します。同一構造が4箇所に重複しているため、将来的な差分漏れを防ぐために抽出したほうが保守しやすいです。
♻️ 提案差分（共通化）
+ ComponentPropertyBoundVariables: + type: object + description: The variables bound to a particular field on this component property + properties: + value: + $ref: "#/components/schemas/VariableAlias" + BooleanComponentProperty: type: object description: A boolean property of a component. properties: @@ - boundVariables: - type: object - description: The variables bound to a particular field on this component property - properties: - value: - $ref: "#/components/schemas/VariableAlias" + boundVariables: + $ref: "#/components/schemas/ComponentPropertyBoundVariables" TextComponentProperty: @@ - boundVariables: - type: object - description: The variables bound to a particular field on this component property - properties: - value: - $ref: "#/components/schemas/VariableAlias" + boundVariables: + $ref: "#/components/schemas/ComponentPropertyBoundVariables" VariantComponentProperty: @@ - boundVariables: - type: object - description: The variables bound to a particular field on this component property - properties: - value: - $ref: "#/components/schemas/VariableAlias" + boundVariables: + $ref: "#/components/schemas/ComponentPropertyBoundVariables" InstanceSwapComponentProperty: @@ - boundVariables: - type: object - description: The variables bound to a particular field on this component property - properties: - value: - $ref: "#/components/schemas/VariableAlias" + boundVariables: + $ref: "#/components/schemas/ComponentPropertyBoundVariables"Also applies to: 5623-5628, 5644-5649, 5669-5674
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi/openapi.yaml` around lines 5601 - 5607, The repeated inline schema for boundVariables should be extracted into a shared component schema (e.g., create components.schemas.BoundVariables that has type: object, description and properties.value $ref: "#/components/schemas/VariableAlias"), then replace each inline occurrence (the current boundVariables blocks at the four locations) with a $ref to that new components.schemas.BoundVariables; update any required arrays that referenced the inline block to reference the same reusable schema to avoid duplication and future divergence.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@openapi/openapi.yaml`:
- Around line 5601-5607: The repeated inline schema for boundVariables should be
extracted into a shared component schema (e.g., create
components.schemas.BoundVariables that has type: object, description and
properties.value $ref: "#/components/schemas/VariableAlias"), then replace each
inline occurrence (the current boundVariables blocks at the four locations) with
a $ref to that new components.schemas.BoundVariables; update any required arrays
that referenced the inline block to reference the same reusable schema to avoid
duplication and future divergence.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f338acd9-a587-481f-b3ae-a9436574804e
📒 Files selected for processing (1)
openapi/openapi.yaml
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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 `@openapi/openapi.yaml`:
- Around line 5675-5678: The OpenAPI change made
InstanceSwapComponentProperty.preferredValues mandatory which breaks
compatibility; update the schema so preferredValues is optional by removing
"preferredValues" from the required array for InstanceSwapComponentProperty (the
block that currently lists required: - type - value - preferredValues) and
ensure the Definition-level required entries remain unchanged; target the
InstanceSwapComponentProperty schema in openapi.yaml and remove only the
preferredValues entry from its required list.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f849e6c1-ea1a-4b2e-99e3-e47338a757e7
📒 Files selected for processing (1)
openapi/openapi.yaml
| required: | ||
| - type | ||
| - value | ||
| - preferredValues |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Find and examine the openapi.yaml file
find . -name "openapi.yaml" -o -name "*.yaml" | grep -i openapi | head -20Repository: plainbrew/figma-rest-api-spec
Length of output: 95
🏁 Script executed:
# Check lines 5574 and 5675-5678 in openapi.yaml to understand the context
if [ -f "openapi/openapi.yaml" ]; then
echo "=== Definition side (around line 5574) ==="
sed -n '5560,5590p' openapi/openapi.yaml
echo ""
echo "=== Property side (around line 5675-5678) ==="
sed -n '5660,5690p' openapi/openapi.yaml
fiRepository: plainbrew/figma-rest-api-spec
Length of output: 2147
🌐 Web query:
Figma REST API INSTANCE_SWAP componentProperties preferredValues field required
💡 Result:
In the Figma REST API, the preferredValues field under componentProperties / componentPropertyDefinitions is not required:
- In the REST API type definitions, it is explicitly marked as optional (
preferredValues?) and “only exists onINSTANCE_SWAPproperties.” If there are no preferred values, the field may be omitted entirely. [1] - This matches the Plugin API docs wording: for
INSTANCE_SWAPproperties, preferred values are optional. [2]
If preferredValues is present, each entry is an InstanceSwapPreferredValue object with required fields like:
type:"COMPONENT"or"COMPONENT_SET"key: the component / component set key [1]
Sources:
[1] Figma REST API – File property types (ComponentProperty / ComponentPropertyDefinition / InstanceSwapPreferredValue) (developers.figma.com)
[2] Figma Plugin API – ComponentPropertyDefinitions (“may optionally have… InstanceSwapPreferredValue”) (developers.figma.com)
Citations:
- 1: https://developers.figma.com/docs/rest-api/file-property-types/
- 2: https://developers.figma.com/docs/plugins/api/ComponentPropertyDefinitions/
🌐 Web query:
Figma API official documentation Instance node componentProperties schema
💡 Result:
In Figma’s official Plugin API docs, an InstanceNode exposes:
instance.componentProperties schema (type: ComponentProperties)
A map keyed by component property name:
type ComponentProperties = {
[propertyName: string]: {
type: ComponentPropertyType
value: string | boolean
preferredValues?: InstanceSwapPreferredValue[]
readonly boundVariables?: {
[field in VariableBindableComponentPropertyField]?: VariableAlias
}
}
}
type VariableBindableComponentPropertyField = "value"This is documented as “a map of component properties that exist on an instance node.” [1]
Key naming rule (propertyName)
For TEXT, BOOLEAN, and INSTANCE_SWAP properties, the propertyName you use/read is the UI name suffixed with # + a unique id (the full suffixed name must be used in component-property-related APIs). [2]
Where the names/types come from
InstanceNode docs note that propertyName corresponds to the names returned by componentPropertyDefinitions, and reiterate the #<unique id> suffix requirement for TEXT / BOOLEAN / INSTANCE_SWAP. [3]
Sources: [1] [2] [3]
InstanceSwapComponentProperty.preferredValues の必須化は互換性リスクがあります。
Figma 公式 REST API ドキュメントでは、preferredValues はオプションフィールド（preferredValues?）として定義されており、値がない場合は省略される可能性があります。Line 5678 で必須にすると、既存レスポンスが type/value のみを返すケースでバリデーション破壊が発生します。Definition 側（Line 5574）を必須にするのは妥当ですが、Property 側は任意のままにするべきです。
修正案（Property 側の必須解除）
InstanceSwapComponentProperty:
required:
- type
- value
- - preferredValues📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| required: | |
| - type | |
| - value | |
| - preferredValues | |
| required: | |
| - type | |
| - value |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openapi/openapi.yaml` around lines 5675 - 5678, The OpenAPI change made
InstanceSwapComponentProperty.preferredValues mandatory which breaks
compatibility; update the schema so preferredValues is optional by removing
"preferredValues" from the required array for InstanceSwapComponentProperty (the
block that currently lists required: - type - value - preferredValues) and
ensure the Definition-level required entries remain unchanged; target the
InstanceSwapComponentProperty schema in openapi.yaml and remove only the
preferredValues entry from its required list.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
openapi/openapi.yaml (1)
5620-5641:⚠️ Potential issue | 🟠 Major
VariantComponentProperty.boundVariablesは必須にしないでください。Figma の公式 API 仕様によると、
boundVariablesは変数にバインドされている場合にのみ存在し、バインドされていない場合は省略される設計になっています。現在の YAML では必須にすることで、未バインド状態の VARIANT プロパティを不正に扱う恐れがあります。修正案
VariantComponentProperty: required: - type - value - - boundVariables🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi/openapi.yaml` around lines 5620 - 5641, 現在の VariantComponentProperty スキーマにある required 配列から boundVariables を削除し、VariantComponentProperty の定義（プロパティ名: boundVariables、$ref: "#/components/schemas/VariableAlias" を参照）を必須ではなく省略可能にしてください；つまり OpenAPI の VariantComponentProperty スキーマから "boundVariables" を required リストに含めないよう修正し、既存の boundVariables プロパティ定義はそのまま残して「存在しない場合がある」ことを表現してください。
♻️ Duplicate comments (1)
openapi/openapi.yaml (1)
5658-5661:⚠️ Potential issue | 🟠 Major
InstanceSwapComponentProperty.preferredValuesの必須化は後方互換性を壊します。Line 5661 の required 化で、
type/valueのみ返す既存レスポンスが不正になります。💡 修正案
InstanceSwapComponentProperty: required: - type - value - - preferredValuesFigma REST API の ComponentProperty 仕様で、INSTANCE_SWAP の preferredValues は必須ですか？ optional（preferredValues?）ですか？🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openapi/openapi.yaml` around lines 5658 - 5661, 現在の OpenAPI 定義で InstanceSwapComponentProperty の required に preferredValues を追加すると後方互換性が壊れるので、該当スキーマ（InstanceSwapComponentProperty）から preferredValues を required 配列から外して optional に戻してください（現在 required に含まれている "type","value","preferredValues" を "type","value" のみに変更）。もし preferredValues を必須扱いにする意図があるなら、代替案としてはスキーマ変更に伴うバージョンアップ／リリースノート追記を行ってから必須化する旨を明記してください。
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi/openapi.yaml`:
- Around line 5571-5574: The schema currently marks
InstanceSwapComponentPropertyDefinition.preferredValues as required; remove
"preferredValues" from the required array for the
InstanceSwapComponentPropertyDefinition schema in openapi.yaml so
preferredValues becomes optional (per Figma REST API), ensuring existing
INSTANCE_SWAP definitions without preferredValues remain compatible.
---
Outside diff comments:
In `@openapi/openapi.yaml`:
- Around line 5620-5641: 現在の VariantComponentProperty スキーマにある required 配列から
boundVariables を削除し、VariantComponentProperty の定義（プロパティ名: boundVariables、$ref:
"#/components/schemas/VariableAlias" を参照）を必須ではなく省略可能にしてください；つまり OpenAPI の
VariantComponentProperty スキーマから "boundVariables" を required リストに含めないよう修正し、既存の
boundVariables プロパティ定義はそのまま残して「存在しない場合がある」ことを表現してください。
---
Duplicate comments:
In `@openapi/openapi.yaml`:
- Around line 5658-5661: 現在の OpenAPI 定義で InstanceSwapComponentProperty の
required に preferredValues
を追加すると後方互換性が壊れるので、該当スキーマ（InstanceSwapComponentProperty）から preferredValues を
required 配列から外して optional に戻してください（現在 required に含まれている
"type","value","preferredValues" を "type","value" のみに変更）。もし preferredValues
を必須扱いにする意図があるなら、代替案としてはスキーマ変更に伴うバージョンアップ／リリースノート追記を行ってから必須化する旨を明記してください。
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 36d28fd9-3e7e-40d1-bc33-ef6dc243f9b2
📒 Files selected for processing (1)
openapi/openapi.yaml
amotarao
changed the title
plainbrew/figma-rest-api-spec#2 の変更を適用。 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 participant
変更内容
ComponentPropertyDefinitionとComponentPropertyを、typeフィールドの値ごとに専用スキーマへ分割しました。oneOf+discriminatorによる判別子ユニオン構造になっています。ComponentPropertyDefinition
BooleanComponentPropertyDefinitionBOOLEANbooleanTextComponentPropertyDefinitionTEXTstringVariantComponentPropertyDefinitionVARIANTstringvariantOptions(required)InstanceSwapComponentPropertyDefinitionINSTANCE_SWAPstringpreferredValues(required)ComponentProperty
BooleanComponentPropertyBOOLEANbooleanTextComponentPropertyTEXTstringVariantComponentPropertyVARIANTstringboundVariables(required)InstanceSwapComponentPropertyINSTANCE_SWAPstringpreferredValues(required)