TCM-6557 Update Strings API and add common schemas to api_common.yaml

CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+OpenAPI 3.0 specification for the Smartling REST API, published at https://api-reference.smartling.com/. The spec is split across multiple YAML files under `spec/` and bundled at build time into a single `swagger.json`/`swagger.yaml` for rendering via ReDoc/Swagger UI.
+
+## Commands
+
+```bash
+npm install          # install dependencies (Node 17+ required)
+npm start            # build, start local server + swagger-editor (live reload)
+npm test             # validate the OpenAPI spec (swagger-repo validate)
+npm run build        # bundle spec into web_deploy/
+npm run process-yaml # re-generate TQC x-paths (required after editing TQC YAML files)
+```
+
+The local server URL is printed to console on startup. The swagger-editor URL is also printed separately (port 5000+).
+
+## Spec structure
+
+- `spec/openapi.yaml` - root file: server, global tags (with long descriptions), and `$ref` paths to all sub-specs
+- `spec/api_common.yaml` - shared reusable components: parameters (`accountUid`, `projectId`, `localeId`), request bodies, and common schemas (`SuccessResponse`, `EmptyResponse`, etc.)
+- Each API domain lives in its own subdirectory:
+  - `spec/translation_quality/` - TQC endpoints split across many files; uses `x-paths` extension and requires `npm run process-yaml` after edits
+  - `spec/issues/` - Issues, issue comments, watchers, dictionaries, sub-types
+  - `spec/job_batches_v1/` and `spec/job_batches_v2/` - Job batch endpoints
+  - `spec/glossary_v3/` - Glossary, blocklist, import/export, labels, entries
+  - `spec/webhooks_api/` - Webhook subscriptions, events, components
+  - `spec/file_translation/` - File MT upload, MT, language detection
+  - `spec/strings/` - Strings API v2 (uses `x-paths` extension)
+  - `spec/connectors_import_v3/` - Connectors Import API
+
+## Key conventions
+
+**Global headers**: The `headers:` top-level key (non-standard) is supported - references like `$ref: "#/headers/Rate-Limit-Limit"` are inlined and the `headers` block is removed during build so the output remains valid OpenAPI.
+
+**x-paths extension**: `spec/translation_quality/` and `spec/strings/` use a custom `x-paths` key (not the standard `paths`) with `$ref` includes. Running `npm run process-yaml` resolves these refs and merges them into `spec/openapi.yaml`. Always run this after editing TQC or Strings YAML files.
+
+**Build output**: `npm run build` produces `web_deploy/` containing the bundled spec (`swagger.json`, `swagger.yaml`), the static web UI, and copies of all spec subdirectories.
+
+## CI/CD
+
+- Jenkins builds on every branch; non-master branches deploy a preview - the URL depends on whether a PR is open:
+  - No PR open: `https://api-reference.smartling.com/preview/<branch-name-lowercase>`
+  - PR open: `https://api-reference.smartling.com/preview/pr-<number>` (Jenkins uses the PR ref as `BRANCH_NAME`)
+- `master` deploys to the main documentation site
+- Preview branches are not auto-cleaned; stale previews must be cleaned manually via the `gh-pages` branch (see README.md)

README.md

@@ -7,8 +7,9 @@
 - Look full spec:
     + JSON https://api-reference.smartling.com/swagger.json
     + YAML https://api-reference.smartling.com/swagger.yaml
-- Preview spec version for branch `<branch>`: https://api-reference.smartling.com/preview/<branch>
-  (Note: use lower case name in the url for the branch)
+- Preview spec version:
+  - By branch name (before opening a PR): https://api-reference.smartling.com/preview/<branch-name-lowercase>
+  - By PR number (after opening a PR): https://api-reference.smartling.com/preview/pr-<number>
 
 **Warning:** All above links are updated only after Jenkins finishes deployment
 

scripts/deploy-branch.js

@@ -23,6 +23,7 @@ if (branch && branch !== 'gh-pages') {
   cp('-R', 'spec/connectors_import_v3', specFolder);
   cp('-R', 'spec/glossary_v3', specFolder);
   cp('-R', 'spec/webhooks_api', specFolder);
+  cp('-R', 'spec/strings', specFolder);
   cp('-R', 'spec/api_common.yaml', specFolder);
 
   exec('deploy-to-gh-pages --update .tmp');

spec/api_common.yaml

@@ -11,15 +11,49 @@ components:
         name: projectId
         in: path
         required: true
-        type: string
         description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
+        schema:
+          type: string
+          pattern: '^[a-z0-9]{9}$'
+        examples:
+          typical:
+            summary: Typical project ID
+            value: abcd12345
 
       localeId:
         name: localeId
         in: path
         required: true
-        type: string
-        description: A valid Smartling Locale ID.
+        description: |
+          Locale identifier. Either a 2-letter language code (`en`) or a
+          language-region pair (`en-US`). The language part is always lowercase;
+          the region part is always uppercase.
+        schema:
+          $ref: '#/components/schemas/LocaleId'
+        examples:
+          language_only:
+            summary: Language code only
+            value: en
+          language_region:
+            summary: Language and region
+            value: fr-FR
+
+      offset:
+        name: offset
+        in: query
+        description: Number of items to skip. Default is 0.
+        schema:
+          type: integer
+          minimum: 0
+          default: 0
+
+      limit:
+        name: limit
+        in: query
+        description: Maximum number of items to return per page.
+        schema:
+          type: integer
+          minimum: 1
 
   requestBodies:
 
@@ -41,6 +75,56 @@ components:
 
   schemas:
 
+    DateTime:
+      type: string
+      format: date-time
+      description: ISO 8601 UTC timestamp.
+      examples:
+        - "2026-01-15T10:00:00Z"
+
+    FileUri:
+      type: string
+      description: URI path of a source file within a Smartling project.
+      examples:
+        - /content/en/home.json
+
+    LocaleId:
+      type: string
+      pattern: '^[a-z]{2}(-[A-Z]{2})?$'
+      description: |
+        Locale identifier. Either a 2-letter language code (`en`) or a
+        language-region pair (`en-US`). The language part is always lowercase;
+        the region part is always uppercase.
+      example: fr-FR
+
+    Hashcode:
+      type: string
+      description: MD5 hash digest — 32 lowercase hexadecimal characters.
+      pattern: '^[a-f0-9]{32}$'
+      examples:
+        - d41d8cd98f00b204e9800998ecf8427e
+
+    TranslationJobUid:
+      type: string
+      description: Translation job unique identifier — 12 lowercase alphanumeric characters.
+      pattern: '^[a-z0-9]{12}$'
+      examples:
+        - j45v1uvsi3tx
+
+    WorkflowUid:
+      type: string
+      description: Workflow unique identifier — 12 lowercase alphanumeric characters.
+      pattern: '^[a-z0-9]{12}$'
+      examples:
+        - 5449a8595ae4
+
+    WorkflowStepUid:
+      type: string
+      description: Workflow step unique identifier — 12 lowercase alphanumeric characters.
+      pattern: '^[a-z0-9]{12}$'
+      examples:
+        - 7564fc097a85
+
     SuccessResponse:
       type: object
       required: