From dba04fa2c3e063e253bc5de0d2b0ffd412b8719f Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Mon, 29 Apr 2024 20:28:41 +0200 Subject: [PATCH 1/3] feat: add support for structured log info --- .../workflow_execution_service.openapi.yaml | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/openapi/workflow_execution_service.openapi.yaml b/openapi/workflow_execution_service.openapi.yaml index 025b7d5..814a04b 100644 --- a/openapi/workflow_execution_service.openapi.yaml +++ b/openapi/workflow_execution_service.openapi.yaml @@ -821,6 +821,59 @@ components: outputs: type: object description: The outputs from the workflow run. + LogType: + title: LogType + enum: + - WRROC_PROCESS + - WRROC_WORKFLOW + - WRROC_PROV + type: string + nullable: true + description: > + Supported models and schemes for describing the shape of structured logging information. Can take any of the following values: + + + WRROC_PROCESS: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Process Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/process_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + + WRROC_WORKFLOW: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Workflow Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/workflow_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + + WRROC_PROV: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Provenance Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/provenance_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + + null: Use if your preferred logging scheme is not explicitly supported. In that case, make sure to provide documentation for client implementations in `StructuredLog.doc_url` + StructuredLog: + title: StructuredLog + type: object + properties: + log_type: + $ref: '#/components/schemas/LogType' + log_type_version: + type: string + description: Version of `log_type` model or schema. + logs: + oneOf: + - type: string + - type: array + items: {} + - type: object + description: >- + Structured log message content. Whether one or more log messages are used and whether + these represent strings or more complex objects depends on the log type (see `spec_url` + and/or `doc_url` for additional details). + spec_url: + type: string + description: >- + A URL pointing to the specification describing the `log_type` model or schema. At least + one of `spec_url` and `doc_url` should always be provided if `log_type` is `null`. + doc_url: + type: string + description: >- + A web page URL with human-readable documentation for client implementers on how to + interpret `logs`. At least one of `spec_url` and `doc_url` should always be provided if + `log_type` is `null`. + required: + - log_type + - log_type_version + - logs + description: Log information whose shape is described by a defined model or schema. Log: title: Log type: object @@ -849,6 +902,11 @@ components: type: integer description: Exit code of the program format: int32 + structured_logs: + type: array + items: + $ref: '#/components/schemas/StructuredLog' + description: Structured log information whose shape is described by one or more defined models or schemas. system_logs: type: array items: From fc05363adabf57c3b383e5d48c96dcd382a196df Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Mon, 29 Apr 2024 21:22:55 +0200 Subject: [PATCH 2/3] Clarifications --- openapi/workflow_execution_service.openapi.yaml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/openapi/workflow_execution_service.openapi.yaml b/openapi/workflow_execution_service.openapi.yaml index 814a04b..b88e544 100644 --- a/openapi/workflow_execution_service.openapi.yaml +++ b/openapi/workflow_execution_service.openapi.yaml @@ -832,13 +832,13 @@ components: description: > Supported models and schemes for describing the shape of structured logging information. Can take any of the following values: - + WRROC_PROCESS: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Process Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/process_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + WRROC_PROCESS: Workflow Run RO-Crate Process Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/process_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + WRROC_WORKFLOW: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Workflow Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/workflow_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + WRROC_WORKFLOW: Workflow Run RO-Crate Workflow Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/workflow_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + WRROC_PROV: Expects a single string item in `StructuredLog.logs` that represents a valid Workflow Run RO-Crate Provenance Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/provenance_run_crate) of the version indicated in `StructuredLog.log_type_version`. + + WRROC_PROV: Workflow Run RO-Crate Provenance Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/provenance_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + null: Use if your preferred logging scheme is not explicitly supported. In that case, make sure to provide documentation for client implementations in `StructuredLog.doc_url` + + null: Use if your preferred logging scheme is not explicitly supported. In that case, make sure to provide sufficient documentation for client implementers to parse the log information in the web page referred to by `StructuredLog.doc_url`. StructuredLog: title: StructuredLog type: object @@ -856,8 +856,10 @@ components: - type: object description: >- Structured log message content. Whether one or more log messages are used and whether - these represent strings or more complex objects depends on the log type (see `spec_url` - and/or `doc_url` for additional details). + these represent strings or more complex objects depends on the log type. Log messages + can also contain URLs that point to web sites that host the actual log contents. See + the `LogType` description and `spec_url` and/or `doc_url` for additional details on + how the contents of a given log format are mapped to this property. spec_url: type: string description: >- From 52aadc2f40f8d13c136ef04b8023b10f5cd61bf5 Mon Sep 17 00:00:00 2001 From: Alex Kanitz Date: Mon, 29 Apr 2024 21:26:39 +0200 Subject: [PATCH 3/3] typos and refactoring --- openapi/workflow_execution_service.openapi.yaml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/openapi/workflow_execution_service.openapi.yaml b/openapi/workflow_execution_service.openapi.yaml index b88e544..99b8adf 100644 --- a/openapi/workflow_execution_service.openapi.yaml +++ b/openapi/workflow_execution_service.openapi.yaml @@ -825,20 +825,24 @@ components: title: LogType enum: - WRROC_PROCESS - - WRROC_WORKFLOW - WRROC_PROV + - WRROC_WORKFLOW type: string nullable: true description: > Supported models and schemes for describing the shape of structured logging information. Can take any of the following values: - + WRROC_PROCESS: Workflow Run RO-Crate Process Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/process_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. + + WRROC_PROCESS: Workflow Run RO-Crate Process Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/process_run_crate). + Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + WRROC_WORKFLOW: Workflow Run RO-Crate Workflow Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/workflow_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. + + WRROC_PROV: Workflow Run RO-Crate Provenance Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/provenance_run_crate). + Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + WRROC_PROV: Workflow Run RO-Crate Provenance Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/provenance_run_crate). Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. + + WRROC_WORKFLOW: Workflow Run RO-Crate Workflow Run Crate (https://www.researchobject.org/workflow-run-crate/profiles/workflow_run_crate). + Expects a single serialized JSON-LD string item in `StructuredLog.logs` that conforms to the profile version indicated in `StructuredLog.log_type_version`. - + null: Use if your preferred logging scheme is not explicitly supported. In that case, make sure to provide sufficient documentation for client implementers to parse the log information in the web page referred to by `StructuredLog.doc_url`. + + null: Use if your preferred logging scheme is not explicitly supported. + In that case, make sure to provide sufficient documentation for client implementers to parse the log information in the web page referred to by `StructuredLog.doc_url`. StructuredLog: title: StructuredLog type: object @@ -875,7 +879,7 @@ components: - log_type - log_type_version - logs - description: Log information whose shape is described by a defined model or schema. + description: Log information whose shape is described by a defined model or schema. Log: title: Log type: object