|
|
Post by siaoleio on Feb 20, 2021 1:34:32 GMT
Hello everyone,
I am new to redfish. I learn from the document that redfish's protocol and schema are separate. But I am still confused about the correspondence between specification version and schema version. Please help answer my following questions about this seemingly simple topic. Thanks a lot.
I am trying to develop a redfish service based on C lanaguage. Suppose we want to develop based on the latest redfish version. The 3 reference files are "DSP0266 1.12.0 Redfish Specification 20 Jan 2021", "DSP0268 2020.4 Redfish Schema Supplement 20 Jan 2021", "DSP8010 2020.4 Redfish Schema Bundle 20 Jan 2021". My questions are:
1) How to call the version of the redfish service？ Can I tell my customer my redfish service version is "1.12.0"? Or should I call my redfish service version is "based on specification 1.12.0 and schema 2021.2.20 ", I think the latter seems to be correct, but it doesn’t seem to be concise enough.
2) Is there a clear correspondence between the specification version and the schema bundle version? If my redfish service is based on the newest specification but a very old schema bundle files. I do not think this is correct. Can I arbitrarily combine specification version and schema files version?
With kindest regards
|
|
|
|
Post by jautor on Feb 20, 2021 6:20:35 GMT
1) How to call the version of the redfish service？ Can I tell my customer my redfish service version is "1.12.0"? Or should I call my redfish service version is "based on specification 1.12.0 and schema 2021.2.20 ", I think the latter seems to be correct, but it doesn’t seem to be concise enough.
You are correct that the specification (protocol) version is separate, and independent of, the schema (resource) versions. The answer to the question "What version of Redfish do you support" is unfortunately more complicated than users will expect. All protocol functionality added since v1.6.0 is optional, and so you can report 1.12.0 easily, even if you haven't added those options. The question of schema version is more complex, but yes, we do tend to tell users what bundle version our services are "based on" - but if a user is expecting a specific resource or property, they really need to ask or consult the vendor documentation - because very few properties are required by specification. This is why we recommend that vendors document their service contents by publishing mockups or other documentation to show what a typical service response will look like.
2) Is there a clear correspondence between the specification version and the schema bundle version? If my redfish service is based on the newest specification but a very old schema bundle files. I do not think this is correct. Can I arbitrarily combine specification version and schema files version?
Yes, you can arbitrarily combine the specification and schema versions. Certainly your service will have a number of different "schema versions" because each schema is versioned independently as well. So while you may have ComputerSystem v1.10.0, you would have PowerSupply v1.0.0 - because PowerSupply was just released in the latest bundle, while ComputerSystem has been around since the first Redfish release. If you are building a new service implementation, I would suggest reporting the "latest" schema version you support, even if you don's support all of the "latest" property additions. That will at least indicate that you're aware of the latest versions, any errata, clarifications, or deprecated properties. But know also that it will set expectations from your users - it's fair for them to ask for functionality that has been defined by that version of schema. Hope that helps, Jeff |
|
|
|
Post by siaoleio on Feb 20, 2021 9:33:00 GMT
The question of schema version is more complex, but yes, we do tend to tell users what bundle version our services are "based on" - but if a user is expecting a specific resource or property, they really need to ask or consult the vendor documentation - because very few properties are required by specification. Hi jautor, Thanks a lot for your response. As I am new to the Odata and openAPI, can you help to answer the following questions?
1. Are the properties required by specification marked with " Nullable= 'false' " in the schema file?
In the ServiceRoot_v1.xml, I see the <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="ServiceRoot.v1_1_0"> has a new StorageSystem property:
' <NavigationProperty Name="StorageSystems" Type="StorageSystemCollection.StorageSystemCollection" Nullable="false"> '
This StorageSystem property is not defined in the <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="ServiceRoot.v1_0_0">.
So if my service can not provide the StorageSystem related information, I still need to keep this StorageSystem attribute with a link to the StorageSystemCollection which is a empty set.
My service cannot provide any information about StorageSystems, but my service can provide the empty StorageSystemCollection link, so it is still compliant with redfish specifications. Is this right?
For specific resources, such as chassis, as long as I return these attributes marked as ' Nullable= 'false' ' , it will meet the redfish specification, right?
2. What is the meaning of '<Annotation Term="Redfish.Required"/>' ？ For example, the following 'Links' properity in the ServiceRoot_v1.xml.
<ComplexType Name="Links" BaseType="Resource.Links">
<Annotation Term="OData.Description" String="The links to other Resources that are related to this Resource."/>
<Annotation Term="OData.LongDescription" String="The Redfish Specification-described type shall contain links to Resources related to but not subordinate to this Resource."/>
<NavigationProperty Name="Sessions" Type="SessionCollection.SessionCollection" Nullable="false">
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
<Annotation Term="OData.Description" String="The link to a collection of Sessions."/>
<Annotation Term="OData.LongDescription" String="This property shall contain a link to a Resource Collection of type SessionCollection."/>
<Annotation Term="OData.AutoExpandReferences"/>
<Annotation Term="Redfish.Required"/>
</NavigationProperty>
</ComplexType>
Thank you very much for your patience and help.
|
|
|
|
Post by jautor on Feb 21, 2021 22:20:25 GMT
1. Are the properties required by specification marked with " Nullable= 'false' " in the schema file? No, the few required properties are marked in schema with the "Redfish.Required" annotation (CSDL), or shown in the "required" attribute in JSON schema. For getting started, I would highly recommend using the Redfish Resource and Schema Guide (DSP2046) instead of reading the schema files directly. That document captures all the important information and presents it in a much more human-friendly document. www.dmtf.org/sites/default/files/standards/documents/DSP2046_2020.4.pdfNo, those links are not required (see above), and your service does not, and should not, provide empty links or properties that would never be populated in your implementation. Very few properties are required, and we certainly try to minimize the amount of overhead you have to implement just for the sake of the standard. It's just the "required" properties, which, for example, in the Chassis schema, are: "@odata.id", "@odata.type", "Name", "Id", and "ChassisType". Sorry for the confusion from the schema definitions - while Redfish uses a subset of the OData specification and the CSDL schema language (one of 4 schema languages that we support), everything you need to know regarding OData is contained within the Redfish Specification itself... Jeff |
|
