docs(yaml): reconcile YAML config schema with project file reference

[rshade]

Summary

• Aligns the YAML language reference with the canonical project-level config schema documented in project-file.md, resolving the long-standing inconsistencies flagged in Inconsistencies in YAML config docs #12417 (mismatched type names, drifted property tables, and a stale anchor link).
• Replaces the YAML page's Title-Case type list (String, Number, List<String>, etc.) with the lowercase types the engine actually accepts today: string, integer, boolean, array, and object, plus the items form that replaces List<T>.
• Moves the legacy configuration key guidance into a warning callout that documents the full deprecated schema, so existing users can still recognize their programs while new programs get steered to the supported form.
• Adds a note on project-file.md clarifying that the config schema there is the canonical, engine-parsed schema used by every language (including YAML), with a cross-link to the YAML page for YAML-flavored examples.

Test plan

• make lint clean (project's markdownlint-cli2 over built output)
• Visual spot-check via make serve: rendered {{% notes %}} callouts on both pages, in-page #config anchor from the top property table, and cross-links between the two pages
• Spot-check that the example YAML program still parses with pulumi preview against a scratch project

Changes

Modified files

• content/docs/iac/languages-sdks/yaml/yaml-language-reference.md — Fix the top-of-page config link to use the in-page #config anchor; rewrite the Config section to mirror the project-level schema (lowercase types, items row, secret guidance); move the configuration deprecation into a warning callout with the full legacy type list; refresh the example program to use the supported schema and add a boolean example.
• content/docs/iac/concepts/projects/project-file.md — Add a note above ### config options clarifying that this schema is parsed by the engine and applies to every language, with a link to the YAML reference.

Closes #12417

Proposed changes

Unreleased product version (optional)

Related issues (optional)

[claude]

Docs review — PR #18971

Reviewed both modified files against STYLE-GUIDE.md and the shared review criteria. The change is well-motivated and the YAML reference now genuinely matches the canonical schema in project-file.md. A few small polish items below.

Issues

content/docs/iac/languages-sdks/yaml/yaml-language-reference.md

• Line 49 — Type ordering does not match the canonical reference. The YAML page lists string, integer, boolean, array, and object, while project-file.md line 145 lists string, boolean, integer, array, or object. Since this PR's goal is reconciliation, align the order so a reader cross-referencing the two pages does not suspect they are different sets. Suggested change to match the canonical source:

  | `type` | string | No | No | The data type for the config value. Valid types are: `string`, `boolean`, `integer`, `array`, and `object`. |
  

• Line 50 — Nit: "Required when type is array" reads slightly differently from project-file.md line 149's "required if type is array". Either is fine, but matching phrasing reinforces the "same schema" message:

  | `items` | object | Required if `type` is `array` | No | A nested structured declaration of the type of the items in the array. |
  

• Line 55 (warning callout) — The sentence "Programs that still use configuration continue to work and emit a deprecation warning during pulumi preview and pulumi up" makes a specific, verifiable claim. Worth confirming against the YAML runtime today that (a) configuration still parses without error, and (b) the deprecation warning is actually emitted (and on which commands). If the warning only fires on certain commands or has a slightly different trigger, narrow the wording. If it is not emitted at all today, soften to "is documented as deprecated."

• Line 55 — Minor: "Title-Case types" is fine descriptively, but per the style guide preference for lowercase non-proper nouns, "title-case types" would be more consistent. Optional.

content/docs/iac/concepts/projects/project-file.md

• Line 125 — The new note is one ~50-word sentence with two nested clauses. Easier to scan if split:

  This is the project-level `config` schema parsed by the Pulumi engine. It applies to programs in every language — TypeScript, Python, Go, .NET, Java, and YAML — including the `config` block of a Pulumi YAML program. See the [Pulumi YAML reference](/docs/iac/languages-sdks/yaml/yaml-language-reference/#config) for a YAML-flavored example.
  

• Line 125 — Verify the language list is correct and complete. The note says "every language (TypeScript, Python, Go, .NET, Java, and YAML)" — if Pulumi currently supports additional first-party language runtimes not listed here (or if Java is still considered preview/community in your docs taxonomy), tighten the wording to avoid an inadvertent support claim.

Things that look good

• The top-of-page anchor fix from /docs/reference/pulumi-yaml/#config-options to #config resolves correctly to the in-page ### Config heading.
• The cross-link to …/project-file/#config-options resolves to the ### config options heading (Hugo strips the backticks).
• Moving the configuration legacy guidance into a warning callout with the full Title-Case type list is the right call — existing users can still identify their schema while new programs are steered to config.
• The example program is a meaningful upgrade: it now exercises boolean, the array + items pair, and the secret guidance.
• The reworded default description ("if no value is set on the stack") is more accurate than the prior "if no value is specified".

Checklist

• Style guide compliance — generally clean
• Links resolve (in-page #config anchor, cross-link to #config-options)
• No file moves/aliases needed (in-place edits)
• Code example is syntactically valid YAML; types match documented schema
• Verify configuration deprecation warning behavior (line 55)
• Confirm the canonical language list in the new note (line 125)

---

Mention me (@claude) if you would like a follow-up pass after revisions, or if you want me to dig into the deprecation-warning behavior question.

[pulumi-bot]

Your site preview for commit 475ed11 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18971-475ed11f.s3-website.us-west-2.amazonaws.com