494 lines
16 KiB
YAML
494 lines
16 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: SD Tooling API
|
|
description: |-
|
|
The APIs described in the following document enable the management
|
|
of the lifecycle for creating a Resource Description on the provider side, including
|
|
its publication on the federated catalogue. The available APIs allow to define
|
|
access and usage policies, specify the Resource Address on the provider side,
|
|
and manage the validation and publication process on the federated catalogue.
|
|
|
|
## Business Context
|
|
|
|
The API facilitates the creation and management of Resource Descriptions in a federated data space. It enables providers to publish metadata about their data assets on a federated catalogue, define access and usage policies, and manage the validation and publication workflow. This supports discoverability and interoperability across the data ecosystem.
|
|
|
|
|
|
### Key Actors
|
|
|
|
- **Provider**: Creates and publishes Resource Descriptions, defines policies, and manages validation.
|
|
|
|
- **Governance Authority**: Hosts the Federated Catalogue
|
|
|
|
### Typical Flow
|
|
|
|
1. Create a Resource Description.
|
|
|
|
2. Define access and usage policies.
|
|
|
|
3. Specify the Resource Address.
|
|
|
|
4. Submit the Resource Description for validation
|
|
|
|
5. Publish the Resource Description on the federated catalogue
|
|
contact:
|
|
name: Simpl Programme
|
|
url: https://simpl-programme.ec.europa.eu/
|
|
email: cnect-simpl@ec.europa.eu
|
|
license:
|
|
name: European Union Public License (EUPL) 1.2
|
|
url: https://interoperable-europe.ec.europa.eu/sites/default/files/custom-page/attachment/eupl_v1.2_en.pdf
|
|
version: "1.0"
|
|
servers:
|
|
- url: https://creation-wizard-api.dev.simpl-europe.eu/v2
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/selfDescriptions/enriched:
|
|
post:
|
|
tags:
|
|
- Self Description
|
|
summary: Enriches and validates a self-description using the provided metadata and additional properties
|
|
description: Adds hashing, registers asset and policies into the provider EDC, creates a contract definition on EDC connector and validates the resulting SD json enriched with all info. Allows passing additional properties via a JSON string.
|
|
operationId: enrichAndValidate
|
|
parameters:
|
|
- name: schemaId
|
|
in: query
|
|
description: schemaId
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: data-dataSchema1
|
|
- name: templateId
|
|
in: query
|
|
description: resource address template id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 1
|
|
requestBody:
|
|
description: Request body containing SD JSON-LD and additional properties
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- properties
|
|
- sdJson
|
|
type: object
|
|
example:
|
|
sdJson:
|
|
'@context': http://www.w3.org/ns/odrl.jsonld
|
|
'@type': Set
|
|
assigner:
|
|
role: http://www.w3.org/ns/odrl/2/assigner
|
|
uid: provider
|
|
permission:
|
|
- action:
|
|
- http://simpl.eu/odrl/actions/search
|
|
assignee:
|
|
role: http://www.w3.org/ns/odrl/2/assignee
|
|
uid: CONSUMER
|
|
constraint:
|
|
- leftOperand: http://www.w3.org/ns/odrl/2/dateTime
|
|
operator: http://www.w3.org/ns/odrl/2/gteq
|
|
rightOperand: 2024-08-01T00:00:00Z
|
|
- leftOperand: http://www.w3.org/ns/odrl/2/dateTime
|
|
operator: http://www.w3.org/ns/odrl/2/lteq
|
|
rightOperand: 2024-08-31T23:59:59Z
|
|
target: ""
|
|
profile: http://www.w3.org/ns/odrl/2/odrl.jsonld
|
|
target: ""
|
|
uid: 68777919-f260-4305-9c41-d4266ac0a639
|
|
properties:
|
|
resourceAddressTemplateId: TPL-1
|
|
customProperty2: 42
|
|
required: true
|
|
responses:
|
|
"400":
|
|
description: Bad Request
|
|
content:
|
|
application/problem+json:
|
|
examples:
|
|
Bad Request Error Example:
|
|
description: Bad Request Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:validationError
|
|
title: Parameter validation error
|
|
status: 400
|
|
detail: One or more parameters are invalid
|
|
issues:
|
|
- type: urn:problem-type:simpl:invalidParameter
|
|
title: Invalid parameter
|
|
detail: The schemaId parameter must meet specific criteria
|
|
in: query
|
|
name: schemaId
|
|
value: invalidValue
|
|
"500":
|
|
description: Internal Server Error
|
|
content:
|
|
application/problem+json:
|
|
examples:
|
|
Internal Server Error Example:
|
|
description: Internal Server Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:internalServerError
|
|
title: Internal Server Error
|
|
status: 500
|
|
detail: Unexpected internal error
|
|
instance: /selfDescriptions/enriched
|
|
"200":
|
|
description: Successfully enriched and validated SD JSON-LD
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
SD json file enriched and validated:
|
|
description: SD json file enriched and validated
|
|
value:
|
|
'@context': http://www.w3.org/ns/odrl.jsonld
|
|
'@type': Set
|
|
assigner:
|
|
role: http://www.w3.org/ns/odrl/2/assigner
|
|
uid: provider
|
|
permission:
|
|
- action:
|
|
- http://simpl.eu/odrl/actions/search
|
|
assignee:
|
|
role: http://www.w3.org/ns/odrl/2/assignee
|
|
uid: CONSUMER
|
|
constraint:
|
|
- leftOperand: http://www.w3.org/ns/odrl/2/dateTime
|
|
operator: http://www.w3.org/ns/odrl/2/gteq
|
|
rightOperand: 2024-08-01T00:00:00Z
|
|
- leftOperand: http://www.w3.org/ns/odrl/2/dateTime
|
|
operator: http://www.w3.org/ns/odrl/2/lteq
|
|
rightOperand: 2024-08-31T23:59:59Z
|
|
target: ""
|
|
profile: http://www.w3.org/ns/odrl/2/odrl.jsonld
|
|
target: ""
|
|
uid: 68777919-f260-4305-9c41-d4266ac0a639
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/problem+json:
|
|
examples:
|
|
Unauthorized Error Example:
|
|
description: Unauthorized Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:unauthorized
|
|
title: Unauthorized
|
|
status: 401
|
|
detail: Missing or invalid Authorization header
|
|
instance: /selfDescriptions/enriched
|
|
"406":
|
|
description: Not Acceptable
|
|
content:
|
|
application/problem+json:
|
|
examples:
|
|
Not Acceptable Error Example:
|
|
description: Not Acceptable Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:notAcceptable
|
|
title: Not Acceptable
|
|
status: 406
|
|
detail: The requested media type could not be provided
|
|
instance: /selfDescriptions/enriched
|
|
"415":
|
|
description: Unsupported Media Type
|
|
content:
|
|
application/problem+json:
|
|
examples:
|
|
Unsupported Media Type Error Example:
|
|
description: Unsupported Media Type Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:unsupportedMediaType
|
|
title: Unsupported Media Type
|
|
status: 415
|
|
detail: The media type in the request payload is unsupported
|
|
instance: /selfDescriptions/enriched
|
|
/schemas:
|
|
get:
|
|
tags:
|
|
- Schema
|
|
summary: List all available schema
|
|
description: Returns all schema info in order to allow them to be selected and initiate the self-description creation process.
|
|
operationId: getSchemas
|
|
responses:
|
|
"400":
|
|
description: Bad Request
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: '#/components/schemas/BadRequestProblem'
|
|
examples:
|
|
Bad Request Error Example:
|
|
description: Bad Request Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:badRequest
|
|
title: BadRequest
|
|
status: 400
|
|
detail: Missing or invalid arguments
|
|
"500":
|
|
description: Internal Server Error
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: '#/components/schemas/InternalServerErrorProblem'
|
|
examples:
|
|
Internal Server Error Example:
|
|
description: Internal Server Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:internalServerError
|
|
title: Internal Server Error
|
|
status: 500
|
|
detail: Unexpected internal error
|
|
"200":
|
|
description: A map of available TTL schema files
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SchemaMetadataWrapper'
|
|
examples:
|
|
Available schemas:
|
|
description: Available schemas
|
|
value:
|
|
schemas:
|
|
- title: Application Asset
|
|
name: health
|
|
description: Schema for describing a software application.
|
|
resourceType: APPLICATION
|
|
version: 1.0.0
|
|
schemaId: application-health
|
|
- title: Data Offering
|
|
name: Data offering
|
|
description: SHACL shape for data offering self-descriptions.
|
|
resourceType: DATA
|
|
version: 1.0.0
|
|
schemaId: data-offeringShape
|
|
No schemas available:
|
|
description: No schemas available for the current environment/tenant
|
|
value:
|
|
schemas: []
|
|
/schemas/{schemaId}/content:
|
|
get:
|
|
tags:
|
|
- Schema
|
|
summary: Returns schema content based on schemaId
|
|
description: Returns schema content for the specified schema identifier
|
|
operationId: getSchemaContent
|
|
parameters:
|
|
- name: schemaId
|
|
in: path
|
|
description: Identifier of the TTL schema
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Identifier of the schema
|
|
example: data-offeringShape
|
|
example: data-offeringShape
|
|
responses:
|
|
"400":
|
|
description: Bad Request
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: '#/components/schemas/BadRequestProblem'
|
|
examples:
|
|
Bad Request Error Example:
|
|
description: Bad Request Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:badRequest
|
|
title: BadRequest
|
|
status: 400
|
|
detail: Missing or invalid arguments
|
|
"500":
|
|
description: Internal Server Error
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: '#/components/schemas/InternalServerErrorProblem'
|
|
examples:
|
|
Internal Server Error Example:
|
|
description: Internal Server Error Example
|
|
value:
|
|
type: urn:problem-type:simpl:internalServerError
|
|
title: Internal Server Error
|
|
status: 500
|
|
detail: Unexpected internal error
|
|
"200":
|
|
description: TTL schema file content
|
|
content:
|
|
text/turtle:
|
|
schema:
|
|
type: string
|
|
examples:
|
|
ttlExample:
|
|
summary: Example TTL content
|
|
description: ttlExample
|
|
value: '@prefix ex: <http://example.org/> .'
|
|
"404":
|
|
description: Not Found
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotFoundProblem'
|
|
examples:
|
|
Not Found:
|
|
summary: Schema not found
|
|
description: Not Found
|
|
value:
|
|
type: schema-not-found
|
|
title: SCHEMA_NOT_FOUND
|
|
status: 404
|
|
detail: Schema not found
|
|
instance: /schemas
|
|
components:
|
|
schemas:
|
|
BadRequestProblem:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
format: uri
|
|
href:
|
|
type: string
|
|
format: uri
|
|
title:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
format: int32
|
|
detail:
|
|
type: string
|
|
instance:
|
|
type: string
|
|
format: uri
|
|
issues:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/InputValidationIssue'
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
InputObject:
|
|
type: object
|
|
properties:
|
|
in:
|
|
type: string
|
|
enum:
|
|
- body
|
|
- path
|
|
- query
|
|
- header
|
|
name:
|
|
type: string
|
|
value:
|
|
type: object
|
|
InputValidationIssue:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
format: uri
|
|
href:
|
|
type: string
|
|
format: uri
|
|
title:
|
|
type: string
|
|
detail:
|
|
type: string
|
|
in:
|
|
type: string
|
|
enum:
|
|
- body
|
|
- path
|
|
- query
|
|
- header
|
|
name:
|
|
type: string
|
|
value:
|
|
type: object
|
|
inputs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/InputObject'
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
InternalServerErrorProblem:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
format: uri
|
|
href:
|
|
type: string
|
|
format: uri
|
|
title:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
format: int32
|
|
detail:
|
|
type: string
|
|
instance:
|
|
type: string
|
|
format: uri
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
SchemaMetadata:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
title:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
version:
|
|
type: string
|
|
resourceType:
|
|
type: string
|
|
SchemaMetadataWrapper:
|
|
type: object
|
|
properties:
|
|
schemas:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SchemaMetadata'
|
|
NotFoundProblem:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
format: uri
|
|
href:
|
|
type: string
|
|
format: uri
|
|
title:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
format: int32
|
|
detail:
|
|
type: string
|
|
instance:
|
|
type: string
|
|
format: uri
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
description: IAA cloud gateway JWT token
|
|
scheme: bearer
|
|
bearerFormat: JWT
|