Skip to content

r2.2

Pre-release
Pre-release

Choose a tag to compare

View all tags
@camara-release-automation camara-release-automation released this 06 Nov 01:18
r2.2
1a0dc14
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes

This release candidate contains the definition and documentation of

  • knowledge-base 0.2.0-rc.2
  • qa-assistant-manage 0.2.0-rc.2
  • qa-assistant-service 0.2.0-rc.2

The API definition(s) are based on

  • Commonalities r4.4 (0.9.0)
  • Identity and Consent Management r4.2 (0.5.0)

knowledge-base 0.2.0-rc.2

knowledge-base 0.2.0-rc.2 is a release-candidate version of this API.

Changes documented below are compared to version 0.2.0-rc.1.

Breaking changes

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • The update operations updateKnowledgeBase and updateTool now use HTTP PATCH instead of PUT (issue #50). Request bodies, response bodies and status codes are unchanged - only the HTTP verb changes. The partial-update semantics documented in r2.1 still apply unchanged: fields omitted from the request body are left unchanged (not cleared), providing a field replaces its stored value, and at least one updatable field MUST be provided (an empty body is rejected with 400 INVALID_ARGUMENT). This change supersedes the r2.1 decision to retain PUT with documented partial-update semantics. Rationale: per RFC 7231 §4.3.4 a PUT request asks that the state of the target resource be created or replaced (full replacement), while the request bodies of these operations carry a set of optional field modifications - the "set of instructions describing how a resource should be modified" that RFC 5789 defines PATCH for. Since the APIs are pre-1.0 (0.2.0-rc.x), breaking changes are permitted per the CAMARA API Readiness Checklist, and switching now costs only the verb (a later switch would require a major version). API consumers MUST send PATCH requests to /knowledge-bases/{knowledgeBaseId} and /knowledge-bases/{knowledgeBaseId}/tools/{toolId}; PUT is no longer part of the documented contract for these operations.
  • Replace deprecated GenericXXX error schemas with Commonalities r4.4 common error schemas by @lihaojie-CMCC in #71

Added

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • Test definitions: the three scenarios requested in issue #58:
      • @knowledge_base_get_document_404_01_not_found: requests getDocument with a documentId set to a random UUID and asserts 404 with $.code = NOT_FOUND. The 404 response has been documented for getDocument since r2.1; the sibling deleteDocument operation already had a not-found scenario (@knowledge_base_delete_document_404_01_not_found), getDocument did not.
      • @knowledge_base_create_409_01_duplicate_name: creates a knowledge base named duplicate-kb, then sends createKnowledgeBase with the same name and asserts 409 with $.code = ALREADY_EXISTS. This tests the AlreadyExists409 response documented as part of the issue #46 fix in this release and completes 409 test coverage for all three operations that document a 409 (createKnowledgeBase, createTool, updateTool).
      • @knowledge_base_list_02_empty: restored - the scenario had been deleted rather than updated during the rc.1 review cycle (PR #54) while its equivalent in qa-assistant-manage.feature was kept. It asserts that listKnowledgeBases returns 200 with items as an empty array and pagination present and compliant with the Pagination schema - the empirical check that pagination is always present, as made required for issue #47.
    • Test definitions: failure scenarios for the operations that previously only had a success path, so that every per-operation feature file covers both the happy path and the relevant error behaviour. No API definition changes were needed for these additions:
      • updateKnowledgeBase: @knowledge_base_update_400_01_empty_body (400 INVALID_ARGUMENT for an empty request body, exercising the at-least-one-updatable-field rule), @knowledge_base_update_403_01_missing_scope, @knowledge_base_update_404_01_not_found (random UUID).
      • deleteKnowledgeBase: @knowledge_base_delete_403_01_missing_scope, @knowledge_base_delete_404_01_not_found.
      • getTool: @knowledge_base_tool_get_403_01_missing_scope, @knowledge_base_tool_get_404_01_not_found.
  • Add 415 response declaration to createTool operation by @lihaojie-CMCC in #85

Changed

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • The documented 409 responses are narrowed to exactly the error code each operation can return, adopting the Commonalities r4.4 error-response catalogue (issue #46). In r2.1 all three operations documented their 409 by referencing the shared Generic409 response, whose code enum bundles ABORTED, ALREADY_EXISTS and INCOMPATIBLE_STATE (the deprecated CONFLICT code was itself removed from that enum in Commonalities 0.9.0). But createKnowledgeBase and createTool can only return ALREADY_EXISTS (duplicate name) and updateTool only ABORTED (concurrent modification), so each published contract declared three error codes of which two can never occur. Following the Commonalities r4.4 migration guidance in CAMARA_common.yaml ("Generic409 → AlreadyExists409; ... local definition from the ABORTED / INCOMPATIBLE_STATE examples otherwise"):
      • createKnowledgeBase and createTool now reference the catalogue response AlreadyExists409 (HTTP 409, code enum restricted to ALREADY_EXISTS, shared example GENERIC_409_ALREADY_EXISTS).
      • updateTool defines a local Aborted409 response (components.responses), because r4.4 provides no catalogue response for ABORTED: HTTP 409, code enum restricted to ABORTED, with the example $ref-ing the shared GENERIC_409_ABORTED example so the error wording stays consistent across CAMARA APIs. It follows the same locally-defined-response pattern as the existing ToolInvalidInput422.
      • All 409 responses keep the x-correlator header, and the narrowed contracts now match the existing test scenarios exactly (@knowledge_base_tool_create_409_01_duplicate_name → ALREADY_EXISTS, @knowledge_base_tool_update_409_01_concurrent_modification → ABORTED, new @knowledge_base_create_409_01_duplicate_name → ALREADY_EXISTS).
        This is a documentation-precision change, not a behavioural one: implementations never returned the removed codes for these operations.
    • Aligned with Commonalities r4.4 (0.9.0). code/common/CAMARA_common.yaml refreshed to the r4.4 release artifacts:
      • new catalogue of minimal, directly referenceable error responses (BadRequest400, BadRequestWithRange400, Unauthenticated401, PermissionDenied403, NotFound404, IdentifierNotFound404, AlreadyExists409, DeviceIdentifier422, PhoneNumberIdentifier422, TooManyRequests429), added alongside the existing Generic* responses, which remain valid;
      • new Date and SingleIpv6Address schemas (Ipv6Address now composes SingleIpv6Address via allOf);
      • the perPage parameter description corrected from "Number of subscriptions to return per page" to "Number of resources to return per page" (this repository had flagged the old wording for upstream correction in the r2.1 changelog);
      • the info.description Commonalities reference updated to the r4.4 template wording (the applicable Commonalities Release is now identified from the x-camara-commonalities field, the changelog and the released API version metadata).
    • The components $ref-ed by this API (x-correlator header/parameter, page/perPage parameters, Generic400/401/403/404/415/500 responses, ErrorInfo, Pagination, DateTime schemas, openId security scheme) are byte-identical between the r4.3 and r4.4 versions of the common file. The x-camara-commonalities marker is updated from 0.8.0 to 0.9.0. No behavioural change to this API.
    • Test definitions restructured: knowledge-base.feature (50 scenarios) split into 14 feature files, one per operationId, as recommended in issue #58 per the location-of-feature-files convention in the CAMARA API Testing Guidelines, so the 50-scenarios-per-file warning of CAMARA Validation no longer applies. The new files are knowledge-base-createKnowledgeBase.feature, -listKnowledgeBases.feature, -getKnowledgeBase.feature, -updateKnowledgeBase.feature, -deleteKnowledgeBase.feature, -uploadDocument.feature, -getDocument.feature, -deleteDocument.feature, -createTool.feature, -listTools.feature, -getTool.feature, -updateTool.feature, -deleteTool.feature and -callTool.feature; each carries its own Background (apiRoot environment, resource, Content-Type, Authorization, x-correlator schema check). All 50 existing scenarios are preserved unchanged; the split yields 60 scenarios across the 14 files (50 existing plus the 10 additions listed under Added above).

Fixed

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • Removed the contradiction between the Security considerations text and the enforced https-only constraint (issue #56). The Security considerations section (introduced for the SSRF mitigation of issue #40) documented three aspects of the tool url protocol restriction, one of which contradicted the other two: the schema enforces https unconditionally via pattern: '^https://.*' (an http:// URL is rejected at write time with 400 INVALID_ARGUMENT) and the ToolCommon.url description states "MUST use the https scheme", but the URL scheme bullet of the Security considerations still read "Only https (and optionally http for non-sensitive, explicitly documented local testing) URLs are accepted" - an exception the schema does not implement. The parenthetical was removed so the bullet now reads "Only https URLs are accepted."; in the same pass the ports bullet was aligned ("e.g. 443 for HTTPS, optionally 80 for HTTP" → "e.g. 443 for HTTPS"), since port 80 is unreachable under the https-only constraint. Documentation-only change; the enforced behaviour is unchanged.
  • Clean up 'GenericXXX' in Test_definitions by @lihaojie-CMCC in #77

Removed

qa-assistant-manage 0.2.0-rc.2

qa-assistant-manage 0.2.0-rc.2 is a release-candidate version of this API.

Changes documented below are compared to version 0.2.0-rc.1.

Breaking changes

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • The update operation updateAssistant now uses HTTP PATCH instead of PUT (issue #50). Request bodies, response bodies and status codes are unchanged - only the HTTP verb changes. The partial-update semantics documented in r2.1 still apply unchanged: fields omitted from the request body are left unchanged (not cleared), largeModelParameters and toolIds are replaced as a whole when provided (no nested merge, not appended to), and at least one updatable field MUST be provided. See the knowledge-base 0.2.0-rc.2 Breaking changes above for the full rationale (RFC 7231 §4.3.4 vs RFC 5789, and why the switch is made in this release). API consumers MUST send PATCH requests to /assistants/{assistantId}; PUT is no longer part of the documented contract for this operation.
  • Replace deprecated GenericXXX error schemas with Commonalities r4.4 common error schemas by @lihaojie-CMCC in #71

Added

Changed

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • Aligned with Commonalities r4.4 (0.9.0): the x-camara-commonalities marker updated from 0.8.0 to 0.9.0 and the info.description Commonalities reference updated to the r4.4 template wording (the applicable Commonalities Release is now identified from the x-camara-commonalities field, the changelog and the released API version metadata). The components $ref-ed by this API from code/common/CAMARA_common.yaml are unchanged between r4.3 and r4.4. No behavioural change to this API. The test file qa-assistant-manage.feature received only the same marker update (31 scenarios, below the 50-scenarios-per-file limit, so no split was needed).

Fixed

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • The largeModelParameters bounds documentation no longer describes the minimum/maximum values as "reference defaults" that the provider MAY adjust (issue #57). In r2.1, following issue #52, the bounds were documented as reference defaults with "An API provider MAY adjust (widen or tighten) these bounds to match what its backend actually supports" and values outside "the bounds documented by the provider" rejected with 400 OUT_OF_RANGE. That contradicts the published contract: the schema's minimum/maximum are enforced validation constraints, there is no mechanism for a provider to adjust them in a published API definition, tightening them would reject requests that are valid against the published schema, and widening them would be undiscoverable by consumers reading the contract. The adjustability wording was removed in 11 places in qa-assistant-manage.yaml:
      • the largeModelParameters summary bullet in info.description (now: fixed contract constraints, values outside the bounds rejected with 400 OUT_OF_RANGE);
      • the AssistantCreateRequest.largeModelParameters description, where the "Provider-specific bounds" paragraph (including the "some LLM providers use a temperature range of 0-2" example) was rewritten as a "Parameter bounds" note stating that the bounds are fixed contract constraints, identical for every API provider and not provider-adjustable;
      • the temperature / maxTokens / topP field descriptions in AssistantCreateRequest, AssistantUpdateRequest and Assistant (7 places), which no longer carry "MAY adjust" / "reference default" sentences or pointers to the removed note.
    • The stale cross-reference "See the largeModelParameters description on AssistantCreateRequest for the provider-specific bounds note" in AssistantUpdateRequest.largeModelParameters now points at the fixed-bounds note instead. The bounds are now documented as fixed contract constraints; values outside the bounds are rejected with 400 OUT_OF_RANGE, as asserted by the six existing OUT_OF_RANGE test scenarios across the three test suites. The minimum/maximum values themselves are unchanged (temperature 0-1, maxTokens 1-128000, topP 0-1). Documentation-only change.

Removed

qa-assistant-service 0.2.0-rc.2

qa-assistant-service 0.2.0-rc.2 is a release-candidate version of this API.

Changes documented below are compared to version 0.2.0-rc.1.

Breaking changes

  • Replace deprecated GenericXXX error schemas with Commonalities r4.4 common error schemas by @lihaojie-CMCC in #71

Added

  • N/A

Changed

  • Update API files for Sync26 Release r2.2 by @lihaojie-CMCC in #63
    • Aligned with Commonalities r4.4 (0.9.0): the x-camara-commonalities marker updated from 0.8.0 to 0.9.0 and the info.description Commonalities reference updated to the r4.4 template wording (the applicable Commonalities Release is now identified from the x-camara-commonalities field, the changelog and the released API version metadata). The components $ref-ed by this API from code/common/CAMARA_common.yaml are unchanged between r4.3 and r4.4. No behavioural change to this API. The test file qa-assistant-service.feature received only the same marker update (16 scenarios, below the 50-scenarios-per-file limit, so no split was needed).

Fixed

  • N/A

Removed

Full Changelog: r2.1...r2.2

Contributors

lihaojie-CMCC
Assets 2
Loading