[API Proposal] TrustWorthiness Intent API #293

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._

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