Skip to content

Commit 377c656

Browse files
panos-ecepanos-ece
committed
[API Proposal] TrustWorthiness Intent API #293
- OpenAPI schema as supporting document for TrustWorthiness Intent API - API proposal template
1 parent 79c13ae commit 377c656

File tree

2 files changed

+387
-0
lines changed

2 files changed

+387
-0
lines changed

‎documentation/API proposals/TrustWorthiness_Intent_API_proposal.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# API Proposal Template
2+
3+
This template captures all the information that a partner should fill out when proposing a new API (or API family) to CAMARA.
4+
5+
### API family name
6+
7+
Name of the API or API family.
8+
9+
CAMARA TrustWorthiness INTENT API.
10+
11+
### API family owner
12+
13+
Company submitting the API proposal.
14+
15+
National Centre for Scientific Research Demokritos (NCSRD)
16+
and Infolysis S.A.
17+
18+
### API summary
19+
20+
High level description / scope of the API or API family, and two/three examples of in-scope business cases.
21+
22+
A Trustworthiness Intent API enabling developers and applications to request and
23+
monitor trust guarantees (security, privacy, reliability, resilience,safety) as
24+
high-level intents without specifying low-level configurations.
25+
26+
### Technical viability
27+
28+
Identify the underlying network/cloud capabilities which are needed for the support of this API or API family, relating these capabilities to standards maturity.
29+
_Example: this API requires the availability of NEF with this Rel-15 "X" feature._
30+
31+
No network/cloud capabilities required. The API's bussiness logic is supported through an open-source
32+
AI-native trust orchestrator acts as the backend to produce trust scores to feed them in the correspondent network.
33+
34+
### Commercial viability
35+
36+
Specify the availability of commercial or (industrialized) open-source solutions for the identified network/cloud capabilities.
37+
_NOTE: If open-source, provide a publicly available reference/link to the actual solution, and specify the version under consideration._
38+
39+
An open-source implementation is used called Cognitive Coordinator (CoCo), that is, an AI-native trust orchestrator.
40+
It interprets user trust intents expressed in natural language and translates them into actionable system configurations,
41+
dynamically computing a Level of Trustworthiness (LoT) that aligns with both semantic intent and real-world resource constraints.
42+
43+
This is part of the SAFE-6G European Horizon project. (https://safe-6g.eu/)
44+
45+
### YAML code available?
46+
47+
YES / NO.
48+
YES
49+
50+
### Validated in lab/productive environments?
51+
52+
YES / NO.
53+
If YES, specify if it was lab network or productive network.
54+
55+
YES, lab network.
56+
57+
### Validated with real customers?
58+
59+
YES / NO.
60+
If YES, specify how many customers participated in the evaluation, and what their use cases were.
61+
_NOTE: It is not mandatory (though recommendable) to specify the name of the customers._
62+
NO
63+
64+
### Validated with operators?
65+
66+
YES / NO.
67+
If YES, specify how many operators participated in the evaluation.
68+
_NOTE: It is not mandatory (though recommendable) to specify the name of the operators._
69+
NO
70+
71+
### Supporters in API Backlog Working Group
72+
73+
List of supporters.
74+
_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‎

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
openapi: 3.1.0
2+
info:
3+
title: CAMARA Trustworthiness Intent API (TWIA)
4+
description: |
5+
CAMARA proposal for a Trustworthiness Intent API enabling developers and applications
6+
to request and monitor trust guarantees (security, privacy, reliability, resilience,
7+
safety) as high-level intents without specifying low-level configurations.
8+
version: 0.1.0
9+
10+
servers:
11+
- url: "{apiRoot}/api.example.com/v1"
12+
variables:
13+
apiRoot:
14+
default: http://localhost:9091
15+
description: API root
16+
17+
tags:
18+
- name: Intent
19+
description: Manage trustworthiness intents
20+
21+
paths:
22+
/intents:
23+
post:
24+
tags: [Intent]
25+
summary: Create a trustworthiness intent
26+
operationId: createTrustIntent
27+
requestBody:
28+
required: true
29+
content:
30+
"application/json":
31+
schema:
32+
$ref: "#/components/schemas/TrustIntentCreate"
33+
examples:
34+
INTENT_INPUT:
35+
summary: "Example Trustworthiness Intent"
36+
description: "A request containing multiple trustworthiness categories."
37+
value:
38+
type: TrustworthinessIntent
39+
serviceId: MyChatbotApp
40+
data:
41+
- label: Privacy
42+
text: Ensure privacy requirements are accurate for location data sharing.
43+
- label: Security
44+
text: Verify every device accessing the network.
45+
- label: Reliability
46+
text: Take measures to ensure stability.
47+
- label: Resilience
48+
text: Can you guarantee fault tolerance for financial services.
49+
- label: Safety
50+
text: Implement safe data access and sharing policies.
51+
responses:
52+
"200":
53+
description: Intent result
54+
content:
55+
application/json:
56+
schema:
57+
$ref: "#/components/schemas/TrustIntentResponse"
58+
examples:
59+
INTENT_RESPONSE:
60+
$ref: "#/components/examples/INTENT_RESPONSE"
61+
"400":
62+
$ref: "#/components/responses/Generic400"
63+
"401":
64+
$ref: "#/components/responses/Generic401"
65+
"403":
66+
$ref: "#/components/responses/Generic403"
67+
"404":
68+
$ref: "#/components/responses/Generic404"
69+
"422":
70+
$ref: "#/components/responses/Generic422"
71+
security:
72+
- openId:
73+
- trustworthiness-intent:create
74+
components:
75+
securitySchemes:
76+
openId:
77+
description: OpenID Connect authentication
78+
type: openIdConnect
79+
openIdConnectUrl: https://example.com/.well-known/openid-configuration
80+
schemas:
81+
Intent:
82+
type: object
83+
properties:
84+
type:
85+
type: string
86+
description: A label identifying the specific type of intent.
87+
serviceId:
88+
type: string
89+
description: A unique ID correlating the service that request the intent.
90+
required:
91+
- type
92+
discriminator:
93+
propertyName: type
94+
mapping:
95+
TrustworthinessIntent: "#/components/schemas/TrustIntentCreate"
96+
TrustIntentCreate:
97+
allOf:
98+
- $ref: "#/components/schemas/Intent"
99+
- type: object
100+
properties:
101+
type:
102+
type: string
103+
description: The intent Type, in our case TrustWorthinessIntent.
104+
const: TrustworthinessIntent
105+
data:
106+
type: array
107+
description: List of intent segments, each with a category label and the corresponding text.
108+
minItems: 1
109+
items:
110+
$ref: "#/components/schemas/TrustIntentTargets"
111+
required:
112+
- data
113+
TrustIntentResponse:
114+
type: object
115+
properties:
116+
assetId:
117+
type: string
118+
data:
119+
type: array
120+
description: List of intent scores, each with a category label and a corresponding score.
121+
minItems: 1
122+
items:
123+
$ref: "#/components/schemas/TrustScoresResponse"
124+
overall_trustworthiness_level:
125+
type: number
126+
description: The average trustworthiness level after summing up the individual scores.
127+
minimum: 0.0
128+
maximum: 1.0
129+
required:
130+
- assetId
131+
- data
132+
- overall_trustworthiness_level
133+
TrustIntentTargets:
134+
type: object
135+
description: Trustworthiness objectives
136+
properties:
137+
label:
138+
type: string
139+
description: The high-level intent category (e.g., Security, Privacy, Reliability).
140+
enum: [Security, Privacy, Reliability, Resilience, Safety]
141+
text:
142+
type: string
143+
description: The natural language statement from the user/chatbot about that category.
144+
minLength: 2
145+
required:
146+
- label
147+
- text
148+
TrustScoresResponse:
149+
type: object
150+
description: Trustworthiness score
151+
properties:
152+
label:
153+
type: string
154+
description: The high-level intent category (e.g., Security, Privacy, Reliability).
155+
enum: [Security, Privacy, Reliability, Resilience, Safety]
156+
score:
157+
type: number
158+
description: The score of an intent category.
159+
minimum: 0.0
160+
maximum: 1.0
161+
required:
162+
- label
163+
- score
164+
ErrorInfo:
165+
description: Common schema for errors
166+
type: object
167+
required:
168+
- status
169+
- code
170+
- message
171+
properties:
172+
status:
173+
type: integer
174+
description: HTTP response status code
175+
code:
176+
type: string
177+
description: A human-readable code to describe the error
178+
message:
179+
type: string
180+
description: A human-readable description of what the event represents
181+
responses:
182+
Generic400:
183+
description: Bad Request
184+
content:
185+
application/json:
186+
schema:
187+
allOf:
188+
- $ref: "#/components/schemas/ErrorInfo"
189+
- type: object
190+
properties:
191+
status:
192+
enum:
193+
- 400
194+
code:
195+
enum:
196+
- INVALID_ARGUMENT
197+
examples:
198+
GENERIC_400_INVALID_ARGUMENT:
199+
summary: Invalid argument
200+
description: Invalid Argument. Generic Syntax Exception
201+
value:
202+
status: 400
203+
code: INVALID_ARGUMENT
204+
message: Client specified an invalid argument, request body or query param.
205+
Generic401:
206+
description: Unauthorized
207+
content:
208+
application/json:
209+
schema:
210+
allOf:
211+
- $ref: "#/components/schemas/ErrorInfo"
212+
- type: object
213+
properties:
214+
status:
215+
enum:
216+
- 401
217+
code:
218+
enum:
219+
- UNAUTHENTICATED
220+
examples:
221+
GENERIC_401_UNAUTHENTICATED:
222+
description: Request cannot be authenticated and a new authentication is required
223+
value:
224+
status: 401
225+
code: UNAUTHENTICATED
226+
message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
227+
Generic403:
228+
description: Forbidden
229+
content:
230+
application/json:
231+
schema:
232+
allOf:
233+
- $ref: "#/components/schemas/ErrorInfo"
234+
- type: object
235+
properties:
236+
status:
237+
enum:
238+
- 403
239+
code:
240+
enum:
241+
- PERMISSION_DENIED
242+
examples:
243+
GENERIC_403_PERMISSION_DENIED:
244+
summary: Permission denied
245+
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
246+
value:
247+
status: 403
248+
code: PERMISSION_DENIED
249+
message: Client does not have sufficient permissions to perform this action.
250+
Generic404:
251+
description: Not found
252+
content:
253+
application/json:
254+
schema:
255+
allOf:
256+
- $ref: "#/components/schemas/ErrorInfo"
257+
- type: object
258+
properties:
259+
status:
260+
enum:
261+
- 404
262+
code:
263+
enum:
264+
- IDENTIFIER_NOT_FOUND
265+
examples:
266+
GENERIC_404_IDENTIFIER_NOT_FOUND:
267+
summary: Identifier not found
268+
description: Some identifier cannot be matched.
269+
value:
270+
status: 404
271+
code: IDENTIFIER_NOT_FOUND
272+
message: Identifier not found.
273+
Generic422:
274+
description: Unprocessable Content
275+
content:
276+
application/json:
277+
schema:
278+
allOf:
279+
- $ref: "#/components/schemas/ErrorInfo"
280+
- type: object
281+
properties:
282+
status:
283+
enum:
284+
- 422
285+
code:
286+
enum:
287+
- MISSING_IDENTIFIER
288+
- UNSUPPORTED_IDENTIFIER
289+
examples:
290+
GENERIC_422_MISSING_IDENTIFIER:
291+
summary: Missing required identifier
292+
description: Some identifier is missing.
293+
value:
294+
status: 422
295+
code: MISSING_IDENTIFIER
296+
message: Identifier is missing.
297+
examples:
298+
INTENT_RESPONSE:
299+
description: The score that will feed the network perform configuration after the intent.
300+
value:
301+
assetId: chatbot application
302+
data:
303+
- label: Privacy
304+
score: 0.7
305+
- label: Security
306+
score: 0.85
307+
- label: Reliability
308+
score: 0.9
309+
- label: Resilience
310+
score: 0.95
311+
- label: Safety
312+
score: 0.83
313+
overall_trustworthiness_level: 0.85

0 commit comments

Comments
 (0)