Skip to content

v3.3: cleanup: removed json-style format from yaml examples #5301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
karenetheridge wants to merge 1 commit into from
+26 −33
Closed

v3.3: cleanup: removed json-style format from yaml examples #5301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 26 additions & 33 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -966,7 +966,7 @@
dataValue:
- 12345678
- 90099
serializedValue: "12345678,90099"
serializedValue: 12345678,90099
```


Expand All @@ -993,7 +993,7 @@
dataValue:
greeting: Hello%2C%20world!
code: 42
serializedValue: "greeting=Hello%2C%20world!; code=42"
serializedValue: greeting=Hello%2C%20world!; code=42
```

A cookie parameter relying on the percent-encoding behavior of the default `style: "form"`:
Expand All @@ -1012,7 +1012,7 @@
characters, rather than just the one non-cookie-safe
character, getting percent-encoded.
dataValue: Hello, world!
serializedValue: "greeting=Hello%2C%20world%21"
serializedValue: greeting=Hello%2C%20world%21
```

A path parameter of a string value:
Expand All @@ -1025,15 +1025,15 @@
schema:
type: string
examples:
"Edsger Dijkstra":
Edsger Dijkstra:
dataValue: edijkstra
serializedValue: edijkstra
Diṅnāga:
dataValue: diṅnāga
serializedValue: di%E1%B9%85n%C4%81ga
Al-Khwarizmi:
dataValue: "الخوارزميّ"
serializedValue: "%D8%A7%D9%84%D8%AE%D9%88%D8%A7%D8%B1%D8%B2%D9%85%D9%8A%D9%91"
serializedValue: %D8%A7%D9%84%D8%AE%D9%88%D8%A7%D8%B1%D8%B2%D9%85%D9%8A%D9%91
```

An optional query parameter of a string value, allowing multiple values by repeating the query parameter
Expand All @@ -1054,7 +1054,7 @@
dataValue:
- one thing
- another thing
serializedValue: "thing=one%20thing&thing=another%20thing"
serializedValue: thing=one%20thing&thing=another%20thing
```

A free-form query parameter, allowing arbitrary parameters of `type: "integer"`:
Expand Down Expand Up @@ -1174,7 +1174,7 @@
- 1
- 2
flag: null
serializedValue: "%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D"
serializedValue: %7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D
```

Assuming a path of `/foo`, a server of `https://example.com`, the full URL incorporating the value from `serializedValue` would be:
Expand Down Expand Up @@ -1449,22 +1449,20 @@
examples:
cat:
summary: An example of a cat
value: {
"name": "Fluffy",
"petType": "Cat",
"color": "White",
"gender": "male",
"breed": "Persian"
}
value:
name: Fluffy
petType: Cat
color: White
gender: male
breed: Persian
Copy link
Copy Markdown
Contributor

@notEthan notEthan Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The immediately preceding text no longer makes sense...

Alternatively, since all JSON is valid YAML, the example value can use JSON syntax within a YAML document

... since the example value now does not use JSON syntax

dog:
summary: An example of a dog with a cat's name
value: {
"name": "Puma",
"petType": "Dog",
"color": "Black",
"gender": "Female",
"breed": "Mixed"
}
value:
name: Puma
petType: Dog
color: Black
gender: Female
breed: Mixed
frog:
$ref: '#/components/examples/frog-example'
```
Expand Down Expand Up @@ -1509,7 +1507,7 @@
description: JSONL and NDJSON are identical for this example
# Note that the value must be written as a string with newlines,
# as JSONL and NDJSON are not valid YAML
value: |
serializedValue: |
{"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
{"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Bye!"}
responses:
Expand Down Expand Up @@ -2446,12 +2444,7 @@
author: A. Writer
title: An Older Book
rating: 4.5
serializedValue: |
{
"author": "A. Writer",
"title": "An Older Book",
"rating": 4.5
}
serializedValue: {"author":"A. Writer","title":"An Older Book","rating":4.5}
Copy link
Copy Markdown
Contributor

@notEthan notEthan Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this changes serializedValue from a string to a json object, does not look correct

```

##### Binary Examples
Expand All @@ -2478,10 +2471,10 @@
schema:
type: boolean
examples:
"true":
'true':
dataValue: true
serializedValue: flag=true
"false":
'false':
dataValue: false
serializedValue: flag=false
```
Expand Down Expand Up @@ -2850,9 +2843,9 @@
examples:
SetCookies:
dataValue:
lang: "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT"
foo: "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT"
urlSafeData: "Hello%2C%20world%21"
lang: en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
foo: bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
urlSafeData: Hello%2C%20world%21
serializedValue: |
lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
Expand Down Expand Up @@ -3879,7 +3872,7 @@

#### Namespace Limitations

The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:

Check failure on line 3875 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://www.w3.org/TR/xml-names11/ Status: 403

Raw Output:
message:"Cannot reach https://www.w3.org/TR/xml-names11/ Status: 403"  location:{path:"src/oas.md"  range:{start:{line:3875  column:58}  end:{line:3875  column:110}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}

* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI" ("non-relative IRI" as of OAS v3.2.0), so authors using namespaces that include a fragment should check tooling support carefully.
* XML allows but discourages relative IRI-references, while this specification outright forbids them.
Expand Down
Loading