@lihaojie-CMCC Don't have the time for detailed review, but happy to support with comments on points I see. I have mainly looked on the first YAML knowledge-base-manage.yaml, some comments might apply also to other two.

Important point are the API names. They are very important for us here in CAMARA, and there is the guideline that file names, title in the API definitions and the server URL must be consistent. See CAMARA-API-Design-Guide.md#52-openapi-version and the following section there. "api-name is a kebab-case string used to create unique names or values of objects and parameters related to given API"

Currently I see:

File name: knowledge-base-manage -> is the "manage" needed here? qa-knowledge-base would be consistent with the server URL
Title: Knowledge Base - Manage -> Q&A Knowledge Base instead?
API Name in server URL: qa/knowledge_base (-> should be qa-knowledge-base, if you want "qa" part of the API name. I'm not against the form qa/knowledge-base, but that isn't covered by the current guidelines and would add one path level more which could create challenges for API providers who rely on the guidelines)

File name: qa-assistent-manage
Title: Q&A Assistant - Manage
API Name in server URL: qa/assistant_manage -> should be qa-assistant-manage

File name: qa-assistent-service
Title: Q&A Assistant - Service
API Name in server URL: qa/assistant_service -> should be qa-assistant-service

Security:

Use

 security:
        - openId:
            - {scope}

instead of

security:
        - openId: ['knowledge-base:create']  # Added security scope

(might be equivalent, but not as in the guidelines)

documents:upload -> knowledge-base:documents:upload or qa-knowledge-base:documents:upload (all scopes are starting with the API name, with optional :<resource>: field, cf. https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#66-scope-naming)

Path names: "Using lowercase words and hyphenation (kebab-case)" ... so /knowlegde-bases instead of /knowledge_bases"

BTW: Tags have to be consistent, defined is knowledge-base, but used is in line 40 Knowledge Bases

General hints:

• View the file in Swagger UI, it should be valid and look correct (e.g. https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/r2.2/code/API_definitions/qod-provisioning.yaml is currently invalid)
• Deploy linting within the repository, as described in https://github.com/camaraproject/Commonalities/blob/main/documentation/API-linting-Implementation-Guideline.md

x-correlator: "required: true" for the header is wrong, the parameter is optional for API consumers

Please use the definition as in https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml

headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

x-correlator parameter is missing in the 2xx responses?

Add required RFC 2229 description to uploadDate field:

uploadDate:
  type: string
  format: date-time
  description: "Upload timestamp. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ"

Add the required externalDocs section:

externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/ModelAsAService

Add the mandatory text about additional CAMARA error responses into the (end of) info section (as of https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#33-error-responses---mandatory-template-for-infodescription-in-camara-api-specs)

# Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.

As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.

As of https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#64-mandatory-template-for-infodescription-in-camara-api-specs and https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#64-mandatory-template-for-infodescription-in-camara-api-specs add the mandatory template to the info description:

# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. 

Hi @hdamker , Thank you for taking the time to review our project! We truly appreciate your valuable input.

We've addressed each of your suggestions individually in the latest updates. Please feel free to verify the modifications at your convenience.

@lihaojie-CMCC all changes are looking good - I will not check now if they are complete as there will be anyway a release review on your M3 release PR.

But one hint: the title of the PR says "meet alpha release requirements", but as you want to participate in the Fall25 meta-release (as indicated by the release trackers which you have created), you would need to create the release PR for the release-candidate versions (r1.1 with 0.1.0-rc.1) until end of the week. Alpha release is optional, so I recommend that you go directly to the release candidate. Please have a look on https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/API_Release_Guidelines.md#Releasing-an-API-step-by-step and prepare your release PR for r1.1 already in parallel.