Components proposal #51

shaisachs · 2023-04-26T16:26:33Z

Addresses #43

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

…er example of a workflow input Signed-off-by: Shai Sachs <shaisachs@gmail.com>

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

handrews · 2023-05-19T14:33:19Z

versions/1.0.0.md

@@ -257,7 +257,7 @@ Field Name | Type | Description
 <a name="workflowId"></a>workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows document. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions.
 <a name="workflowSummary"></a>summary | `string` | A summary of the purpose or objective of the workflow.
 <a name="workflowDescription"></a>description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-<a name="workflowInputs"></a>inputs | `JSON Schema` or `string` | A JSON Schema object representing the input parameters used by this workflow.  If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `inputs` field.
+<a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. Some of the input parameters may be [References](#reference-object) to the [[Component Object]](#component-object)'s `inputs` field.


If this proposal is trying for the same feel as OAS 3.1, then you don't need to talk about Reference Objects here. Reference Objects are used outside of Schema Objects, where $ref is not otherwise defined. The OAS 3.1 Schema Object is just a regular 2020-12 schema, and $ref is already defined with behavior specific to schemas (in terms of how adjacent keywords are handled).

Hmm ok, I can take out that sentence. I'll leave the example in though.

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

handrews · 2023-05-20T17:33:31Z

versions/1.0.0.md

+Field Name | Type | Description
+---|:---:|---
+<a name="referenceRef"></a>$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI, with a prefix of `#/components/inputs` or `#/components/parameters`.
+<a name="referenceValue"></a>value | `string` | The value of the Input or Parameter which by default SHOULD override that of the referenced component.


This is a dramatic departure from how $ref is used in every other specification I've seen, and will cause problems with anyone trying to use standard tooling. In particular, if this is done with $ref inside of schemas, you will not be able to use standard draft 2020-12 JSON Schema implementations, which was the main reason that OAS 3.1 adopted 2020-12 in full.

I'm kind of dropping in here without context- is there somewhere I can read up on the reason for this usage? don't see any discussion of it in the referenced issue.

Probably makes sense to discuss at our meeting this coming Wednesday, can you make it? Also, might be worth taking a look at the pet store example which I've marked up in this PR, that should at least convey the intention of this use of $ref. But certainly open to hearing improvements.

I'll try to make the meeting. My main concern here is that this proposal seems to be a bit disconnected from the general history and usage of $ref. Support for $ref has been a challenge in the OAS tooling community, and has often been addressed by having standalone tools that understand $ref which are used in conjunction with OAS-specific tools. Adding substantially different behavior to $ref will break many, many things.

darrelmiller · 2023-05-20T22:42:20Z

versions/1.0.0.md

+```json
+"components": {
+  "inputs": {
+    "storeId": {


These examples seem to be backwards no? Isn't input a JSON Schema and parameter has the the name, in value property?

Hmm - components.inputs is a Map of string to JSON Schema object, so I'm reasonably sure that piece is right (in this case storeId is the key). Not sure I understand the problem with parameter.

shaisachs · 2023-05-24T16:06:00Z

versions/1.0.0.md

-<a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema object representing the input parameters used by this workflow
-<a name="workflowSteps"></a>steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow
+<a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
+<a name="workflowSteps"></a>steps | [[Step Object](#step-object) | [Reference Object](#reference-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step.


Yeah I thought we were knocking out Steps in favor of just using Workflows as the unit of reuse. My pet store example shows how to do that.

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

versions/1.0.0.md

frankkilcommins · 2023-06-07T15:57:36Z

versions/1.0.0.md

+
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow document.
+
+Field Name Examples:


I'm not sure what the field name examples are representing here. We don't have this in other sections

It's just a regex for the keys in the Maps - happy to remove this section but I figured it'd be a good idea.

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

versions/1.0.0.md

reverting steps back to original description

versions/1.0.0.md

I do not see why we would not allow extensibility here if so desired by authors.

missed Reference object review

versions/1.0.0.md

…r-enrichment

shaisachs added 2 commits April 26, 2023 10:00

Add components facility (OAI#43)

a408a36

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

add credit

6a42a02

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

shaisachs changed the title ~~Components proposal (addresses #43)~~ Components proposal Apr 26, 2023

shaisachs added 6 commits April 28, 2023 15:18

pagination is a better example of an operation param; store is a bett…

254b277

…er example of a workflow input Signed-off-by: Shai Sachs <shaisachs@gmail.com>

add and consume reference object

b7844a0

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

add example of reusing steps and parameters

9fbf292

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

fix components row

dd367b9

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

add overridable value property (OAI#43)

d556b2b

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

allow input refs (OAI#43)

5946142

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

handrews reviewed May 19, 2023

View reviewed changes

shaisachs added 2 commits May 20, 2023 06:36

remove mention of references in workflowinputs (OAI#43)

c627f16

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

unwind components in steps; use reusable workflows

9d45822

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

handrews reviewed May 20, 2023

View reviewed changes

darrelmiller reviewed May 20, 2023

View reviewed changes

shaisachs commented May 24, 2023

View reviewed changes

update example to use JSON Schema more correctly

9f553c8

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

frankkilcommins reviewed Jun 7, 2023

View reviewed changes

versions/1.0.0.md Outdated Show resolved Hide resolved

frankkilcommins reviewed Jun 7, 2023

View reviewed changes

fix formatting, more standard component description

27b3bfa

Signed-off-by: Shai Sachs <shaisachs@gmail.com>

frankkilcommins reviewed Jul 5, 2023

View reviewed changes

versions/1.0.0.md Outdated Show resolved Hide resolved

Update versions/1.0.0.md

d965fbb

reverting steps back to original description

frankkilcommins reviewed Jul 5, 2023

View reviewed changes

versions/1.0.0.md Outdated Show resolved Hide resolved

Update versions/1.0.0.md

f810363

I do not see why we would not allow extensibility here if so desired by authors.

frankkilcommins previously approved these changes Jul 5, 2023

View reviewed changes

frankkilcommins reviewed Jul 5, 2023

View reviewed changes

versions/1.0.0.md Outdated Show resolved Hide resolved

typo in reference object section

d0d9015

frankkilcommins approved these changes Jul 5, 2023

View reviewed changes

Merge branch 'draft-version-minor-enrichment' into draft-version-mino…

d59e165

…r-enrichment

frankkilcommins merged commit 76ff21e into OAI:draft-version-minor-enrichment Jul 5, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Components proposal #51

Components proposal #51

shaisachs commented Apr 26, 2023 •

edited

Loading

handrews May 19, 2023

shaisachs May 20, 2023

handrews May 20, 2023

shaisachs May 20, 2023

handrews May 20, 2023

darrelmiller May 20, 2023

shaisachs Jun 8, 2023

shaisachs May 24, 2023

frankkilcommins Jun 7, 2023

shaisachs Jun 8, 2023


		All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow document.

		Field Name Examples:

Components proposal #51

Components proposal #51

Conversation

shaisachs commented Apr 26, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shaisachs commented Apr 26, 2023 •

edited

Loading