SSA request bodies can include either JSON or YAML

[MohammadAlavi1986]

SSA request bodies can include either JSON or YAML

Since JSON messages are valid YAML, the request body for a server-side apply request (application/apply-patch+yaml content type) can be in either JSON or YAML.

Example:

kubectl create deploy nginx --image nginx --replicas 1

# request body is in JSON
cat <<EOF | curl  -XPATCH -H 'content-type: application/apply-patch+yaml' \
 'http://localhost:8001/apis/apps/v1/namespaces/default/deployments/nginx?fieldManager=test&force=true' \
 --data-binary @-
{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "spec": {
    "replicas": 2
  }
}
EOF


# request body is in YAML
cat <<EOF | curl  -XPATCH -H 'content-type: application/apply-patch+yaml' \
 'http://localhost:8001/apis/apps/v1/namespaces/default/deployments/nginx?fieldManager=test&force=true' \
 --data-binary @-
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 1
EOF

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign divya-mohan0209 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• content/en/docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	057e98b
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/67d85f87ba2d4f0008bc9a58
😎 Deploy Preview	https://deploy-preview-50116--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[sftim]

application/apply-patch+yaml is always formally YAML, not JSON.

This change doesn't convey the nuance originally intended. You are welcome to write something new, but we shouldn't make the swap you're proposing here.

[MohammadAlavi1986]

JSON is YAML, but the reverse is not true. The sentence in the documentation currently states "Some clients specify Server-Side Apply requests using YAML request bodies that are also valid JSON", which is not true and the exact opposite. You can provide JSON (in addition to YAML) request bodies because JSON is valid YAML.

[MohammadAlavi1986]

A better wording might be:

All JSON messages are valid YAML. Therefore, in addition to using YAML request bodies for Server-Side Apply requests, you can also use JSON request bodies, as they are also valid YAML.

[sftim]

All JSON messages are valid YAML. Therefore, in addition to using YAML request bodies for Server-Side Apply requests, you can also use JSON request bodies, as they are also valid YAML.

You could try that. Actually, the existing text is factually wrong. JSON allows tabs as whitespace; YAML does not. Something to bear in mind.

You can convert all JSON to valid YAML by replacing all ASCII tab characters with the appropriate number of space (0x20) characters. If you do that, the resulting YAML will also be valid JSON.

[MohammadAlavi1986]

YAML is a superset of JSON, and any compliant YAML parser should be able to parse JSON. There’s no need to convert a JSON document before passing it to a YAML parser.

[sftim]

Can you cite a source for that assertion [that the existing docs are correct and that YAML is a pure superset of JSON]? I checked against the official grammars.

[MohammadAlavi1986]

The documentation is incorrect, as it states the opposite. SSA request bodies (application/apply-patch+yaml content type) are expected to be in YAML. However, since a YAML parser can also parse JSON (YAML is a superset of JSON), you can use JSON as well as YAML for request bodies.
The existing documentation states:

Some clients specify Server-Side Apply requests using YAML request bodies that are also valid JSON.

This should be corrected to:

Some clients specify Server-Side Apply requests using JSON request bodies that are also valid YAML.

[apelisse]

I think no one is wrong or right here, but if there's confusion, we should probably update it.

The existing documentation states:

Some clients specify Server-Side Apply requests using YAML request bodies that are also valid JSON.

I don't think that's wrong, I could slightly rephrase as:

Some clients specify Server-Side Apply requests using YAML request bodies, and they happen to also be valid JSON (which they can be), but that's irrelevant, since it's still YAML at the end of the day. So in other word, however you format your YAML, in the form of json or not, it doesn't matter, as long as it's yaml.

[MohammadAlavi1986]

Some clients specify Server-Side Apply requests using YAML request bodies that are also valid JSON.

From this statement, it can be inferred that all YAML are valid JSON. At least, this is my initial interpretation. While this is true for some YAML documents, it is not true for all YAML. Furthermore, since the content type for SSA requests is application/apply-patch+yaml, the request body is expected to be in YAML. Given that YAML is a superset of JSON, I thought there was a typo in the statement and you meant to say that some clients use JSON for request bodies, which is also valid YAML.

[sftim]

/hold

I have a concern about technical accuracy. Let's get a tech review from SIG API Machinery before unholding.

[sftim]

kubectl create deploy nginx --image nginx --replicas 1

# request body is in JSON
cat <<EOF | curl  -XPATCH -H 'content-type: application/apply-patch+yaml' \
 'http://localhost:8001/apis/apps/v1/namespaces/default/deployments/nginx?fieldManager=test&force=true' \
 --data-binary @-
{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "spec": {
    "replicas": 2
  }
}
EOF

According to the metadata, that's YAML. I don't see how it's more correct to say that it is JSON; it is YAML that is also valid JSON.

Another analogy: think of a rational number under 1000000, and then divide it by 3.
The [decimal string representation of the] resulting number is also valid JSON, but I think it's most appropriate to think of it as a number.

[MohammadAlavi1986]

kubectl create deploy nginx --image nginx --replicas 1

# request body is in JSON
cat <<EOF | curl  -XPATCH -H 'content-type: application/apply-patch+yaml' \
 'http://localhost:8001/apis/apps/v1/namespaces/default/deployments/nginx?fieldManager=test&force=true' \
 --data-binary @-
{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "spec": {
    "replicas": 2
  }
}
EOF

According to the metadata, that's YAML. I don't see how it's more correct to say that it is JSON; it is YAML that is also valid JSON.

Another analogy: think of a rational number under 1000000, and then divide it by 3. The [decimal string representation of the] resulting number is also valid JSON, but I think it's most appropriate to think of it as a number.

Not all YAML are JSON, but all JSON are YAML

[sftim]

Not all YAML are JSON, but all JSON are YAML.

Look, this is factually wrong. See #50116 (comment)

You're allows tab characters as whitespace in JSON but not in YAML, so you can have a valid JSON document that is not valid YAML.

If we change the document, let's not retain that misleading detail. Right now I judge that the better option is to leave it like I wrote it. However, I am (and SIG Docs is) open to a bigger change that removes the misleading existing text and replaces it with something easier to understand.

[MohammadAlavi1986]

Not all YAML are JSON, but all JSON are YAML.

Look, this is factually wrong. See #50116 (comment)

You're allows tab characters as whitespace in JSON but not in YAML, so you can have a valid JSON document that is not valid YAML.

If we change the document, let's not retain that misleading detail. Right now I judge that the better option is to leave it like I wrote it. However, I am (and SIG Docs is) open to a bigger change that removes the misleading text and replaces it with something easier to understand.

In response to the comment, I stated that YAML is a superset of JSON, meaning any YAML parser should be able of parsing JSON, even if it includes tab characters. I also referenced the YAML specification to support this point. However, it seems that you do not accept that YAML is a superset of JSON.

To clarify, here is a simple Go app that demonstrates a YAML parser successfully parsing JSON with tab characters:

package main

import (
	"fmt"
	"gopkg.in/yaml.v2"
	"log"
)

func main() {
	// Example JSON with tab characters as whitespace (valid JSON/YAML)
	jsonData := `{
		"name":		"example",		"version":	1
	}`

	var yamlObj map[string]interface{}
	err := yaml.Unmarshal([]byte(jsonData), &yamlObj)
	if err != nil {
		log.Fatalf("Error parsing as YAML: %v", err)
	}
	fmt.Println("Not all YAML are JSON, but all JSON are YAML.")
}

[sftim]

Ah, you know what? I'm out of date. YAML 1.2.2 does have full JSON compatibility.

Great. The existing text is fine and doesn't need to be changed in order to become correct. We can make a different change to what you've proposed @MohammadAlavi1986 and a rewording to clarify is welcome, but I really don't support what you're proposing here.

In my considered opinion, it would confuse more people than it would help.

[MohammadAlavi1986]

Ah, you know what? I'm out of date. YAML 1.2.2 does have full JSON compatibility.

Great. The existing text is fine and doesn't need to be changed in order to become correct. We can make a different change to what you've proposed @MohammadAlavi1986 and a rewording to clarify is welcome, but I really don't support what you're proposing here.

In my considered opinion, it would confuse more people than it would help.

what is the confusion in the following sentence?
All JSON messages are valid YAML. Therefore, in addition to using YAML request bodies for Server-Side Apply requests, you can also use JSON request bodies, as they are also valid YAML.