diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 06b9864..a4836e8 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -1,6 +1,6 @@ # Workflows Specification -#### Version 1.0.0 +## Version 1.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -16,11 +16,11 @@ The Workflows Specification can articulate these workflows in a human-readable a ## Table of Contents - [Workflows Specification](#workflows-specification) - - [Version 1.0.0](#version-100) + - [Version 1.0.0](#version-100) - [Introduction](#introduction) - [Table of Contents](#table-of-contents) - [Definitions](#definitions) - - [Workflows Description](#workflows-description) + - [Workflows Description](#workflows-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) @@ -55,20 +55,23 @@ The Workflows Specification can articulate these workflows in a human-readable a - [Component Object](#component-object) - [Fixed Fields](#fixed-fields-8) - [Component Object Example](#component-object-example) - - [Criterion Object](#criterion-object) - - [Fixed Fields](#fixed-fields-9) - - [Criterion Object Example](#criterion-object-example) - [Reference Object](#reference-object) - - [Fixed Fields](#fixed-fields-10) + - [Fixed Fields](#fixed-fields-9) - [Reference Object Example](#reference-object-example) + - [Criterion Object](#criterion-object) + - [Fixed Fields](#fixed-fields-10) + - [Criterion Object Example](#criterion-object-example) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) + - [Security Considerations](#security-considerations) + - [IANA Considerations](#iana-considerations) - [Appendix A: Revision History](#appendix-a-revision-history) + - [Appendix B: Contextual Scope Overview](#appendix-b-contextual-scope--access-for-inputs-and-outputs) ## Definitions -##### Workflows Description +### Workflows Description A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). A Workflows Description (WD) uses and conforms to the Workflows Specification, and `MUST` contain a valid Workflows Specification version field (`workflowsSpec`), an [Info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification @@ -691,7 +694,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens type: JSONPath ``` -### Runtime Expressions +### Runtime Expressions A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Workflows document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: @@ -717,7 +720,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` -##### Examples +##### Examples Source Location | example expression | notes ---|:---|:---| @@ -736,7 +739,7 @@ Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. -### Specification Extensions +### Specification Extensions While the Workflows Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. @@ -748,7 +751,7 @@ Field Pattern | Type | Description The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). -## Security Considerations +## Security Considerations The Workflows Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows. @@ -756,11 +759,11 @@ Workflows can be JSON or YAML values. As such, all security considerations defin Workflows are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing a workflow description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful. -## IANA Considerations +## IANA Considerations The proposed MIME media types for Workflows are described below. -### application/vnd.oai.workflows +### application/vnd.oai.workflows The default (or general) MIME type for Workflows is defined as follows: @@ -780,7 +783,7 @@ The default (or general) MIME type for Workflows is defined as follows: **Note:** When using the `application/vnd.oai.workflows` media type the consumer should be prepared to receive YAML formatted content -### application/vnd.oai.workflows+json +### application/vnd.oai.workflows+json The proposed MIME media type for Workflows that require a JSON-specific media type is defined as follows: @@ -798,7 +801,7 @@ The proposed MIME media type for Workflows that require a JSON-specific media ty   Interoperability considerations: N/A -### application/vnd.oai.workflows+yaml +### application/vnd.oai.workflows+yaml The proposed MIME media type for Workflows that require a YAML-specific media type is defined as follows: @@ -816,14 +819,14 @@ The proposed MIME media type for Workflows that require a YAML-specific media ty   Interoperability considerations: N/A -## Appendix A: Revision History +## Appendix A: Revision History Version | Date | Notes --- | --- | --- 1.0.0 | TBD | First release of the Workflows Specification -## Appendix B: Contextual scope / access for inputs and outputs +## Appendix B: Contextual scope / access for inputs and outputs This quick image is to add some context / scope access overview for `inputs`, `step parameters`, `step outputs` and `workflow outputs`