fish
Guppy
Posts: 65
|
Post by fish on Feb 19, 2018 12:51:34 GMT
Hi,
Regarding usage of deprecation annotation in schemas. An example is the deprecation of old Location/Info property in Resource schema (used in Chassis). I can find description of other annotations in the specification document DSP0266, but I can’t find any description of “Deprecated” annotation usage. Same for annotation of enum value deprecation via EnumDeprecated in JSON. (Example: IndicatorLED in ComputerSystem) Is this described somewhere? If not, I would like to propose that such description is added to the specification. This will also be valuable for organizations defining own OEM schemas as this will make it easier to follow same pattern for deprecation handling.
Related questions:
1. Are there any plans for how long the deprecation period will be for the deprecated properties, before they are finally removed from schemas (latest version)? Or will they never be removed? Should such statement be added to the specification also?
2. Is the any Redfish mechanism for deprecation of complete resource/schema? (Has this ever been applied in Redfish?)
|
|
|
|
Post by mraineri on Feb 20, 2018 12:56:47 GMT
We track descriptions for those in the Redfish Schemas themselves. The schema files "RedfishExtensions_v1.xml" and "redfish-schema.v1_X_0.json" contain the annotations we've defined in the SPMF. Each of the schema files in both CSDL and JSON Schema will reference one of the two files in order to leverage those definitions. For example, in the file Chassis.v1_6_0.json, it contains the term "$schema" with the value "http://redfish.dmtf.org/schemas/v1/redfish-schema.v1_3_0.json", which is the JSON Schema method of including additional meta-schema elements. We can discuss it within the group to see if it's worth copying the descriptions into the specification, but at least they're in the schema files themselves currently.
For your other questions...
1) Generally speaking, we'd clean up the schemas and remove deprecated properties when a new major version of the schema is introduced; this is mentioned in the description for the deprecated term: "Deprecated properties are likely to be removed in a future major version of the schema." One thing to keep in mind though is major version changes tend to break backwards compatibility, so we try to avoid those if possible.
2) We could leverage the same term to deprecate an entire resource, but that's not something we've encountered yet. Ultimately I think there will need to be careful thought when doing that, since we'd have to scrub all of the NavigationProperty elements that reference the deprecated schema and in turn deprecate those properties.
|
|
fish
Guppy
Posts: 65
|
Post by fish on Feb 20, 2018 14:55:18 GMT
Hi,
OK, thanks.
1) I guess it will be up to the server providers (Redfish service) to worry about minimum deprecation period towards their clients. But it could result in that a server cannot migrate to use the newer Redfish schema, in case Redfish schemas are updated to exclude some deprecated property. The server provider can chose themselves when to not support the property anymore, by not returning it ni the response, as long as the deprecated property is still in the schema. So maybe the best solution, on Redfish schema level, is to keep the deprecated properties as long as possible, and leave it to the server providers to handle deprecation period. ?
|
|
|
|
Post by mraineri on Feb 20, 2018 18:41:11 GMT
That's correct; that's why as a general methodology with using "deprecated" in the schema is to keep the definition around until a new major version is introduced. This allows a good amount of time for services and clients to transition to new definitions.
While we haven't gone through this yet, we suspect that transitioning to a new major version of schema will break backwards compatibility and will require both client and service work in order to transition to a 2.X.X version. So, that sort of breaking point is ideal from a standards perspective to pull out deprecated definitions. Keep in mind, just because a schema may transition to a new major version, clients and services can still use older versions of the schema until they're ready to transition, which means they can continue to use deprecated definitions until they can be updated.
|
|
