diff --git a/documentation/API proposals/TrustWorthiness_Intent_API_proposal.md b/documentation/API proposals/TrustWorthiness_Intent_API_proposal.md new file mode 100644 index 0000000..6bc9aab --- /dev/null +++ b/documentation/API proposals/TrustWorthiness_Intent_API_proposal.md @@ -0,0 +1,52 @@ +# API Proposal Template + +This template captures all the information that a partner should fill out when proposing a new API (or API family) to CAMARA. + +### API family name + +CAMARA TrustWorthiness INTENT API. + +### API family owner + +National Centre for Scientific Research Demokritos (NCSRD) +and Infolysis P.C. + +### API summary + +A Trustworthiness Intent API enabling developers and applications to request and +monitor trust guarantees (security, privacy, reliability, resilience,safety) as +high-level intents without specifying low-level configurations. + +### Technical viability + +No network/cloud capabilities required. The API's bussiness logic is supported through an open-source +AI-native trust orchestrator acts as the backend to produce trust scores to feed them in the correspondent network. + +### Commercial viability + +An open-source implementation is used called Cognitive Coordinator (CoCo), that is, an AI-native trust orchestrator. +It interprets user trust intents expressed in natural language and translates them into actionable system configurations, +dynamically computing a Level of Trustworthiness (LoT) that aligns with both semantic intent and real-world resource constraints. + +This is part of the SAFE-6G European Horizon project. (https://safe-6g.eu/) + +### YAML code available? + +YES + +### Validated in lab/productive environments? + +YES, lab network. + +### Validated with real customers? + +NO + +### Validated with operators? + +NO + +### Supporters in API Backlog Working Group + +List of supporters. +_NOTE: That shall be added by the Working Group. Supporting an API proposal means that the supporting company must provide at least 1 (one) Maintainer at the time of the Sub Project creation._ diff --git a/documentation/SupportingDocuments/camara_trustworthiness_intent_api.yaml b/documentation/SupportingDocuments/camara_trustworthiness_intent_api.yaml new file mode 100644 index 0000000..cb06981 --- /dev/null +++ b/documentation/SupportingDocuments/camara_trustworthiness_intent_api.yaml @@ -0,0 +1,313 @@ +openapi: 3.1.0 +info: + title: CAMARA Trustworthiness Intent API (TWIA) + description: | + CAMARA proposal for a Trustworthiness Intent API enabling developers and applications + to request and monitor trust guarantees (security, privacy, reliability, resilience, + safety) as high-level intents without specifying low-level configurations. + version: 0.1.0 + +servers: + - url: "{apiRoot}/api.example.com/v1" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + +tags: + - name: Intent + description: Manage trustworthiness intents + +paths: + /intents: + post: + tags: [Intent] + summary: Create a trustworthiness intent + operationId: createTrustIntent + requestBody: + required: true + content: + "application/json": + schema: + $ref: "#/components/schemas/TrustIntentCreate" + examples: + INTENT_INPUT: + summary: "Example Trustworthiness Intent" + description: "A request containing multiple trustworthiness categories." + value: + type: TrustworthinessIntent + serviceId: MyChatbotApp + data: + - label: Privacy + text: Ensure privacy requirements are accurate for location data sharing. + - label: Security + text: Verify every device accessing the network. + - label: Reliability + text: Take measures to ensure stability. + - label: Resilience + text: Can you guarantee fault tolerance for financial services. + - label: Safety + text: Implement safe data access and sharing policies. + responses: + "200": + description: Intent result + content: + application/json: + schema: + $ref: "#/components/schemas/TrustIntentResponse" + examples: + INTENT_RESPONSE: + $ref: "#/components/examples/INTENT_RESPONSE" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + security: + - openId: + - trustworthiness-intent:create +components: + securitySchemes: + openId: + description: OpenID Connect authentication + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + schemas: + Intent: + type: object + properties: + type: + type: string + description: A label identifying the specific type of intent. + serviceId: + type: string + description: A unique ID correlating the service that request the intent. + required: + - type + discriminator: + propertyName: type + mapping: + TrustworthinessIntent: "#/components/schemas/TrustIntentCreate" + TrustIntentCreate: + allOf: + - $ref: "#/components/schemas/Intent" + - type: object + properties: + type: + type: string + description: The intent Type, in our case TrustWorthinessIntent. + const: TrustworthinessIntent + data: + type: array + description: List of intent segments, each with a category label and the corresponding text. + minItems: 1 + items: + $ref: "#/components/schemas/TrustIntentTargets" + required: + - data + TrustIntentResponse: + type: object + properties: + assetId: + type: string + data: + type: array + description: List of intent scores, each with a category label and a corresponding score. + minItems: 1 + items: + $ref: "#/components/schemas/TrustScoresResponse" + overall_trustworthiness_level: + type: number + description: The average trustworthiness level after summing up the individual scores. + minimum: 0.0 + maximum: 1.0 + required: + - assetId + - data + - overall_trustworthiness_level + TrustIntentTargets: + type: object + description: Trustworthiness objectives + properties: + label: + type: string + description: The high-level intent category (e.g., Security, Privacy, Reliability). + enum: [Security, Privacy, Reliability, Resilience, Safety] + text: + type: string + description: The natural language statement from the user/chatbot about that category. + minLength: 2 + required: + - label + - text + TrustScoresResponse: + type: object + description: Trustworthiness score + properties: + label: + type: string + description: The high-level intent category (e.g., Security, Privacy, Reliability). + enum: [Security, Privacy, Reliability, Resilience, Safety] + score: + type: number + description: The score of an intent category. + minimum: 0.0 + maximum: 1.0 + required: + - label + - score + ErrorInfo: + description: Common schema for errors + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: A human-readable code to describe the error + message: + type: string + description: A human-readable description of what the event represents + responses: + Generic400: + description: Bad Request + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + examples: + GENERIC_400_INVALID_ARGUMENT: + summary: Invalid argument + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + Generic401: + description: Unauthorized + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - UNAUTHENTICATED + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated and a new authentication is required + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. + Generic403: + description: Forbidden + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + examples: + GENERIC_403_PERMISSION_DENIED: + summary: Permission denied + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + Generic404: + description: Not found + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - IDENTIFIER_NOT_FOUND + examples: + GENERIC_404_IDENTIFIER_NOT_FOUND: + summary: Identifier not found + description: Some identifier cannot be matched. + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Identifier not found. + Generic422: + description: Unprocessable Content + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - MISSING_IDENTIFIER + - UNSUPPORTED_IDENTIFIER + examples: + GENERIC_422_MISSING_IDENTIFIER: + summary: Missing required identifier + description: Some identifier is missing. + value: + status: 422 + code: MISSING_IDENTIFIER + message: Identifier is missing. + examples: + INTENT_RESPONSE: + description: The score that will feed the network perform configuration after the intent. + value: + assetId: chatbot application + data: + - label: Privacy + score: 0.7 + - label: Security + score: 0.85 + - label: Reliability + score: 0.9 + - label: Resilience + score: 0.95 + - label: Safety + score: 0.83 + overall_trustworthiness_level: 0.85