Skip to content
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

Jump to bottom

Proposal: Use semver instead of dates for schema IDs #138

Closed
michaeltlombardi opened this issue Aug 4, 2023 · 2 comments
Closed

Proposal: Use semver instead of dates for schema IDs #138

michaeltlombardi opened this issue Aug 4, 2023 · 2 comments
Labels
Issue-Enhancement The issue is a feature or idea Need-Review

Comments

@michaeltlombardi
Copy link
Collaborator

michaeltlombardi commented Aug 4, 2023 •
edited
Loading

Using $schema rather than a semver version requires forward compat to just give parsing a try and hope that anything that would be considered a major version change isn't still parsable by an older client. (Alternatively, you can just have no forward compat.)

Have you considered embedding a semver version number in the schema URL to enable forward compatability?

Originally posted by @JohnMcPMS in #94 (comment)
@michaeltlombardi michaeltlombardi mentioned this issue Aug 4, 2023
Merged
@michaeltlombardi michaeltlombardi changed the title Using $schema rather than a semver version requires forward compat to just give parsing a try and hope that anything that would be considered a major version change isn't still parsable by an older client. (Alternatively, you can just have no forward compat.) Proposal: Use semver instead of dates for schema IDs Aug 4, 2023
@michaeltlombardi michaeltlombardi added the Issue-Enhancement The issue is a feature or idea label Aug 30, 2023
@michaeltlombardi michaeltlombardi mentioned this issue Jan 18, 2024
Closed
@michaeltlombardi
Copy link
Collaborator Author

Thinking about this again, one of the things we might want to do, because hosting the schemas is relatively cheap, is publish the schemas at multiple URIs (possibly just by adding redirects):

  • A canonical URI based on the semantic version of the schema itself, indicating breaking changes/additions/etc. This will be more important after alpha to provide an indication of whether or not users can expect any changes for the schema between versions.
  • The date-based URI, which we use now, as an alias.
  • An alias URI based on the compatible DSC version. In this case, when the same schema applies to multiple versions, we publish it to each URI. This would make alpha.1, alpha.2, and alpha.3 use the same schemas, but accessible at .../v3.0.0-alpha.1/..., .../v3.0.0-alpha.2/..., etc.

The other thing we could (should?) do is add a $comment to the schemas indicating which version(s) of DSC they are compatible with, so anyone reviewing the schema can quickly identify the releases it works with.

michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Feb 22, 2025
@michaeltlombardi
(PowerShellGH-642) Generate schemas from source for v3.0
a83f4e7 
This change generates the canonical schemas for in new folders: `v3`,
`v3.0`, and `v3.0.0`, instead of the previous date-based folder
`2024/04`. The changing of the casing is _not_ backwards compatible, and
requires a new location to avoid breaking prior schemas.

This change generates the schemas into three folders to accomodate the
changes requested in PowerShell#138 for moving from date-based to semantic
versioning for the schemas.

Going forward, schema generation should:

- Export to a folder for the current release with the full semantic
  version, like `v3.0.1` or `v3.1.0`.
- Export to a folder for the current `major.minor` schema, like `v3.0` or
  `v3.1`
- Build to a folder for the current major version of the release, like `v3`.

Under this design, you can:

- Get the exact version of the schema that a release shipped with by
  specifying the schema URI as `v<major>.<minor>.<patch>`
- Get the latest schema for your minor version as `v<major>.<minor>`
- Get the latest schema for your major version as `v<major>`

Breaking changes to the schema have the potential to break
integrating software, configuration documents, and resource manifests.
They therefore constitute a breaking change in the application and
require incrementing the major version segment of the semantic version.

This change will be followed by an update to the allowed schema versions
in the code itself, which should only recognize the updated schema at
this time, not previous schemas.
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Feb 25, 2025
@michaeltlombardi
(PowerShellGH-642) Generate schemas from source for v3.0
91a8a67 
This change generates the canonical schemas for in new folders: `v3`,
`v3.0`, and `v3.0.0`, instead of the previous date-based folder
`2024/04`. The changing of the casing is _not_ backwards compatible, and
requires a new location to avoid breaking prior schemas.

This change generates the schemas into three folders to accomodate the
changes requested in PowerShell#138 for moving from date-based to semantic
versioning for the schemas.

Going forward, schema generation should:

- Export to a folder for the current release with the full semantic
  version, like `v3.0.1` or `v3.1.0`.
- Export to a folder for the current `major.minor` schema, like `v3.0` or
  `v3.1`
- Build to a folder for the current major version of the release, like `v3`.

Under this design, you can:

- Get the exact version of the schema that a release shipped with by
  specifying the schema URI as `v<major>.<minor>.<patch>`
- Get the latest schema for your minor version as `v<major>.<minor>`
- Get the latest schema for your major version as `v<major>`

Breaking changes to the schema have the potential to break
integrating software, configuration documents, and resource manifests.
They therefore constitute a breaking change in the application and
require incrementing the major version segment of the semantic version.

This change will be followed by an update to the allowed schema versions
in the code itself, which should only recognize the updated schema at
this time, not previous schemas.
SteveL-MSFT pushed a commit to SteveL-MSFT/DSC that referenced this issue Feb 26, 2025
@michaeltlombardi @SteveL-MSFT
(PowerShellGH-642) Generate schemas from source for v3.0
d86b7e4 
This change generates the canonical schemas for in new folders: `v3`,
`v3.0`, and `v3.0.0`, instead of the previous date-based folder
`2024/04`. The changing of the casing is _not_ backwards compatible, and
requires a new location to avoid breaking prior schemas.

This change generates the schemas into three folders to accomodate the
changes requested in PowerShell#138 for moving from date-based to semantic
versioning for the schemas.

Going forward, schema generation should:

- Export to a folder for the current release with the full semantic
  version, like `v3.0.1` or `v3.1.0`.
- Export to a folder for the current `major.minor` schema, like `v3.0` or
  `v3.1`
- Build to a folder for the current major version of the release, like `v3`.

Under this design, you can:

- Get the exact version of the schema that a release shipped with by
  specifying the schema URI as `v<major>.<minor>.<patch>`
- Get the latest schema for your minor version as `v<major>.<minor>`
- Get the latest schema for your major version as `v<major>`

Breaking changes to the schema have the potential to break
integrating software, configuration documents, and resource manifests.
They therefore constitute a breaking change in the application and
require incrementing the major version segment of the semantic version.

This change will be followed by an update to the allowed schema versions
in the code itself, which should only recognize the updated schema at
this time, not previous schemas.
@michaeltlombardi
Copy link
Collaborator Author

Resolved by #648

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Issue-Enhancement The issue is a feature or idea Need-Review
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@michaeltlombardi