OpenAPI omits vector/shape stroke and annotation schemas and conflicts with current REST docs #102

Summary

The current REST docs publish variableWidthPoints, complexStrokeProperties, and annotations on VECTOR-derived nodes, but tagged @figma/rest-api-spec 0.44.0 still declares VariableWidthStrokesTrait, ComplexStrokesTrait, and AnnotationsTrait as empty objects.

This prevents generated clients from distinguishing valid current response fields from unknown provider drift.

Versioned-spec history

• VariableWidthStrokesTrait and ComplexStrokesTrait were introduced as properties: {} in commit 5112a5c0af0714b8bbe1711f9d90df980ebb9835 / release 0.35.0.
• They remain empty in tagged 0.44.0 (1c15f007cc81b4409efb2f24fec89608e8a7548d).
• AnnotationsTrait was introduced as empty in commit cdc430d4bcfaec9ea7a6b031030912d37844daef; PR update to 0.20.0: deletedButReferenced, backfill of annotations/measurements #26 says annotations were already in the public API but had not been added to the spec.

Current-doc conflicts

The current Node types page publishes on VECTOR:

• variableWidthPoints: VariableWidthPoint[], displayed default [];
• complexStrokeProperties: ComplexStrokeProperties, displayed default {};
• individualStrokeWeights: StrokeWeights; and
• annotations: Annotation[], displayed default [].

It says BOOLEAN_OPERATION inherits all VECTOR properties except annotations, and STAR, LINE, ELLIPSE, REGULAR_POLYGON, and RECTANGLE inherit VECTOR properties.

The current Property types page defines the complex-stroke discriminator as strokeType. However, the Node types page shows {} for VECTOR and {"type":"BASIC"} for SECTION, so neither displayed default conforms to strokeType: "BASIC".

The versioned spec also applies IndividualStrokesTrait only to RECTANGLE and applies CornerTrait to VECTOR, STAR, REGULAR_POLYGON, and RECTANGLE, while the current Node types inheritance implies different applicability.

Clarifications requested

Could you please update the versioned OpenAPI and/or REST docs to establish:

1. the exact complexStrokeProperties wire discriminator and conforming basic-stroke representation;
2. whether complexStrokeProperties, variableWidthPoints, and annotations are always present, optional, or conditional in REST responses;
3. the required fields for every Basic, Dynamic, Scatter, and Stretch complex-stroke variant;
4. exact node-type applicability for both stroke fields, individualStrokeWeights, annotations, and corner fields; and
5. whether the VECTOR property list is exhaustive for current REST response roots.

The relevant official pages are:

• https://developers.figma.com/docs/rest-api/file-node-types/
• https://developers.figma.com/docs/rest-api/file-property-types/
• https://developers.figma.com/docs/rest-api/changelog/

No Plugin API behavior is being assumed here; the request concerns REST response JSON and the REST OpenAPI package.