openapi: 3.1.0
info:
  title: Platform Localization Logical Contract
  version: 0.1.0
  summary: Logical contract for locale resolution, preference persistence, and invariant machine-format behavior.
paths:
  /localization/context:
    get:
      summary: Resolve the effective locale for the current request.
      operationId: resolveLocalizationContext
      description: Admin and tenant planes may resolve from explicit override, user preference, workspace default, or system default. The system plane resolves from explicit override or system default only in v1.
      responses:
        '200':
          description: Effective locale context for the current request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedLocaleContext'
  /localization/override:
    put:
      summary: Set or replace the explicit temporary locale override that sits first in the precedence chain.
      operationId: updateExplicitLocaleOverride
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocaleOverrideUpdate'
      responses:
        '200':
          description: Updated locale context after setting the override.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedLocaleContext'
        '400':
          description: Unsupported or malformed locale input was rejected and the request falls back safely.
    delete:
      summary: Clear the explicit temporary locale override and return to inherited behavior.
      operationId: clearExplicitLocaleOverride
      responses:
        '204':
          description: Explicit override cleared.
  /users/me/locale-preference:
    put:
      summary: Persist the authenticated user's personal locale preference.
      operationId: updateUserLocalePreference
      description: Applies to the workspace-bound `User` actor on admin and tenant planes only. System-panel `PlatformUser` actors do not get a persisted locale preference in v1.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLocalePreferenceUpdate'
      responses:
        '200':
          description: Updated locale context after saving the preference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedLocaleContext'
        '400':
          description: Unsupported or malformed locale input was rejected and the request falls back safely.
        '403':
          description: Caller is authenticated but the current surface or policy does not allow personal locale preference mutation.
        '404':
          description: The personal preference path is unavailable in the current plane or membership context, including system-panel requests.
  /workspaces/{workspaceId}/settings/localization/default-locale:
    put:
      summary: Persist the workspace-owned default locale through the existing settings surface.
      operationId: updateWorkspaceDefaultLocale
      description: Applies to workspace-scoped admin and tenant flows only. The system plane does not inherit workspace default in v1.
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceDefaultLocaleUpdate'
      responses:
        '200':
          description: Updated workspace default locale metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceLocaleSetting'
        '400':
          description: Unsupported or malformed locale input was rejected.
        '403':
          description: Caller is a workspace member but lacks permission to manage workspace settings.
        '404':
          description: Workspace is inaccessible in the current plane or membership context.
components:
  schemas:
    SupportedLocale:
      type: string
      enum:
        - en
        - de
    LocaleSource:
      type: string
      enum:
        - explicit_override
        - user_preference
        - workspace_default
        - system_default
    ResolvedLocaleContext:
      type: object
      required:
        - locale
        - source
        - fallback_locale
        - machine_artifacts_invariant
      properties:
        locale:
          $ref: '#/components/schemas/SupportedLocale'
        source:
          $ref: '#/components/schemas/LocaleSource'
        fallback_locale:
          type: string
          const: en
        user_preference_locale:
          anyOf:
            - $ref: '#/components/schemas/SupportedLocale'
            - type: 'null'
        workspace_default_locale:
          anyOf:
            - $ref: '#/components/schemas/SupportedLocale'
            - type: 'null'
        machine_artifacts_invariant:
          type: boolean
          const: true
    UserLocalePreferenceUpdate:
      type: object
      required:
        - preferred_locale
      properties:
        preferred_locale:
          anyOf:
            - $ref: '#/components/schemas/SupportedLocale'
            - type: 'null'
      description: Null clears the personal preference and returns the user to inherited behavior.
    LocaleOverrideUpdate:
      type: object
      required:
        - override_locale
      properties:
        override_locale:
          $ref: '#/components/schemas/SupportedLocale'
      description: Sets the explicit temporary override that takes precedence over persisted preference and workspace default.
    WorkspaceDefaultLocaleUpdate:
      type: object
      required:
        - default_locale
      properties:
        default_locale:
          anyOf:
            - $ref: '#/components/schemas/SupportedLocale'
            - type: 'null'
      description: Null returns the workspace to system-default inheritance.
    WorkspaceLocaleSetting:
      type: object
      required:
        - workspace_id
        - default_locale
      properties:
        workspace_id:
          type: integer
        default_locale:
          anyOf:
            - $ref: '#/components/schemas/SupportedLocale'
            - type: 'null'