Skip to content

Commit

Permalink
chore: resolve ToC issues
Browse files Browse the repository at this point in the history
  • Loading branch information
@frankkilcommins
frankkilcommins committed Dec 20, 2023
1 parent 6070953 commit 62da6ba
Showing 1 changed file with 21 additions and 18 deletions.
39 changes: 21 additions & 18 deletions versions/1.0.0.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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)
Expand Down Expand Up @@ -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)
<!-- /TOC -->

## 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
Expand Down Expand Up @@ -691,7 +694,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
type: JSONPath
```

### <a name="runtimeExpressions"></a>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:
Expand All @@ -717,7 +720,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
```

##### <a name="runtimeExpressionExamples"></a>Examples
##### Examples

Source Location | example expression | notes
---|:---|:---|
Expand All @@ -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.


### <a name="specificationExtensions"></a>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.

Expand All @@ -748,19 +751,19 @@ 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).

## <a name="securityConsiderations"></a>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.

Workflows can be JSON or YAML values. As such, all security considerations defined in [RFC 8259](https://www.rfc-editor.org/info/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply.

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.

## <a name="iANAConsiderations"></a>IANA Considerations
## IANA Considerations

The proposed MIME media types for Workflows are described below.

### <a name="defaultMIMEType"></a>application/vnd.oai.workflows
### application/vnd.oai.workflows

The default (or general) MIME type for Workflows is defined as follows:

Expand All @@ -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

### <a name="jsonMIMEType"></a>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:

Expand All @@ -798,7 +801,7 @@ The proposed MIME media type for Workflows that require a JSON-specific media ty

&emsp; Interoperability considerations: N/A

### <a name="yamlMIMEType"></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:

Expand All @@ -816,14 +819,14 @@ The proposed MIME media type for Workflows that require a YAML-specific media ty

&emsp; Interoperability considerations: N/A

## <a name="revisionHistory"></a>Appendix A: Revision History
## Appendix A: Revision History

Version | Date | Notes
--- | --- | ---
1.0.0 | TBD | First release of the Workflows Specification


## <a name="contextualScopeImage"></a>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`

Expand Down

0 comments on commit 62da6ba

Please sign in to comment.