devcontainer.json $schema URL downgrade and unknown field handling in GitHub Codespaces

Direct Answer

GitHub Codespaces does not automatically strip or ignore unknown fields when you downgrade the $schema URL. It also does not reject the workspace startup or prompt for manual adjustment. Instead, the platform retains all fields present in devcontainer.json and validates only against the schema version you explicitly reference. Fields that exist in the newer schema but not the older one (such as postCreateCommand in certain versions) remain in the configuration but may be ignored, misinterpreted, or produce silent inconsistencies because the older schema does not define them.

Confirmed Behavior

• Schema validation is version-bound. The $schema URL selects a specific JSON Schema draft. Codespaces uses that schema to validate the file, but the devcontainer schema historically sets additionalProperties: true (or omits the keyword), so unknown properties pass validation.
• No automated rollback. There is no documented safe-rollback mechanism that rewrites your devcontainer.json when you change the schema URL. The onus is on the author to align the configuration with the targeted version.
• Startup proceeds with warnings at most. Codespaces may emit a log line noting unrecognized properties, but it will not block the build or require interactive confirmation.

Likely Explanation (Not Guaranteed)

The devcontainer specification evolves by adding fields. When you point $schema to an older URL, you are effectively saying “validate this file as if it were written for version X.” The validator honors that request: it checks required fields and types defined in version X, but it does not delete keys that version X doesn’t know about. Those keys travel forward into the container runtime, where the Codespaces agent may ignore them, treat them differently, or—if the runtime is newer than the schema—still execute them. This mismatch is the source of the “inconsistent environment” risk you identified.

Practical Verification Steps

1. Change $schema to the older URL you intend to use (e.g., https://aka.ms/devcontainer-json/schema.json for a specific release).
2. Add a deliberately unknown field such as "__testUnknown": true.
3. Create or rebuild the Codespace and inspect the build logs (the “Creation log” in the Codespaces UI or ~/.codespaces/logs/ in the container). Look for lines containing unknown, unrecognized, or validation.
4. If the Codespace starts and the test field produces no error, the platform is silently retaining unknown properties for that runtime version.

Recommended Workflow

Treat $schema as a contract, not a migration tool. When you must target an older schema:

• Consult the devcontainer specification changelog to see which fields were added or changed between versions.
• Manually remove or rewrite any fields not present in the target version.
• Run the verification steps above to confirm the cleaned file behaves as expected.

One Diagnostic Detail Needed

Which exact $schema URL (including version fragment, if any) are you downgrading from and to? The set of recognized fields differs per release, and knowing the pair lets me confirm whether postCreateCommand or other specific keys are defined in the target version.