[Feature in REST-API]: add additional information to OA schema

[mesilov]

Description

We need additional information in OA schema to implement deterministic codegeneration.

Current baseline

• SDK already contains the CLI tool b24-dev:build-schema for generating the current OpenAPI schema from the REST 3.0 documentation endpoint.
• The repository exposes this through make oa-schema-build.
• The generated schema snapshot is stored in docs/open-api/openapi.json and is treated as the repository baseline for research, implementation, and release-time verification.

OpenAPI specification extension mechanism

The standard way to extend OpenAPI with vendor-specific metadata is to use Specification Extensions, that is, custom fields whose names start with x-.

For this task, this means that additional metadata required for deterministic SDK code generation can be added to the OA schema without breaking OpenAPI compatibility, as long as it is expressed through project-specific extension fields such as x-b24-*.

Important notes:

• extension property names must start with x-
• extension values may be primitives, objects, arrays, or null
• support for these attributes depends on the downstream tooling: OpenAPI allows them, but generators/validators may ignore unknown extensions unless they are explicitly handled
• prefixes x-oai- and x-oas- are reserved by the OpenAPI Initiative and should not be used for project-specific metadata
• for this SDK, the preferred namespace should be project-local, for example x-b24-*

Example:

paths:
  /tasks:
    get:
      operationId: getTasks
      x-b24-sdk-service: Task
      x-b24-sdk-method: list
      x-b24-api-version: v3

Relevant documentation

• OpenAPI Specification 3.1, Specification Extensions:
  https://spec.openapis.org/oas/v3.1.0#specification-extensions
• OpenAPI Specification 3.1:
  https://spec.openapis.org/oas/v3.1.0
• Swagger docs: OpenAPI Extensions:
  https://swagger.io/docs/specification/v3_0/openapi-extensions/
• OpenAPI Initiative publications and registries:
  https://spec.openapis.org/

Current OA snapshot already contains structural entity metadata

The current checked-in OA schema already contains structural metadata for entities in components.schemas, even before any project-specific x-b24-* extensions are added.

For example, the Task entity schema currently stores standard OpenAPI properties such as:

• type
• format
• title

A fragment from the current OA schema for Task fields:

{
  "id": {
    "type": "integer",
    "format": "int64",
    "title": "id"
  },
  "title": {
    "type": "string",
    "title": "title"
  },
  "created": {
    "type": "string",
    "format": "date-time",
    "title": "created"
  },
  "deadline": {
    "type": "string",
    "format": "date-time",
    "title": "deadline"
  },
  "needsControl": {
    "type": "boolean",
    "title": "needsControl"
  }
}

So the gap is not that OA contains no entity-field metadata at all, but that it does not yet contain the additional deterministic SDK/codegen metadata we want to add.

Example

No response