feat(API): add key format annotations list endpoint #STRINGS-3028 by phrase-bot · Pull Request #1222 · phrase/strings-openapi

Phrase (phrase-bot) · 2026-07-23T06:54:22Z

This PR was generated by the openapi-apply agent in response to a
/openapi-sync apply request on
Phrase-Engineering/strings-app#18256.

What changed in the API

GET /api/v2/projects/{project_id}/keys/{id}/format_annotations — new endpoint added. Returns an array of format annotations stored directly on a translation key (file format name and original representation), ordered by insertion order, capped at 1,000 entries. Requires the read OAuth scope.

Source

Originating strings-app PR: Phrase-Engineering/strings-app#18256
Applied by: Franca Winter (@francawinter)

Notes for reviewers

swagger-cli validate main.yaml passed cleanly with no warnings.
The Key Format Annotations tag was added to main.yaml and wired into the Core Resources x-tagGroups section (immediately after Keys). If a different grouping is preferred, adjust x-tagGroups in main.yaml before merging.
The path operation file omits the security: block that appeared in the proposal — the scheme names (basicAuthentication, oAuth2) do not match the repo's security schemes (Token, Basic), and security is inherited from the root level, consistent with all other key-scoped operations.
x-cli-version: "2.5" is included as proposed; confirm whether this endpoint should have a different CLI version or none at all.

Opened automatically by the openapi-apply agent. Review the spec changes
against the linked strings-app PR; the agent does not vouch for correctness
beyond "the YAML parsed and the documented layout was followed."

Will look like this:

github-actions · 2026-07-23T06:55:09Z

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

1 changes: 0 error, 0 warning, 1 info
info	[endpoint-added] at doc/compiled.json
	in API GET /projects/{project_id}/keys/{id}/format_annotations
		endpoint added

Regenerate doc/compiled.json so compare-output passes. Remove the `enum` constraint from `cldr_version` in the ICU skeleton endpoint to work around a typescript-fetch generator bug where inline enums inside inline request body schemas produce a reference to an undefined type (IcuSkeletonParametersCldrVersionEnum). Valid values are documented in the field description; server-side validation is unchanged. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Restore `cldr_version` enum values (removed in previous commit, which oasdiff flagged as breaking). Change the inline request body schema title from `icu/skeleton/parameters` to `icu_skeleton_parameters` so the TypeScript-fetch generator can correctly derive and emit the enum type declaration (the slash-based title caused the generator to reference IcuSkeletonParametersCldrVersionEnum without emitting its definition). Regenerate compiled.json with the project-installed swagger-cli to match CI output exactly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…build The TypeScript-fetch generator fails to emit the enum declaration for inline string enums inside inline request body schemas that also use oneOf (a known generator bug). Moving cldr_version to a named component schema (icu_skeleton_cldr_version) gives the generator a proper named type, which it handles correctly. Enum values are unchanged so oasdiff does not flag a breaking change. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new key-scoped endpoint to list “format annotations” stored directly on a translation key, and wires the new schema/tag into the OpenAPI components and generated docs. It also refactors the ICU skeleton endpoint to reuse a shared schema for cldr_version.

Changes:

Added GET /projects/{project_id}/keys/{id}/format_annotations returning an array of format_annotation.
Introduced format_annotation schema and registered it in schemas.yaml.
Extracted ICU skeleton cldr_version into a reusable skeleton_cldr_version schema (and updated the ICU skeleton path to $ref it).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
schemas/icu.yaml	Adds reusable `skeleton_cldr_version` enum schema for ICU skeleton construction.
schemas/format_annotation.yaml	Introduces new `format_annotation` object schema.
schemas.yaml	Registers new schemas (`icu_skeleton_cldr_version`, `format_annotation`) in components.
paths/key_format_annotations/index.yaml	Defines the new “list format annotations for a key” operation.
paths/icu/skeleton.yaml	Updates request schema title and reuses the new `skeleton_cldr_version` schema via `$ref`.
paths.yaml	Adds the new `/projects/{project_id}/keys/{id}/format_annotations` route entry.
main.yaml	Adds the new tag and includes it in `x-tagGroups`.
doc/compiled.json	Updates compiled OpenAPI output to reflect the spec changes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Revert ICU skeleton schema title to icu/skeleton/parameters — consistent with all other request body schemas in the repo; the title change was an intermediate attempt that is no longer needed. Add missing pieces to the format annotations endpoint: - Rate-limit headers on the 200 response - 400 response - Scoped 403 description noting the required read scope Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Sönke Behrendt (theSoenke) · 2026-07-23T09:10:28Z

+skeleton_cldr_version:
+  type: string
+  description: >-
+    Pluralization rule set to apply when constructing skeletons.
+    Accepted values are `legacy` and `cldr_41`. Defaults to
+    `legacy` when omitted.
+  enum:
+    - legacy
+    - cldr_41
+  example: cldr_41


Franca Winter (@francawinter) where is this from? 👀

claude: Added by us to fix a pre-existing TypeScript CI failure. Moved to separate PR: #1223

Sönke Behrendt (theSoenke) · 2026-07-23T09:10:48Z

+  icu_skeleton_cldr_version:
+    "$ref": schemas/icu.yaml#/skeleton_cldr_version


this should be unrelated

claude: Agreed, unrelated to the new endpoint. Moved to separate PR #1223

Sönke Behrendt (theSoenke) · 2026-07-23T09:12:45Z

+  Only annotations stored directly on the key are returned. Annotations stored on the
+  key's translations (per locale) are excluded.
+
+  Results are ordered by insertion order (ascending by internal ID) and capped at 1,000
+  entries. When a key has more than 1,000 stored annotations, only the first 1,000 are
+  returned without an error or any indication that the list was truncated.


Franca Winter (@francawinter) i think this should be rephrased a bit. to remove the translations part, the order and error part

claude: Fixed in 607b55e — removed the translations/per-locale note, the ordering detail, and the truncation wording. Description is now two sentences.

Sönke Behrendt (theSoenke) · 2026-07-23T09:13:33Z

+        The public file format name that produced this annotation. Possible values include
+        `arb`, `xliff_2`, `xlf`, `xml`, `ts`, and `strings_catalog`. Internal-only format
+        variants (such as `xliff_jobsync`) are never returned; they are collapsed to their
+        public equivalent (for example, `xliff_jobsync` is reported as `xliff_2`).


i don't think we should document specific formats here. this can get quickly out of date

claude: Fixed in 6fd5dcf — removed the format list entirely.

Sönke Behrendt (theSoenke) · 2026-07-23T09:14:27Z

+        The original file-format snippet captured when the key was imported, returned
+        byte-for-byte without transformation, reformatting, or additional escaping.
+        May contain multi-line content.


feels a bit overly verbose and byte-for-byte seems a odd way to say we return the original representation

claude: Fixed in 607b55e — changed to "Returned as-is, may contain multi-line content."

Rewrite endpoint and schema descriptions to match existing style: shorter sentences, no internal implementation detail, plain English. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The TypeScript generator fix for the icu/skeleton endpoint is unrelated to the format annotations endpoint. Extracted to its own PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…app-pr-18256

feat(API): add key format annotations list endpoint #STRINGS-3028

c1b7a84

Franca Winter (francawinter) marked this pull request as draft July 23, 2026 06:57

Franca Winter (francawinter) and others added 4 commits July 23, 2026 09:14

chore: trigger PR CI re-run

7903b2c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Franca Winter (francawinter) marked this pull request as ready for review July 23, 2026 08:21

Franca Winter (francawinter) requested review from Copilot and Sönke Behrendt (theSoenke) July 23, 2026 08:21

Copilot started reviewing on behalf of Franca Winter (francawinter) July 23, 2026 08:32 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread paths/icu/skeleton.yaml

Comment thread paths/key_format_annotations/index.yaml

Sönke Behrendt (theSoenke) reviewed Jul 23, 2026

View reviewed changes

Franca Winter (francawinter) marked this pull request as draft July 23, 2026 09:26

Franca Winter (francawinter) and others added 4 commits July 23, 2026 11:29

docs(API): simplify format annotations descriptions

607b55e

Rewrite endpoint and schema descriptions to match existing style: shorter sentences, no internal implementation detail, plain English. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(API): use xliff_2 note as example for format annotations

8e3c006

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(API): remove specific format list from file_format description

6fd5dcf

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: move ICU cldr_version fix to separate PR #1223

9401982

The TypeScript generator fix for the icu/skeleton endpoint is unrelated to the format annotations endpoint. Extracted to its own PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Franca Winter (francawinter) marked this pull request as ready for review July 23, 2026 10:03

Franca Winter (francawinter) requested a review from Sönke Behrendt (theSoenke) July 23, 2026 10:03

Merge remote-tracking branch 'origin/main' into openapi-sync/strings-…

7ccb7a7

…app-pr-18256

Franca Winter (francawinter) marked this pull request as draft July 23, 2026 11:57

Franca Winter (francawinter) self-assigned this Jul 23, 2026

Franca Winter (francawinter) marked this pull request as ready for review July 23, 2026 11:59

Sönke Behrendt (theSoenke) approved these changes Jul 23, 2026

View reviewed changes

Franca Winter (francawinter) merged commit c43cc32 into main Jul 23, 2026
13 checks passed

Franca Winter (francawinter) deleted the openapi-sync/strings-app-pr-18256 branch July 23, 2026 12:08

		icu_skeleton_cldr_version:
		"$ref": schemas/icu.yaml#/skeleton_cldr_version

Uh oh!

Conversation

Phrase (phrase-bot) commented Jul 23, 2026 • edited by francawinter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed in the API

Source

Notes for reviewers

Will look like this:

Uh oh!

github-actions Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API changelog (oasdiff)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Franca Winter (francawinter) Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Franca Winter (francawinter) Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Phrase (phrase-bot) commented Jul 23, 2026 •

edited by francawinter

Loading

github-actions Bot commented Jul 23, 2026 •

edited

Loading

Franca Winter (francawinter) Jul 23, 2026 •

edited

Loading

Franca Winter (francawinter) Jul 23, 2026 •

edited

Loading