177 lines
6.3 KiB
YAML
177 lines
6.3 KiB
YAML
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' |