From 92ab394d9447b06685c0733cb2a36b35c32b5061 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artych=20Rafa=C5=82?= Date: Mon, 6 Jul 2026 11:04:35 +0200 Subject: [PATCH 1/6] Add Annex B content --- documentation/CAMARA-API-Design-Guide.md | 254 +++++++++++++++++++---- 1 file changed, 216 insertions(+), 38 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 6861fecf..bfeac37b 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -5,44 +5,101 @@ This document outlines guidelines for API design within the CAMARA project, appl -- [1. Introduction](#1-introduction) - - [1.1. Conventions](#11-conventions) - - [1.2. Common Vocabulary and Acronyms](#12-common-vocabulary-and-acronyms) -- [2. Data](#2-data) - - [2.1. Common Data Types](#21-common-data-types) - - [2.2. Data Definitions](#22-data-definitions) - - [2.3. Strictness of Request Body Schemas](#23-strictness-of-request-body-schemas) -- [3. Responses](#3-responses) - - [3.1. Business-level Outcomes in Successful Responses](#31-business-level-outcomes-in-successful-responses) - - [3.2. Error Responses](#32-error-responses) -- [4. Pagination, Sorting and Filtering](#4-pagination-sorting-and-filtering) - - [4.1. Pagination](#41-pagination) - - [4.2. Sorting](#42-sorting) - - [4.3. Filtering](#43-filtering) -- [5. OpenAPI Sections](#5-openapi-sections) - - [5.1. Reserved Words](#51-reserved-words) - - [5.2. OpenAPI Version](#52-openapi-version) - - [5.3. Info Object](#53-info-object) - - [5.4. ExternalDocs Object](#54-externaldocs-object) - - [5.5. Servers Object](#55-servers-object) - - [5.6. Tags](#56-tags) - - [5.7. Paths and Operations](#57-paths-and-operations) - - [5.8. Components](#58-components) -- [6. Security](#6-security) - - [6.1. Good Practices for Securing REST APIs](#61-good-practices-for-securing-rest-apis) - - [6.2. Security Definition](#62-security-definition) - - [6.3. Expressing Security Requirements](#63-expressing-security-requirements) - - [6.4. Mandatory Template for `info.description` in CAMARA API](#64-mandatory-template-for-infodescription-in-camara-api) - - [6.5. POST or GET for Transferring Sensitive or Complex Data](#65-post-or-get-for-transferring-sensitive-or-complex-data) - - [6.6. Scope Naming](#66-scope-naming) - - [6.7. Resource Access Restriction](#67-resource-access-restriction) -- [7. Versioning](#7-versioning) - - [7.1. API Version (OAS `info` Object)](#71-api-version-oas-info-object) - - [7.2. API Version in URL (OAS `servers` Object)](#72-api-version-in-url-oas-servers-object) - - [7.3. API Versions Throughout the Release Process](#73-api-versions-throughout-the-release-process) - - [7.4. Backward and Forward Compatibility](#74-backward-and-forward-compatibility) -- [8. External Documentation](#8-external-documentation) -- [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) +- [CAMARA API Design Guide](#camara-api-design-guide) + - [1. Introduction](#1-introduction) + - [1.1. Conventions](#11-conventions) + - [1.2. Common Vocabulary and Acronyms](#12-common-vocabulary-and-acronyms) + - [2. Data](#2-data) + - [2.1. Common Data Types](#21-common-data-types) + - [2.2. Data Definitions](#22-data-definitions) + - [2.2.1. Usage of Discriminator](#221-usage-of-discriminator) + - [Inheritance](#inheritance) + - [Polymorphism](#polymorphism) + - [2.3. Strictness of Request Body Schemas](#23-strictness-of-request-body-schemas) + - [3. Responses](#3-responses) + - [3.1. Business-level Outcomes in Successful Responses](#31-business-level-outcomes-in-successful-responses) + - [3.1.1. Scope and Problem Statement](#311-scope-and-problem-statement) + - [3.1.2. Core Principles](#312-core-principles) + - [3.1.3. Recommended Modeling Pattern](#313-recommended-modeling-pattern) + - [3.1.4. Example](#314-example) + - [3.1.5. Versioning and Migration Guidance](#315-versioning-and-migration-guidance) + - [3.2. Error Responses](#32-error-responses) + - [3.2.1. Standardized Use of CAMARA Error Responses](#321-standardized-use-of-camara-error-responses) + - [3.2.2. Error Responses - Device Object/Phone Number](#322-error-responses---device-objectphone-number) + - [3.2.2.1. Templates](#3221-templates) + - [Response template](#response-template) + - [Examples template](#examples-template) + - [3.2.3. Error Responses - Mandatory Template for `info.description` in CAMARA API](#323-error-responses---mandatory-template-for-infodescription-in-camara-api) + - [3.2.4. Request Body Strictness - Mandatory Template for `info.description` in CAMARA API](#324-request-body-strictness---mandatory-template-for-infodescription-in-camara-api) + - [4. Pagination, Sorting and Filtering](#4-pagination-sorting-and-filtering) + - [4.1. Pagination](#41-pagination) + - [4.1.1. Query Parameters](#411-query-parameters) + - [4.1.2. Request Headers](#412-request-headers) + - [4.1.3. Response Body](#413-response-body) + - [4.1.4. Response Headers](#414-response-headers) + - [4.1.5 HTTP Status Codes](#415-http-status-codes) + - [4.2. Sorting](#42-sorting) + - [4.3. Filtering](#43-filtering) + - [4.3.1. Filtering Security Considerations](#431-filtering-security-considerations) + - [4.3.2. Filtering Operations](#432-filtering-operations) + - [5. OpenAPI Sections](#5-openapi-sections) + - [5.1. Reserved Words](#51-reserved-words) + - [5.2. OpenAPI Version](#52-openapi-version) + - [5.3. Info Object](#53-info-object) + - [5.3.1. Title](#531-title) + - [5.3.2. Description](#532-description) + - [5.3.3. Version](#533-version) + - [5.3.4. Terms of Service](#534-terms-of-service) + - [5.3.5. Contact Information](#535-contact-information) + - [5.3.6. License](#536-license) + - [5.3.7. Extension Field](#537-extension-field) + - [5.4. ExternalDocs Object](#54-externaldocs-object) + - [5.5. Servers Object](#55-servers-object) + - [5.5.1. api-name](#551-api-name) + - [5.5.2. api-version](#552-api-version) + - [5.6. Tags](#56-tags) + - [5.7. Paths and Operations](#57-paths-and-operations) + - [5.7.1. Paths](#571-paths) + - [Resource hierarchy](#resource-hierarchy) + - [5.7.2. Operations](#572-operations) + - [5.7.3. Tags](#573-tags) + - [5.7.4. Parameters](#574-parameters) + - [5.7.5. Request Bodies](#575-request-bodies) + - [5.7.6. Responses](#576-responses) + - [5.7.6.1 Asynchronous responses](#5761-asynchronous-responses) + - [5.8. Components](#58-components) + - [5.8.1. Schemas](#581-schemas) + - [5.8.2. Responses](#582-responses) + - [5.8.3. Parameters](#583-parameters) + - [5.8.4. Request Bodies](#584-request-bodies) + - [5.8.5. Headers](#585-headers) + - [x-correlator Header](#x-correlator-header) + - [Pagination Headers](#pagination-headers) + - [Content-Type Header - clarification](#content-type-header---clarification) + - [5.8.6. Security Schemes](#586-security-schemes) + - [6. Security](#6-security) + - [6.1. Good Practices for Securing REST APIs](#61-good-practices-for-securing-rest-apis) + - [6.2. Security Definition](#62-security-definition) + - [6.3. Expressing Security Requirements](#63-expressing-security-requirements) + - [6.4. Mandatory Template for `info.description` in CAMARA API](#64-mandatory-template-for-infodescription-in-camara-api) + - [6.5. POST or GET for Transferring Sensitive or Complex Data](#65-post-or-get-for-transferring-sensitive-or-complex-data) + - [6.6. Scope Naming](#66-scope-naming) + - [6.6.1. APIs Which Do Not Deal with Explicit Subscriptions](#661-apis-which-do-not-deal-with-explicit-subscriptions) + - [Examples](#examples) + - [6.6.2. API-level Scopes (Sometimes Referred to as Wildcard Scopes in CAMARA)](#662-api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) + - [6.7. Resource Access Restriction](#67-resource-access-restriction) + - [7. Versioning](#7-versioning) + - [7.1. API Version (OAS `info` Object)](#71-api-version-oas-info-object) + - [7.2. API Version in URL (OAS `servers` Object)](#72-api-version-in-url-oas-servers-object) + - [7.3. API Versions Throughout the Release Process](#73-api-versions-throughout-the-release-process) + - [7.4. Backward and Forward Compatibility](#74-backward-and-forward-compatibility) + - [8. External Documentation](#8-external-documentation) + - [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) + - [Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness](#appendix-b-informative-operationid-and-description-guidelines-for-mcp-and-ai-agent-readiness) + - [B.1. `operationId` Naming Rules](#b1-operationid-naming-rules) + - [Proposal: Approved Verb List](#proposal-approved-verb-list) + - [B.2. Operation `description` Completeness Rules](#b2-operation-description-completeness-rules) + - [B.3. Property `description` Completeness Rules](#b3-property-description-completeness-rules) @@ -1580,3 +1637,124 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` +You're right — if it's still feeling too short, then we’ve likely crossed into **over-concision**, sacrificing too much of the **design guidance**, **context**, and **educational value** that makes this appendix useful as a *standard*, not just a machine-readable checklist. + +The goal isn’t minimalism — it’s **clarity, usability, and enforceability** without unnecessary verbosity. + +Below is a **refined, balanced version** that: +- Retains all **key rules, examples, and intent**, +- Keeps helpful **explanations and boundaries** (e.g., *why* a rule exists, *what* it prevents), +- Removes only **redundant phrasing, obvious filler, and excessive whitespace**, +- Flows naturally for a designer reading it to understand and apply the guidance, +- Is **approximately 70–75% the length** of the original — substantive, but not bloated. + + +## Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness + +This appendix is the outcome of the CAMARA MCP Enablement Program – Phase 0. It extends the naming and documentation rules in [5.7.2](#572-operations) and [2.2](#22-data-definitions) with additional, targeted constraints to ensure CAMARA API operations can be reliably selected and invoked by automated consumers, including AI agents and **Model Context Protocol (MCP)** tool-selection pipelines. These consumers rely on the operation object itself — not the top-level `info.description` — to understand what an operation does, when to use it, and how to invoke it correctly. + +### B.1. `operationId` Naming Rules + +While [5.7.2](#572-operations) requires `operationId` to use lowerCamelCase when present, it does not mandate its presence. Since `operationId` is frequently used by tooling and automated systems as the primary handle to select and invoke an operation — and an operation without one generally cannot be used by such consumers — the following rules apply, beginning with an explicit presence requirement: + +- `operationId` **MUST be present** on every operation. +- `operationId` **MUST be in lowerCamelCase format** and **MUST NOT exceed 64 characters in length**. This ensures compatibility with most code generators and vendor tooling limits. (These requirements are formally expressed by the regular expression: `^[a-z][a-zA-Z0-9]{0,63}$`.) +- `operationId` **MUST follow the shape** `[]`, for example: + - `createSession` (verb + noun) + - `getDeviceLocation` (verb + compound noun) + - `deleteSessionById` (verb + noun + qualifier) + + The `` represents the core resource, entity, or concept being acted upon — and MAY be a compound noun (e.g., `DeviceLocation`, `UserProfile`) formed from multiple domain terms. + + The `` is optional and, when used, **MUST serve only to disambiguate** two operations that would otherwise share the same ``. When the qualifier disambiguates on an identifying parameter, it **SHOULD take the form** `By` (e.g., `deleteSessionById`). Otherwise, it **SHOULD be a single PascalCase noun or short noun phrase** appended directly to ``. +- `operationId` **MUST NOT be prefixed** with the HTTP method name, with the exception of `get` when used as an ordinary English verb. + This avoids duplicating information already present in the OpenAPI `path`/`method` pair and adds no disambiguation value for automated selection. +- `operationId` **MUST NOT include a version marker** such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. +- Within a single API document, designers **SHOULD use one consistent read verb** (e.g., always `get` rather than alternating between `get`, `retrieve`, and `fetch`) to promote clarity and reduce cognitive load for consumers. +- `operationId` **SHOULD be unique** within the document to prevent collisions in code generation, tool registries, and AI agent tool-calling systems. + +#### Proposal: Approved Verb List + +Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on this list **MUST** undergo a formal review process before use. + +**CRUD Core Verbs** (replace vague synonyms): +- `create` — Instantiate a new resource. Replaces: `add`, `new`, `insert`, `post`. +- `get` — Fetch a single resource by identity. Replaces: `fetch`, `retrieve`, `read`, `find`. +- `list` — Fetch a collection, optionally filtered. Replaces: `getAll`, `fetchAll`, `search` (when browsing). +- `update` — Modify an existing resource, fully or partially. Replaces: `edit`, `modify`, `patch`, `put`. +- `replace` — Full replacement of a resource (PUT semantics). Replaces: `put`, `overwrite`. +- `delete` — Remove a resource permanently. Replaces: `remove`, `destroy`, `drop`. + +**Action Verbs** (for non-CRUD operations): +- `send` — Dispatch a message, notification, or payload. +- `submit` — Hand off for processing (e.g., forms, orders, applications). +- `approve` — Grant explicit authorization. +- `cancel` — Abort an in-progress or future operation. +- `publish` — Make a resource publicly available. +- `archive` — Move to long-term / read-only storage. +- `restore` — Reverse an archive or soft delete. +- `enable` / `disable` — Toggle active state. +- `activate` / `deactivate` — Lifecycle state transitions. +- `import` / `export` — Bulk data movement across system boundaries. +- `search` — Intentional query with user-supplied terms (distinct from `list`, which implies browsing). +- `validate` — Check correctness without side effects. +- `preview` — Dry-run or read-only rendering of an action’s outcome. +- `transfer` — Move ownership or location between entities. +- `assign` / `unassign` — Attach or detach a resource to an owner. +- `tag` / `untag` — Apply or remove a label. + +**Forbidden Verbs** (never permitted): +- `process` — too vague; does not convey what the operation does. +- `handle` — internal/implementation language, not semantic. +- `manage` — a catch-all with no meaning to an agent. +- `do`, `run`, `execute`, `perform`, `trigger` — no accompanying noun can make these specific enough. +- `get*Data` patterns (e.g., `getInvoiceData`) — the `Data` suffix adds noise; use `getInvoice` instead. + + +### B.2. Operation `description` Completeness Rules + +Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. To ensure they can make correct choices, each operation must be **self-contained** for the purpose of selection and invocation. + +Therefore: +- `operation description` **MUST be present and non-empty**. +- `operation description` **MUST NOT be verbatim identical** to `summary`. +- The description **MUST contain all information** a tool-selecting consumer needs to: + - Decide whether to invoke the operation (`When to use`), + - Distinguish it from similar operations (`Differences`), + - Understand what it does (`Side effects`), + - Know what it returns and how to use the result (`Returns`), + - Identify required inputs (`Requires`). +- This information **MUST be reachable from the operation object** — via its `description`, parameters, and schemas — and **MUST NOT rely exclusively** on `info.description`. + - `info.description` may still provide valuable context (e.g., authentication flow, error-handling philosophy, rate limits), but the *operational essentials* must be self-contained. + +To help ensure completeness, designers **MAY** use the following template as a guide: +```yaml +description: | + When to use: {{ user asks to... }} + Differences: {{ Use instead of X when... }} (optional) + Side effects: {{ Action taken }} or "None" + Returns: {{ What's in the response and how to use it }} + Requires: {{ Data needed, e.g. "customerId from context" }} +``` +This template is **not mandatory**. It may be adapted, shortened, or omitted where the operation’s purpose is already unambiguous from its `operationId`, parameter names, and response schema — for example, simple, side-effect-free, parameter-light operations like `getHealth` or `getRoamingStatus`. +In such cases, a brief description such as`"Returns the service health status"` or `"Returns the current roaming status and the country information"` is sufficient. + +The fuller template remains **expected** for operations that: +- Take meaningful input, +- Have side effects, +- Return complex data requiring interpretation, +- Or could be confused with similarly named operations elsewhere in the API. + +### B.3. Property `description` Completeness Rules + +Building on the existing requirement in [2.2](#22-data-definitions) that every schema property must have a `description`, this section adds guidance for enums whose values are not self-explanatory to an automated consumer. + +Where enum values are not evident from their name alone (e.g., domain- or context-specific codes like `STATUS_OK`, `ERR_AUTH_FAIL`, or `STATE_PENDING`), the enum’s `description` **SHOULD** explain the meaning of each value using a **markdown bullet list**, with one bullet per value: +``` +description: | + Result of the verification: + - `TRUE`: the provided data matches + - `FALSE`: the provided data does not match + - `UNKNOWN`: the match could not be determined +``` +This format is **not required** for self-evident enums (e.g., `true`/`false`, `red`/`green`/`blue`, `open`/`closed`), but is **strongly encouraged** where ambiguity could lead to misinterpretation by tools or agents. From 7d9d59355a2becd07ac0e216c54f2a9154319920 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artych=20Rafa=C5=82?= Date: Mon, 6 Jul 2026 11:14:02 +0200 Subject: [PATCH 2/6] Update Annex B content --- documentation/CAMARA-API-Design-Guide.md | 54 ++++++++++-------------- 1 file changed, 23 insertions(+), 31 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index bfeac37b..0b87c4fe 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -3,7 +3,7 @@ This document outlines guidelines for API design within the CAMARA project, applicable to all APIs developed under the initiative. - + - [CAMARA API Design Guide](#camara-api-design-guide) - [1. Introduction](#1-introduction) @@ -99,6 +99,7 @@ This document outlines guidelines for API design within the CAMARA project, appl - [B.1. `operationId` Naming Rules](#b1-operationid-naming-rules) - [Proposal: Approved Verb List](#proposal-approved-verb-list) - [B.2. Operation `description` Completeness Rules](#b2-operation-description-completeness-rules) + - [Proposal: Operation `description` Template](#proposal-operation-description-template) - [B.3. Property `description` Completeness Rules](#b3-property-description-completeness-rules) @@ -1637,17 +1638,6 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` -You're right — if it's still feeling too short, then we’ve likely crossed into **over-concision**, sacrificing too much of the **design guidance**, **context**, and **educational value** that makes this appendix useful as a *standard*, not just a machine-readable checklist. - -The goal isn’t minimalism — it’s **clarity, usability, and enforceability** without unnecessary verbosity. - -Below is a **refined, balanced version** that: -- Retains all **key rules, examples, and intent**, -- Keeps helpful **explanations and boundaries** (e.g., *why* a rule exists, *what* it prevents), -- Removes only **redundant phrasing, obvious filler, and excessive whitespace**, -- Flows naturally for a designer reading it to understand and apply the guidance, -- Is **approximately 70–75% the length** of the original — substantive, but not bloated. - ## Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness @@ -1657,25 +1647,25 @@ This appendix is the outcome of the CAMARA MCP Enablement Program – Phase 0. I While [5.7.2](#572-operations) requires `operationId` to use lowerCamelCase when present, it does not mandate its presence. Since `operationId` is frequently used by tooling and automated systems as the primary handle to select and invoke an operation — and an operation without one generally cannot be used by such consumers — the following rules apply, beginning with an explicit presence requirement: -- `operationId` **MUST be present** on every operation. -- `operationId` **MUST be in lowerCamelCase format** and **MUST NOT exceed 64 characters in length**. This ensures compatibility with most code generators and vendor tooling limits. (These requirements are formally expressed by the regular expression: `^[a-z][a-zA-Z0-9]{0,63}$`.) -- `operationId` **MUST follow the shape** `[]`, for example: +- `operationId` MUST be present on every operation. +- `operationId` MUST be in lowerCamelCase format and MUST NOT exceed 64 characters in length. This ensures compatibility with most code generators and vendor tooling limits. (These requirements are formally expressed by the regular expression: `^[a-z][a-zA-Z0-9]{0,63}$`.) +- `operationId` MUST follow the shape `[]`, for example: - `createSession` (verb + noun) - `getDeviceLocation` (verb + compound noun) - `deleteSessionById` (verb + noun + qualifier) The `` represents the core resource, entity, or concept being acted upon — and MAY be a compound noun (e.g., `DeviceLocation`, `UserProfile`) formed from multiple domain terms. - The `` is optional and, when used, **MUST serve only to disambiguate** two operations that would otherwise share the same ``. When the qualifier disambiguates on an identifying parameter, it **SHOULD take the form** `By` (e.g., `deleteSessionById`). Otherwise, it **SHOULD be a single PascalCase noun or short noun phrase** appended directly to ``. -- `operationId` **MUST NOT be prefixed** with the HTTP method name, with the exception of `get` when used as an ordinary English verb. + The `` is optional and, when used, MUST serve only to disambiguate two operations that would otherwise share the same ``. When the qualifier disambiguates on an identifying parameter, it SHOULD take the form `By` (e.g., `deleteSessionById`). Otherwise, it SHOULD be a single PascalCase noun or short noun phrase appended directly to ``. +- `operationId` MUST NOT be prefixed with the HTTP method name, with the exception of `get` when used as an ordinary English verb. This avoids duplicating information already present in the OpenAPI `path`/`method` pair and adds no disambiguation value for automated selection. -- `operationId` **MUST NOT include a version marker** such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. -- Within a single API document, designers **SHOULD use one consistent read verb** (e.g., always `get` rather than alternating between `get`, `retrieve`, and `fetch`) to promote clarity and reduce cognitive load for consumers. -- `operationId` **SHOULD be unique** within the document to prevent collisions in code generation, tool registries, and AI agent tool-calling systems. +- `operationId` MUST NOT include a version marker** such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. +- Within a single API document, designers SHOULD use one consistent read verb (e.g., always `get` rather than alternating between `get`, `retrieve`, and `fetch`) to promote clarity and reduce cognitive load for consumers. +- `operationId` SHOULD be unique within the document to prevent collisions in code generation, tool registries, and AI agent tool-calling systems. #### Proposal: Approved Verb List -Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on this list **MUST** undergo a formal review process before use. +Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on this list MUST undergo a formal review process before use. **CRUD Core Verbs** (replace vague synonyms): - `create` — Instantiate a new resource. Replaces: `add`, `new`, `insert`, `post`. @@ -1713,21 +1703,23 @@ Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on ### B.2. Operation `description` Completeness Rules -Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. To ensure they can make correct choices, each operation must be **self-contained** for the purpose of selection and invocation. +Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. To ensure they can make correct choices, each operation must be self-contained for the purpose of selection and invocation. Therefore: -- `operation description` **MUST be present and non-empty**. -- `operation description` **MUST NOT be verbatim identical** to `summary`. -- The description **MUST contain all information** a tool-selecting consumer needs to: +- `operation description` MUST be present and non-empty. +- `operation description` MUST NOT be verbatim identical to `summary`. +- The description MUST contain all information a tool-selecting consumer needs to: - Decide whether to invoke the operation (`When to use`), - Distinguish it from similar operations (`Differences`), - Understand what it does (`Side effects`), - Know what it returns and how to use the result (`Returns`), - Identify required inputs (`Requires`). -- This information **MUST be reachable from the operation object** — via its `description`, parameters, and schemas — and **MUST NOT rely exclusively** on `info.description`. +- This information MUST be reachable from the operation object — via its `description`, parameters, and schemas — and MUST NOT rely exclusively on `info.description`. - `info.description` may still provide valuable context (e.g., authentication flow, error-handling philosophy, rate limits), but the *operational essentials* must be self-contained. -To help ensure completeness, designers **MAY** use the following template as a guide: + +#### Proposal: Operation `description` Template +To help ensure completeness, designers MAY use the following template as a guide: ```yaml description: | When to use: {{ user asks to... }} @@ -1736,10 +1728,10 @@ description: | Returns: {{ What's in the response and how to use it }} Requires: {{ Data needed, e.g. "customerId from context" }} ``` -This template is **not mandatory**. It may be adapted, shortened, or omitted where the operation’s purpose is already unambiguous from its `operationId`, parameter names, and response schema — for example, simple, side-effect-free, parameter-light operations like `getHealth` or `getRoamingStatus`. +This template is not mandatory. It may be adapted, shortened, or omitted where the operation’s purpose is already unambiguous from its `operationId`, parameter names, and response schema — for example, simple, side-effect-free, parameter-light operations like `getHealth` or `getRoamingStatus`. In such cases, a brief description such as`"Returns the service health status"` or `"Returns the current roaming status and the country information"` is sufficient. -The fuller template remains **expected** for operations that: +The fuller template remains expected for operations that: - Take meaningful input, - Have side effects, - Return complex data requiring interpretation, @@ -1749,7 +1741,7 @@ The fuller template remains **expected** for operations that: Building on the existing requirement in [2.2](#22-data-definitions) that every schema property must have a `description`, this section adds guidance for enums whose values are not self-explanatory to an automated consumer. -Where enum values are not evident from their name alone (e.g., domain- or context-specific codes like `STATUS_OK`, `ERR_AUTH_FAIL`, or `STATE_PENDING`), the enum’s `description` **SHOULD** explain the meaning of each value using a **markdown bullet list**, with one bullet per value: +Where enum values are not evident from their name alone (e.g., domain- or context-specific codes like `STATUS_OK`, `ERR_AUTH_FAIL`, or `STATE_PENDING`), the enum’s `description` SHOULD explain the meaning of each value using a markdown *bullet list*, with one bullet per value: ``` description: | Result of the verification: @@ -1757,4 +1749,4 @@ description: | - `FALSE`: the provided data does not match - `UNKNOWN`: the match could not be determined ``` -This format is **not required** for self-evident enums (e.g., `true`/`false`, `red`/`green`/`blue`, `open`/`closed`), but is **strongly encouraged** where ambiguity could lead to misinterpretation by tools or agents. +This format is NOT REQUIRED for self-evident enums (e.g., `true`/`false`, `red`/`green`/`blue`, `open`/`closed`), but is strongly encouraged where ambiguity could lead to misinterpretation by tools or agents. From ea2bc8d069eaf17e17b027834d0465d9e301cb42 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Mon, 6 Jul 2026 13:46:11 +0200 Subject: [PATCH 3/6] Update of TOC --- documentation/CAMARA-API-Design-Guide.md | 139 +++++++---------------- 1 file changed, 41 insertions(+), 98 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 0b87c4fe..cafc26fd 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -3,104 +3,47 @@ This document outlines guidelines for API design within the CAMARA project, applicable to all APIs developed under the initiative. - - -- [CAMARA API Design Guide](#camara-api-design-guide) - - [1. Introduction](#1-introduction) - - [1.1. Conventions](#11-conventions) - - [1.2. Common Vocabulary and Acronyms](#12-common-vocabulary-and-acronyms) - - [2. Data](#2-data) - - [2.1. Common Data Types](#21-common-data-types) - - [2.2. Data Definitions](#22-data-definitions) - - [2.2.1. Usage of Discriminator](#221-usage-of-discriminator) - - [Inheritance](#inheritance) - - [Polymorphism](#polymorphism) - - [2.3. Strictness of Request Body Schemas](#23-strictness-of-request-body-schemas) - - [3. Responses](#3-responses) - - [3.1. Business-level Outcomes in Successful Responses](#31-business-level-outcomes-in-successful-responses) - - [3.1.1. Scope and Problem Statement](#311-scope-and-problem-statement) - - [3.1.2. Core Principles](#312-core-principles) - - [3.1.3. Recommended Modeling Pattern](#313-recommended-modeling-pattern) - - [3.1.4. Example](#314-example) - - [3.1.5. Versioning and Migration Guidance](#315-versioning-and-migration-guidance) - - [3.2. Error Responses](#32-error-responses) - - [3.2.1. Standardized Use of CAMARA Error Responses](#321-standardized-use-of-camara-error-responses) - - [3.2.2. Error Responses - Device Object/Phone Number](#322-error-responses---device-objectphone-number) - - [3.2.2.1. Templates](#3221-templates) - - [Response template](#response-template) - - [Examples template](#examples-template) - - [3.2.3. Error Responses - Mandatory Template for `info.description` in CAMARA API](#323-error-responses---mandatory-template-for-infodescription-in-camara-api) - - [3.2.4. Request Body Strictness - Mandatory Template for `info.description` in CAMARA API](#324-request-body-strictness---mandatory-template-for-infodescription-in-camara-api) - - [4. Pagination, Sorting and Filtering](#4-pagination-sorting-and-filtering) - - [4.1. Pagination](#41-pagination) - - [4.1.1. Query Parameters](#411-query-parameters) - - [4.1.2. Request Headers](#412-request-headers) - - [4.1.3. Response Body](#413-response-body) - - [4.1.4. Response Headers](#414-response-headers) - - [4.1.5 HTTP Status Codes](#415-http-status-codes) - - [4.2. Sorting](#42-sorting) - - [4.3. Filtering](#43-filtering) - - [4.3.1. Filtering Security Considerations](#431-filtering-security-considerations) - - [4.3.2. Filtering Operations](#432-filtering-operations) - - [5. OpenAPI Sections](#5-openapi-sections) - - [5.1. Reserved Words](#51-reserved-words) - - [5.2. OpenAPI Version](#52-openapi-version) - - [5.3. Info Object](#53-info-object) - - [5.3.1. Title](#531-title) - - [5.3.2. Description](#532-description) - - [5.3.3. Version](#533-version) - - [5.3.4. Terms of Service](#534-terms-of-service) - - [5.3.5. Contact Information](#535-contact-information) - - [5.3.6. License](#536-license) - - [5.3.7. Extension Field](#537-extension-field) - - [5.4. ExternalDocs Object](#54-externaldocs-object) - - [5.5. Servers Object](#55-servers-object) - - [5.5.1. api-name](#551-api-name) - - [5.5.2. api-version](#552-api-version) - - [5.6. Tags](#56-tags) - - [5.7. Paths and Operations](#57-paths-and-operations) - - [5.7.1. Paths](#571-paths) - - [Resource hierarchy](#resource-hierarchy) - - [5.7.2. Operations](#572-operations) - - [5.7.3. Tags](#573-tags) - - [5.7.4. Parameters](#574-parameters) - - [5.7.5. Request Bodies](#575-request-bodies) - - [5.7.6. Responses](#576-responses) - - [5.7.6.1 Asynchronous responses](#5761-asynchronous-responses) - - [5.8. Components](#58-components) - - [5.8.1. Schemas](#581-schemas) - - [5.8.2. Responses](#582-responses) - - [5.8.3. Parameters](#583-parameters) - - [5.8.4. Request Bodies](#584-request-bodies) - - [5.8.5. Headers](#585-headers) - - [x-correlator Header](#x-correlator-header) - - [Pagination Headers](#pagination-headers) - - [Content-Type Header - clarification](#content-type-header---clarification) - - [5.8.6. Security Schemes](#586-security-schemes) - - [6. Security](#6-security) - - [6.1. Good Practices for Securing REST APIs](#61-good-practices-for-securing-rest-apis) - - [6.2. Security Definition](#62-security-definition) - - [6.3. Expressing Security Requirements](#63-expressing-security-requirements) - - [6.4. Mandatory Template for `info.description` in CAMARA API](#64-mandatory-template-for-infodescription-in-camara-api) - - [6.5. POST or GET for Transferring Sensitive or Complex Data](#65-post-or-get-for-transferring-sensitive-or-complex-data) - - [6.6. Scope Naming](#66-scope-naming) - - [6.6.1. APIs Which Do Not Deal with Explicit Subscriptions](#661-apis-which-do-not-deal-with-explicit-subscriptions) - - [Examples](#examples) - - [6.6.2. API-level Scopes (Sometimes Referred to as Wildcard Scopes in CAMARA)](#662-api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) - - [6.7. Resource Access Restriction](#67-resource-access-restriction) - - [7. Versioning](#7-versioning) - - [7.1. API Version (OAS `info` Object)](#71-api-version-oas-info-object) - - [7.2. API Version in URL (OAS `servers` Object)](#72-api-version-in-url-oas-servers-object) - - [7.3. API Versions Throughout the Release Process](#73-api-versions-throughout-the-release-process) - - [7.4. Backward and Forward Compatibility](#74-backward-and-forward-compatibility) - - [8. External Documentation](#8-external-documentation) - - [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) - - [Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness](#appendix-b-informative-operationid-and-description-guidelines-for-mcp-and-ai-agent-readiness) - - [B.1. `operationId` Naming Rules](#b1-operationid-naming-rules) - - [Proposal: Approved Verb List](#proposal-approved-verb-list) - - [B.2. Operation `description` Completeness Rules](#b2-operation-description-completeness-rules) - - [Proposal: Operation `description` Template](#proposal-operation-description-template) - - [B.3. Property `description` Completeness Rules](#b3-property-description-completeness-rules) + + +- [1. Introduction](#1-introduction) + - [1.1. Conventions](#11-conventions) + - [1.2. Common Vocabulary and Acronyms](#12-common-vocabulary-and-acronyms) +- [2. Data](#2-data) + - [2.1. Common Data Types](#21-common-data-types) + - [2.2. Data Definitions](#22-data-definitions) + - [2.3. Strictness of Request Body Schemas](#23-strictness-of-request-body-schemas) +- [3. Responses](#3-responses) + - [3.1. Business-level Outcomes in Successful Responses](#31-business-level-outcomes-in-successful-responses) + - [3.2. Error Responses](#32-error-responses) +- [4. Pagination, Sorting and Filtering](#4-pagination-sorting-and-filtering) + - [4.1. Pagination](#41-pagination) + - [4.2. Sorting](#42-sorting) + - [4.3. Filtering](#43-filtering) +- [5. OpenAPI Sections](#5-openapi-sections) + - [5.1. Reserved Words](#51-reserved-words) + - [5.2. OpenAPI Version](#52-openapi-version) + - [5.3. Info Object](#53-info-object) + - [5.4. ExternalDocs Object](#54-externaldocs-object) + - [5.5. Servers Object](#55-servers-object) + - [5.6. Tags](#56-tags) + - [5.7. Paths and Operations](#57-paths-and-operations) + - [5.8. Components](#58-components) +- [6. Security](#6-security) + - [6.1. Good Practices for Securing REST APIs](#61-good-practices-for-securing-rest-apis) + - [6.2. Security Definition](#62-security-definition) + - [6.3. Expressing Security Requirements](#63-expressing-security-requirements) + - [6.4. Mandatory Template for `info.description` in CAMARA API](#64-mandatory-template-for-infodescription-in-camara-api) + - [6.5. POST or GET for Transferring Sensitive or Complex Data](#65-post-or-get-for-transferring-sensitive-or-complex-data) + - [6.6. Scope Naming](#66-scope-naming) + - [6.7. Resource Access Restriction](#67-resource-access-restriction) +- [7. Versioning](#7-versioning) + - [7.1. API Version (OAS `info` Object)](#71-api-version-oas-info-object) + - [7.2. API Version in URL (OAS `servers` Object)](#72-api-version-in-url-oas-servers-object) + - [7.3. API Versions Throughout the Release Process](#73-api-versions-throughout-the-release-process) + - [7.4. Backward and Forward Compatibility](#74-backward-and-forward-compatibility) +- [8. External Documentation](#8-external-documentation) +- [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) +- [Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness](#appendix-b-informative-operationid-and-description-guidelines-for-mcp-and-ai-agent-readiness) From c65ea57f214da185dbfdcb44c9784a2b1438bd78 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Sat, 11 Jul 2026 22:39:49 +0200 Subject: [PATCH 4/6] Update after review comments --- documentation/CAMARA-API-Design-Guide.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index cafc26fd..657e26a1 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -1643,7 +1643,6 @@ Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on - `do`, `run`, `execute`, `perform`, `trigger` — no accompanying noun can make these specific enough. - `get*Data` patterns (e.g., `getInvoiceData`) — the `Data` suffix adds noise; use `getInvoice` instead. - ### B.2. Operation `description` Completeness Rules Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. To ensure they can make correct choices, each operation must be self-contained for the purpose of selection and invocation. @@ -1660,7 +1659,6 @@ Therefore: - This information MUST be reachable from the operation object — via its `description`, parameters, and schemas — and MUST NOT rely exclusively on `info.description`. - `info.description` may still provide valuable context (e.g., authentication flow, error-handling philosophy, rate limits), but the *operational essentials* must be self-contained. - #### Proposal: Operation `description` Template To help ensure completeness, designers MAY use the following template as a guide: ```yaml From 17e2585e3900c2fe1085a4d7a7220dc67363e2a6 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Sat, 11 Jul 2026 22:45:35 +0200 Subject: [PATCH 5/6] Update after review --- documentation/CAMARA-API-Design-Guide.md | 66 +++++++++++------------- 1 file changed, 29 insertions(+), 37 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 657e26a1..d5e985fd 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -1600,84 +1600,76 @@ While [5.7.2](#572-operations) requires `operationId` to use lowerCamelCase when The `` represents the core resource, entity, or concept being acted upon — and MAY be a compound noun (e.g., `DeviceLocation`, `UserProfile`) formed from multiple domain terms. The `` is optional and, when used, MUST serve only to disambiguate two operations that would otherwise share the same ``. When the qualifier disambiguates on an identifying parameter, it SHOULD take the form `By` (e.g., `deleteSessionById`). Otherwise, it SHOULD be a single PascalCase noun or short noun phrase appended directly to ``. -- `operationId` MUST NOT be prefixed with the HTTP method name, with the exception of `get` when used as an ordinary English verb. +- `operationId` MUST NOT be prefixed with `post`, `put`, or `patch`. (`get` and `delete` are ordinary English verbs describing the operation's action and are not considered HTTP-method leakage.) This avoids duplicating information already present in the OpenAPI `path`/`method` pair and adds no disambiguation value for automated selection. -- `operationId` MUST NOT include a version marker** such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. -- Within a single API document, designers SHOULD use one consistent read verb (e.g., always `get` rather than alternating between `get`, `retrieve`, and `fetch`) to promote clarity and reduce cognitive load for consumers. -- `operationId` SHOULD be unique within the document to prevent collisions in code generation, tool registries, and AI agent tool-calling systems. +- `operationId` MUST NOT include a version marker such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. +- Within a single API document, designers SHOULD use one consistent read verb per retrieval style: `get` for reading resources via `GET`, and `retrieve` for POST-based queries as defined in [6.5. POST or GET for Transferring Sensitive or Complex Data](#65-post-or-get-for-transferring-sensitive-or-complex-data), mirroring the `retrieve-*` verb path. Synonyms such as `read` or `fetch` SHOULD NOT be used in their place. +- `operationId` MUST be unique within the API document, as required by the OpenAPI specification. #### Proposal: Approved Verb List -Verbs used in `operationId` SHOULD be restricted to the list below. Verbs not on this list MUST undergo a formal review process before use. +Verbs used in `operationId` SHOULD be restricted to the list below. Any verb not present in the list MUST be submitted for formal review through a GitHub issue in the Commonalities repository before it may be used. **CRUD Core Verbs** (replace vague synonyms): - `create` — Instantiate a new resource. Replaces: `add`, `new`, `insert`, `post`. -- `get` — Fetch a single resource by identity. Replaces: `fetch`, `retrieve`, `read`, `find`. +- `get` — Fetch a single resource by identity. Replaces: `fetch`, `read`, `find`. +- `retrieve` — Fetch a single resource using POST-based queries. Replaces: `fetch`, `read`, `find`. - `list` — Fetch a collection, optionally filtered. Replaces: `getAll`, `fetchAll`, `search` (when browsing). - `update` — Modify an existing resource, fully or partially. Replaces: `edit`, `modify`, `patch`, `put`. -- `replace` — Full replacement of a resource (PUT semantics). Replaces: `put`, `overwrite`. - `delete` — Remove a resource permanently. Replaces: `remove`, `destroy`, `drop`. **Action Verbs** (for non-CRUD operations): - `send` — Dispatch a message, notification, or payload. - `submit` — Hand off for processing (e.g., forms, orders, applications). -- `approve` — Grant explicit authorization. - `cancel` — Abort an in-progress or future operation. -- `publish` — Make a resource publicly available. -- `archive` — Move to long-term / read-only storage. -- `restore` — Reverse an archive or soft delete. - `enable` / `disable` — Toggle active state. - `activate` / `deactivate` — Lifecycle state transitions. -- `import` / `export` — Bulk data movement across system boundaries. - `search` — Intentional query with user-supplied terms (distinct from `list`, which implies browsing). - `validate` — Check correctness without side effects. -- `preview` — Dry-run or read-only rendering of an action’s outcome. -- `transfer` — Move ownership or location between entities. - `assign` / `unassign` — Attach or detach a resource to an owner. -- `tag` / `untag` — Apply or remove a label. -**Forbidden Verbs** (never permitted): +**Forbidden Verbs** (SHOULD NOT be used): - `process` — too vague; does not convey what the operation does. - `handle` — internal/implementation language, not semantic. - `manage` — a catch-all with no meaning to an agent. - `do`, `run`, `execute`, `perform`, `trigger` — no accompanying noun can make these specific enough. - `get*Data` patterns (e.g., `getInvoiceData`) — the `Data` suffix adds noise; use `getInvoice` instead. +Note: The rules in this section apply to path operations only (i.e., operations defined under the OpenAPI `paths` object). Callback `operationId`s — such as the `postNotification` used in CAMARA notification callback definitions, which are implemented by the API consumer and never exposed as tools — are **out of scope** and not subject to these rules. + ### B.2. Operation `description` Completeness Rules -Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. To ensure they can make correct choices, each operation must be self-contained for the purpose of selection and invocation. +Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`.The following rules ensure operations remain self-contained for this purpose. -Therefore: -- `operation description` MUST be present and non-empty. -- `operation description` MUST NOT be verbatim identical to `summary`. +- Operation `description` MUST be present and non-empty. +- Operation `description` MUST NOT be verbatim identical to `summary`. - The description MUST contain all information a tool-selecting consumer needs to: - - Decide whether to invoke the operation (`When to use`), - - Distinguish it from similar operations (`Differences`), - - Understand what it does (`Side effects`), - - Know what it returns and how to use the result (`Returns`), - - Identify required inputs (`Requires`). + - Decide whether to invoke the operation (*When to use*), + - Distinguish it from similar operations (*Differences*), + - Understand what it does (*Side effects*). + - This information MUST be reachable from the operation object — via its `description`, parameters, and schemas — and MUST NOT rely exclusively on `info.description`. - `info.description` may still provide valuable context (e.g., authentication flow, error-handling philosophy, rate limits), but the *operational essentials* must be self-contained. + - Additional information in the operation `description` that is primarily intended for human readers rather than automated consumers SHOULD, if present, be placed at the end of the description. This allows to more easily ignore or remove such content when processing the operation for tool selection. #### Proposal: Operation `description` Template -To help ensure completeness, designers MAY use the following template as a guide: +To help satisfy this rule, API designers MAY structure the operation description using the following template: +```yaml +description: | + {{Action}} {{core noun or concept}}. + {{Use this to... / Call this when... / Use this for...}} + {{Only mention side effects if they exist.}} + {{Any non-obvious requirements or context needed.}} +``` +Example: ```yaml description: | - When to use: {{ user asks to... }} - Differences: {{ Use instead of X when... }} (optional) - Side effects: {{ Action taken }} or "None" - Returns: {{ What's in the response and how to use it }} - Requires: {{ Data needed, e.g. "customerId from context" }} + Returns the current geographical location of a device. + Use this to get position information. ``` This template is not mandatory. It may be adapted, shortened, or omitted where the operation’s purpose is already unambiguous from its `operationId`, parameter names, and response schema — for example, simple, side-effect-free, parameter-light operations like `getHealth` or `getRoamingStatus`. In such cases, a brief description such as`"Returns the service health status"` or `"Returns the current roaming status and the country information"` is sufficient. -The fuller template remains expected for operations that: -- Take meaningful input, -- Have side effects, -- Return complex data requiring interpretation, -- Or could be confused with similarly named operations elsewhere in the API. - ### B.3. Property `description` Completeness Rules Building on the existing requirement in [2.2](#22-data-definitions) that every schema property must have a `description`, this section adds guidance for enums whose values are not self-explanatory to an automated consumer. From 7550b054e1c21f7b43400bd30a89e02f59fc6c1f Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 24 Jul 2026 12:42:07 +0200 Subject: [PATCH 6/6] Update CAMARA-API-Design-Guide.md --- documentation/CAMARA-API-Design-Guide.md | 28 ++++++++++++++---------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index d5e985fd..3d0f91be 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -1585,6 +1585,7 @@ This approach simplifies API usage for API consumers using a three-legged access ## Appendix B (Informative): `operationId` and `description` Guidelines for MCP and AI Agent Readiness This appendix is the outcome of the CAMARA MCP Enablement Program – Phase 0. It extends the naming and documentation rules in [5.7.2](#572-operations) and [2.2](#22-data-definitions) with additional, targeted constraints to ensure CAMARA API operations can be reliably selected and invoked by automated consumers, including AI agents and **Model Context Protocol (MCP)** tool-selection pipelines. These consumers rely on the operation object itself — not the top-level `info.description` — to understand what an operation does, when to use it, and how to invoke it correctly. +Note: Although this appendix is informative, it uses RFC 2119 keywords (MUST, SHOULD, MAY) to indicate the intended normative strength of each rule if and when it is promoted into the main body of this document. ### B.1. `operationId` Naming Rules @@ -1599,7 +1600,8 @@ While [5.7.2](#572-operations) requires `operationId` to use lowerCamelCase when The `` represents the core resource, entity, or concept being acted upon — and MAY be a compound noun (e.g., `DeviceLocation`, `UserProfile`) formed from multiple domain terms. - The `` is optional and, when used, MUST serve only to disambiguate two operations that would otherwise share the same ``. When the qualifier disambiguates on an identifying parameter, it SHOULD take the form `By` (e.g., `deleteSessionById`). Otherwise, it SHOULD be a single PascalCase noun or short noun phrase appended directly to ``. + The `` is optional and SHOULD primarily serve to disambiguate two operations that would otherwise share the same ``, or to make the operation's scope explicit (e.g., `retrieveSessionsByDevice`). When the qualifier disambiguates on an identifying parameter, it SHOULD take the form `By` (e.g., `deleteSessionById`). Otherwise, it SHOULD be a single PascalCase noun or short noun phrase appended directly to ``. + - `operationId` MUST NOT be prefixed with `post`, `put`, or `patch`. (`get` and `delete` are ordinary English verbs describing the operation's action and are not considered HTTP-method leakage.) This avoids duplicating information already present in the OpenAPI `path`/`method` pair and adds no disambiguation value for automated selection. - `operationId` MUST NOT include a version marker such as `V1`, `_v1`, `v2`, or similar. Versioning belongs in the API path (e.g., `/v1/sessions`) or headers, not in the operation identifier. @@ -1619,16 +1621,17 @@ Verbs used in `operationId` SHOULD be restricted to the list below. Any verb not - `delete` — Remove a resource permanently. Replaces: `remove`, `destroy`, `drop`. **Action Verbs** (for non-CRUD operations): +- `check` — Evaluate a condition or status and return a result without side effects (e.g., `checkSimSwap`). +- `verify` — Confirm that provided data matches operator records (e.g., `verifyLocation`, `verifyNumber`). - `send` — Dispatch a message, notification, or payload. - `submit` — Hand off for processing (e.g., forms, orders, applications). - `cancel` — Abort an in-progress or future operation. - `enable` / `disable` — Toggle active state. -- `activate` / `deactivate` — Lifecycle state transitions. -- `search` — Intentional query with user-supplied terms (distinct from `list`, which implies browsing). -- `validate` — Check correctness without side effects. -- `assign` / `unassign` — Attach or detach a resource to an owner. +- `validate` — Check structural or syntactic correctness without side effects. -**Forbidden Verbs** (SHOULD NOT be used): +This list is intentionally short and based on verbs in actual use across CAMARA APIs; it is expected to grow through the review process described above. + +**Discouraged Verbs** (SHOULD NOT be used): - `process` — too vague; does not convey what the operation does. - `handle` — internal/implementation language, not semantic. - `manage` — a catch-all with no meaning to an agent. @@ -1639,7 +1642,7 @@ Note: The rules in this section apply to path operations only (i.e., operations ### B.2. Operation `description` Completeness Rules -Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`.The following rules ensure operations remain self-contained for this purpose. +Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations using only the operation object — its `description`, `parameters`, `requestBody`, and `responses` — not the global `info.description`. The following rules ensure operations remain self-contained for this purpose. - Operation `description` MUST be present and non-empty. - Operation `description` MUST NOT be verbatim identical to `summary`. @@ -1650,7 +1653,7 @@ Automated consumers (e.g., AI agents, MCP clients) typically evaluate operations - This information MUST be reachable from the operation object — via its `description`, parameters, and schemas — and MUST NOT rely exclusively on `info.description`. - `info.description` may still provide valuable context (e.g., authentication flow, error-handling philosophy, rate limits), but the *operational essentials* must be self-contained. - - Additional information in the operation `description` that is primarily intended for human readers rather than automated consumers SHOULD, if present, be placed at the end of the description. This allows to more easily ignore or remove such content when processing the operation for tool selection. + - Additional information in the operation `description` that is primarily intended for human readers rather than automated consumers SHOULD, if present, be placed at the end of the description. This makes it easier to ignore or strip such content when processing the operation for tool selection. Descriptions also contribute directly to the token size of generated tool definitions, so designers SHOULD keep them concise and avoid restating information already conveyed by parameter and response schemas. #### Proposal: Operation `description` Template To help satisfy this rule, API designers MAY structure the operation description using the following template: @@ -1665,12 +1668,12 @@ Example: ```yaml description: | Returns the current geographical location of a device. - Use this to get position information. + Use this to get position information. ``` This template is not mandatory. It may be adapted, shortened, or omitted where the operation’s purpose is already unambiguous from its `operationId`, parameter names, and response schema — for example, simple, side-effect-free, parameter-light operations like `getHealth` or `getRoamingStatus`. -In such cases, a brief description such as`"Returns the service health status"` or `"Returns the current roaming status and the country information"` is sufficient. +In such cases, a brief description such as `"Returns the service health status"` or `"Returns the current roaming status and the country information"` is sufficient. -### B.3. Property `description` Completeness Rules +### B.3. Property `description` Completeness Rules for Enums Building on the existing requirement in [2.2](#22-data-definitions) that every schema property must have a `description`, this section adds guidance for enums whose values are not self-explanatory to an automated consumer. @@ -1682,4 +1685,5 @@ description: | - `FALSE`: the provided data does not match - `UNKNOWN`: the match could not be determined ``` -This format is NOT REQUIRED for self-evident enums (e.g., `true`/`false`, `red`/`green`/`blue`, `open`/`closed`), but is strongly encouraged where ambiguity could lead to misinterpretation by tools or agents. + +This format is OPTIONAL for self-evident enums (e.g., `true`/`false`, `red`/`green`/`blue`, `open`/`closed`), but is strongly encouraged where ambiguity could lead to misinterpretation by tools or agents.