Skip to content

Commit 2d30591

Browse files
jeremyfieljeremyfiel
committed
Merge branch 'v1.0.0-dev' into feat/markdown-lint-github-action
2 parents 38a9adc + 40742b2 commit 2d30591

File tree

6 files changed

+55
-53
lines changed

6 files changed

+55
-53
lines changed

‎.github/workflows/validate-markdown.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,6 @@ jobs:
2525
with:
2626
node-version: '20.x'
2727
- name: Validate markdown
28-
run: npx --yes mdv ./{versions,schemas/**}/*.md
28+
run: npx --yes mdv ./versions/[1-2].*.md
2929
- name: Lint markdown
30-
run: npx --yes markdownlint-cli --config .markdownlint.yaml ./{versions,schemas/**}/*.md
30+
run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/1.0.[^0].md versions/1.[1-9].*.md versions/2.*.md

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"scripts": {
66
"build": "bash ./scripts/md2html/build.sh",
77
"test": "echo \"Error: no test specified\" && exit 1",
8-
"format-markdown": "bash ./scripts/format-markdown.sh ./{versions,schemas/**}/*.md"
8+
"format-markdown": "bash ./scripts/format-markdown.sh versions/1.0.[^0].md versions/1.[1-9].*.md versions/2.*.md"
99
},
1010
"repository": {
1111
"type": "git",

‎schemas/v1.0/schema.json‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01",
33
"$schema": "https://json-schema.org/draft/2020-12/schema",
4-
"description": "The description of OpenAPI Initiative Arazzo v1.0.0 documents without schema validation, as defined by https://spec.openapis.org/arazzo/v1.0.0",
4+
"description": "The description of Arazzo v1.0.x documents",
55
"type": "object",
66
"properties": {
77
"arazzo": {
@@ -44,7 +44,7 @@
4444
"unevaluatedProperties": false,
4545
"$defs": {
4646
"info": {
47-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#info-object",
47+
"$comment": "https://spec.openapis.org/arazzo/v1.0#info-object",
4848
"description": "Provides metadata about the Arazzo description",
4949
"type": "object",
5050
"properties": {
@@ -73,7 +73,7 @@
7373
"unevaluatedProperties": false
7474
},
7575
"source-description-object": {
76-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#source-description-object",
76+
"$comment": "https://spec.openapis.org/arazzo/v1.0#source-description-object",
7777
"description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo description",
7878
"type": "object",
7979
"properties": {
@@ -103,7 +103,7 @@
103103
"unevaluatedProperties": false
104104
},
105105
"workflow-object": {
106-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#workflow-object",
106+
"$comment": "https://spec.openapis.org/arazzo/v1.0#workflow-object",
107107
"description": "Describes the steps to be taken across one or more APIs to achieve an objective",
108108
"type": "object",
109109
"properties": {
@@ -204,7 +204,7 @@
204204
"unevaluatedProperties": false
205205
},
206206
"step-object": {
207-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#step-object'",
207+
"$comment": "https://spec.openapis.org/arazzo/v1.0#step-object'",
208208
"description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)",
209209
"type": "object",
210210
"properties": {
@@ -371,7 +371,7 @@
371371
"unevaluatedProperties": false
372372
},
373373
"request-body-object": {
374-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#request-body-object",
374+
"$comment": "https://spec.openapis.org/arazzo/v1.0#request-body-object",
375375
"description": "The request body to pass to an operation as referenced by operationId or operationPath",
376376
"type": "object",
377377
"properties": {
@@ -393,7 +393,7 @@
393393
"unevaluatedProperties": false
394394
},
395395
"criterion-object": {
396-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#criterion-object",
396+
"$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object",
397397
"description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria",
398398
"type": "object",
399399
"properties": {
@@ -438,7 +438,7 @@
438438
"unevaluatedProperties": false
439439
},
440440
"criterion-expression-type-object": {
441-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#criterion-expression-type-object",
441+
"$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object",
442442
"description": "An object used to describe the type and version of an expression used within a Criterion Object",
443443
"type": "object",
444444
"properties": {
@@ -505,7 +505,7 @@
505505
"$ref": "#/$defs/specification-extensions"
506506
},
507507
"success-action-object": {
508-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#success-action-object",
508+
"$comment": "https://spec.openapis.org/arazzo/v1.0#success-action-object",
509509
"description": "A single success action which describes an action to take upon success of a workflow step",
510510
"type": "object",
511511
"properties": {
@@ -571,7 +571,7 @@
571571
"unevaluatedProperties": false
572572
},
573573
"failure-action-object": {
574-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#failure-action-object",
574+
"$comment": "https://spec.openapis.org/arazzo/v1.0#failure-action-object",
575575
"description": "A single failure action which describes an action to take upon failure of a workflow step",
576576
"type": "object",
577577
"properties": {
@@ -664,7 +664,7 @@
664664
"unevaluatedProperties": false
665665
},
666666
"reusable-object": {
667-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#reusable-object",
667+
"$comment": "https://spec.openapis.org/arazzo/v1.0#reusable-object",
668668
"description": "A simple object to allow referencing of objects contained within the Components Object",
669669
"type": "object",
670670
"properties": {
@@ -690,7 +690,7 @@
690690
"unevaluatedProperties": false
691691
},
692692
"parameter-object": {
693-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#parameter-object",
693+
"$comment": "https://spec.openapis.org/arazzo/v1.0#parameter-object",
694694
"description": "Describes a single step parameter",
695695
"type": "object",
696696
"properties": {
@@ -704,8 +704,7 @@
704704
"path",
705705
"query",
706706
"header",
707-
"cookie",
708-
"body"
707+
"cookie"
709708
]
710709
},
711710
"value": {
@@ -728,7 +727,7 @@
728727
"unevaluatedProperties": false
729728
},
730729
"payload-replacement-object": {
731-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#payload-replacement-object",
730+
"$comment": "https://spec.openapis.org/arazzo/v1.0#payload-replacement-object",
732731
"description": "Describes a location within a payload (e.g., a request body) and a value to set within the location",
733732
"type": "object",
734733
"properties": {
@@ -749,7 +748,7 @@
749748
"$ref": "#/$defs/specification-extensions"
750749
},
751750
"components-object": {
752-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#components-object",
751+
"$comment": "https://spec.openapis.org/arazzo/v1.0#components-object",
753752
"description": "Holds a set of reusable objects for different aspects of the Arazzo Specification",
754753
"type": "object",
755754
"properties": {
@@ -794,14 +793,14 @@
794793
"$ref": "#/$defs/specification-extensions"
795794
},
796795
"specification-extensions": {
797-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#specification-extensions",
796+
"$comment": "https://spec.openapis.org/arazzo/v1.0#specification-extensions",
798797
"description": "While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points",
799798
"patternProperties": {
800799
"^x-": true
801800
}
802801
},
803802
"schema": {
804-
"$comment": "https://spec.openapis.org/arazzo/v1.0.0#schema-object",
803+
"$comment": "https://spec.openapis.org/arazzo/v1.0#schema-object",
805804
"$ref": "https://json-schema.org/draft/2020-12/schema"
806805
}
807806
}

‎schemas/v1.0/schema.yaml‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
$id: 'https://spec.openapis.org/arazzo/1.0/schema/2024-08-01'
22
$schema: 'https://json-schema.org/draft/2020-12/schema'
33
description: |-
4-
The description of OpenAPI Initiative Arazzo v1.0.0 documents
5-
without schema validation, as defined by https://spec.openapis.org/arazzo/v1.0.0
4+
The description of Arazzo v1.0.x documents
65
type: object
76
properties:
87
arazzo:
@@ -36,7 +35,7 @@ $ref: '#/$defs/specification-extensions'
3635
unevaluatedProperties: false
3736
$defs:
3837
info:
39-
$comment: https://spec.openapis.org/arazzo/v1.0.0#info-object
38+
$comment: https://spec.openapis.org/arazzo/v1.0#info-object
4039
description: Provides metadata about the Arazzo description
4140
type: object
4241
properties:
@@ -58,7 +57,7 @@ $defs:
5857
$ref: '#/$defs/specification-extensions'
5958
unevaluatedProperties: false
6059
source-description-object:
61-
$comment: https://spec.openapis.org/arazzo/v1.0.0#source-description-object
60+
$comment: https://spec.openapis.org/arazzo/v1.0#source-description-object
6261
description: |-
6362
Describes a source description (such as an OpenAPI description)
6463
that will be referenced by one or more workflows described within
@@ -84,7 +83,7 @@ $defs:
8483
$ref: '#/$defs/specification-extensions'
8584
unevaluatedProperties: false
8685
workflow-object:
87-
$comment: https://spec.openapis.org/arazzo/v1.0.0#workflow-object
86+
$comment: https://spec.openapis.org/arazzo/v1.0#workflow-object
8887
description: Describes the steps to be taken across one or more APIs to achieve an objective
8988
type: object
9089
properties:
@@ -150,7 +149,7 @@ $defs:
150149
$ref: '#/$defs/specification-extensions'
151150
unevaluatedProperties: false
152151
step-object:
153-
$comment: https://spec.openapis.org/arazzo/v1.0.0#step-object'
152+
$comment: https://spec.openapis.org/arazzo/v1.0#step-object'
154153
description: |-
155154
Describes a single workflow step which MAY be a call to an
156155
API operation (OpenAPI Operation Object or another Workflow Object)
@@ -246,7 +245,7 @@ $defs:
246245
$ref: '#/$defs/specification-extensions'
247246
unevaluatedProperties: false
248247
request-body-object:
249-
$comment: https://spec.openapis.org/arazzo/v1.0.0#request-body-object
248+
$comment: https://spec.openapis.org/arazzo/v1.0#request-body-object
250249
description: The request body to pass to an operation as referenced by operationId or operationPath
251250
type: object
252251
properties:
@@ -263,7 +262,7 @@ $defs:
263262
$ref: '#/$defs/specification-extensions'
264263
unevaluatedProperties: false
265264
criterion-object:
266-
$comment: https://spec.openapis.org/arazzo/v1.0.0#criterion-object
265+
$comment: https://spec.openapis.org/arazzo/v1.0#criterion-object
267266
description: |-
268267
An object used to specify the context, conditions, and condition types
269268
that can be used to prove or satisfy assertions specified in Step Object successCriteria,
@@ -296,7 +295,7 @@ $defs:
296295
$ref: '#/$defs/specification-extensions'
297296
unevaluatedProperties: false
298297
criterion-expression-type-object:
299-
$comment: https://spec.openapis.org/arazzo/v1.0.0#criterion-expression-type-object
298+
$comment: https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object
300299
description: An object used to describe the type and version of an expression used within a Criterion Object
301300
type: object
302301
properties:
@@ -337,7 +336,7 @@ $defs:
337336
- xpath-30
338337
$ref: '#/$defs/specification-extensions'
339338
success-action-object:
340-
$comment: https://spec.openapis.org/arazzo/v1.0.0#success-action-object
339+
$comment: https://spec.openapis.org/arazzo/v1.0#success-action-object
341340
description: A single success action which describes an action to take upon success of a workflow step
342341
type: object
343342
properties:
@@ -379,7 +378,7 @@ $defs:
379378
$ref: '#/$defs/specification-extensions'
380379
unevaluatedProperties: false
381380
failure-action-object:
382-
$comment: https://spec.openapis.org/arazzo/v1.0.0#failure-action-object
381+
$comment: https://spec.openapis.org/arazzo/v1.0#failure-action-object
383382
description: A single failure action which describes an action to take upon failure of a workflow step
384383
type: object
385384
properties:
@@ -438,7 +437,7 @@ $defs:
438437
$ref: '#/$defs/specification-extensions'
439438
unevaluatedProperties: false
440439
reusable-object:
441-
$comment: https://spec.openapis.org/arazzo/v1.0.0#reusable-object
440+
$comment: https://spec.openapis.org/arazzo/v1.0#reusable-object
442441
description: A simple object to allow referencing of objects contained within the Components Object
443442
type: object
444443
properties:
@@ -458,7 +457,7 @@ $defs:
458457
- reference
459458
unevaluatedProperties: false
460459
parameter-object:
461-
$comment: https://spec.openapis.org/arazzo/v1.0.0#parameter-object
460+
$comment: https://spec.openapis.org/arazzo/v1.0#parameter-object
462461
description: Describes a single step parameter
463462
type: object
464463
properties:
@@ -472,7 +471,6 @@ $defs:
472471
- query
473472
- header
474473
- cookie
475-
- body
476474
value:
477475
description: The value to pass in the parameter
478476
type:
@@ -488,7 +486,7 @@ $defs:
488486
$ref: '#/$defs/specification-extensions'
489487
unevaluatedProperties: false
490488
payload-replacement-object:
491-
$comment: https://spec.openapis.org/arazzo/v1.0.0#payload-replacement-object
489+
$comment: https://spec.openapis.org/arazzo/v1.0#payload-replacement-object
492490
description: Describes a location within a payload (e.g., a request body) and a value to set within the location
493491
type: object
494492
properties:
@@ -504,7 +502,7 @@ $defs:
504502
unevaluatedProperties: false
505503
$ref: '#/$defs/specification-extensions'
506504
components-object:
507-
$comment: https://spec.openapis.org/arazzo/v1.0.0#components-object
505+
$comment: https://spec.openapis.org/arazzo/v1.0#components-object
508506
description: Holds a set of reusable objects for different aspects of the Arazzo Specification
509507
type: object
510508
properties:
@@ -536,10 +534,10 @@ $defs:
536534
unevaluatedProperties: false
537535
$ref: '#/$defs/specification-extensions'
538536
specification-extensions:
539-
$comment: https://spec.openapis.org/arazzo/v1.0.0#specification-extensions
537+
$comment: https://spec.openapis.org/arazzo/v1.0#specification-extensions
540538
description: While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points
541539
patternProperties:
542540
'^x-': true
543541
schema:
544-
$comment: https://spec.openapis.org/arazzo/v1.0.0#schema-object
542+
$comment: https://spec.openapis.org/arazzo/v1.0#schema-object
545543
$ref: 'https://json-schema.org/draft/2020-12/schema'

‎scripts/format-markdown.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
SRCDIR="$(dirname "${BASH_SOURCE[0]}")" # check on Windows
44

55
for filename in $*; do
6+
# check if the $filename exists and if it's writeable
7+
if [ ! -w $filename ]; then
8+
echo "No matching file found: $filename"
9+
continue;
10+
fi
611
# mostly to format code blocks with examples, unfortunately messes up bullet lists and tables
712
npx prettier --write --single-quote $filename
813

‎versions/1.0.0.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ workflows:
178178
# outputs from this step
179179
availablePets: $response.body
180180
outputs:
181-
available: $steps.getPetStep.availablePets
181+
available: $steps.getPetStep.outputs.availablePets
182182
```
183183
184184
#### Info Object
@@ -868,19 +868,19 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org
868868

869869
#### Examples
870870

871-
| Source Location | example expression | notes |
872-
| ---- | :---- | :---- |
873-
| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. |
874-
| Requested media type | `$request.header.accept` | |
875-
| Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. |
876-
| Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. |
877-
| Request URL | `$url` | |
878-
| Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. |
879-
| Response header | `$response.header.Server` | Single header values only are available |
880-
| workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available |
881-
| Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body. |
882-
| Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available |
883-
| Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. |
871+
Source Location | example expression | notes
872+
---|:---|:---|
873+
HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation.
874+
Requested media type | `$request.header.accept` |
875+
Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers.
876+
Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.
877+
Request URL | `$url` |
878+
Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body.
879+
Response header | `$response.header.Server` | Single header values only are available
880+
workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available
881+
Step output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body.
882+
Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body.
883+
Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.
884884

885885
Runtime expressions preserve the type of the referenced value.
886886
Expressions can be embedded into string values by surrounding the expression with `{}` curly braces.

0 commit comments

Comments
 (0)