Some questions about metadata, validator, and specification

siaoleio
Minnow

Posts: 11

Some questions about metadata, validator, and specification Mar 29, 2021 2:04:07 GMT

Quote

Post by siaoleio on Mar 29, 2021 2:04:07 GMT

Hello everyone,

I meet some questions when developing the redfish service, thank you very much for your help.

1)Is the metadata file created by the developer himself? When the developer tell the user the redfish service use the DSP8010_2019.2 as the schema files, do the versions shown in the metadata file must all be the highest versions of the csdl xml files in the DSP8010_2019.2?

For example the metadata file shows the chassis version is:

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Chassis_v1.xml">

    <edmx:Include Namespace="Chassis"/>

    <edmx:Include Namespace="Chassis.v1_10_0"/>

  </edmx:Reference>

And the last Chassis version in the Chassis_v1.xml in DSP8010_2019.2 is also v1_10_0.

    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Chassis.v1_10_0">

      <Annotation Term="Redfish.OwningEntity" String="DMTF"/>

      <Annotation Term="Redfish.Release" String="2019.2"/>



      <EntityType Name="Chassis" BaseType="Chassis.v1_9_2.Chassis">

        <NavigationProperty Name="PCIeDevices" Type="PCIeDeviceCollection.PCIeDeviceCollection" ContainsTarget="true" Nullable="false">

          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>

          <Annotation Term="OData.Description" String="The link to the collection of PCIe devices located in this chassis."/>

          <Annotation Term="OData.LongDescription" String="This property shall contain a link to a Resource Collection of type PCIeDeviceCollection."/>

          <Annotation Term="OData.AutoExpandReferences"/>

        </NavigationProperty>

      </EntityType>

    </Schema>

2)Currently, we are using the redfish service validator to check our service. The validator shows we hava a problem:

The validator shows the odata type "#Storage.v1_7_1.StorageController" in the storageControllers arry in the storage is not in the schema file.

The DSP8010_2019.2\csdl\Storage_v1.xml file related contents:

   <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Storage.v1_0_0">
      <Annotation Term="Redfish.OwningEntity" String="DMTF"/>
      <Annotation Term="Redfish.Release" String="2016.1"/>

      <EntityType Name="Storage" BaseType="Storage.Storage">
        <NavigationProperty Name="StorageControllers" Type="Collection(Storage.v1_0_0.StorageController)" ContainsTarget="true">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
          <Annotation Term="OData.Description" String="The set of storage controllers that this Resource represents."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain a set of the storage controllers that this Resource represents."/>
          <Annotation Term="OData.AutoExpand"/>
        </NavigationProperty>

.......................

  
  <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Storage.v1_7_0">
      <Annotation Term="Redfish.OwningEntity" String="DMTF"/>
      <Annotation Term="Redfish.Release" String="2019.1"/>
      <EntityType Name="Storage" BaseType="Storage.v1_6_1.Storage"/>
      <EntityType Name="StorageController" BaseType="Storage.v1_6_0.StorageController">
        <NavigationProperty Name="Ports" Type="PortCollection.PortCollection" ContainsTarget="true" Nullable="false">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
          <Annotation Term="OData.Description" String="The link to the collection of Ports that exist on the storage controller."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain a link to a Resource Collection of type PortCollection."/>
        </NavigationProperty>
        <Property Name="ControllerRates" Type="Storage.v1_7_0.Rates" Nullable="false">
          <Annotation Term="OData.Description" String="This property describes the various controller rates used for processes such as Volume Rebuild or Consistency Checks."/>
          <Annotation Term="OData.LongDescription" String="This object shall contain all the rate settings available on the controller."/>
        </Property>
      </EntityType>

      <ComplexType Name="Rates">
        <Annotation Term="OData.AdditionalProperties" Bool="false"/>
        <Annotation Term="OData.Description" String="This type describes the various controller rates used for processes such as Volume Rebuild or Consistency Checks."/>
        <Annotation Term="OData.LongDescription" String="This type shall contain all the rate settings available on the controller."/>
        <Property Name="RebuildRatePercent" Type="Edm.Int64">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/ReadWrite"/>
          <Annotation Term="OData.Description" String="The percentage of controller Resources used for rebuilding/repairing volumes."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain the percentage of controller Resources used for rebuilding Volumes."/>
          <Annotation Term="Validation.Minimum" Int="0"/>
          <Annotation Term="Validation.Maximum" Int="100"/>
        </Property>
        <Property Name="TransformationRatePercent" Type="Edm.Int64">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/ReadWrite"/>
          <Annotation Term="OData.Description" String="The percentage of controller Resources used for transforming volumes from one configuration to another."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain the percentage of controller Resources used for transforming Volumes."/>
          <Annotation Term="Validation.Minimum" Int="0"/>
          <Annotation Term="Validation.Maximum" Int="100"/>
        </Property>
        <Property Name="ConsistencyCheckRatePercent" Type="Edm.Int64">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permission/ReadWrite"/>
          <Annotation Term="OData.Description" String="The percentage of controller Resources used for performing a data consistency check on volumes."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain the percentage of controller Resources used for checking data consistency on Volumes."/>
          <Annotation Term="Validation.Minimum" Int="0"/>
          <Annotation Term="Validation.Maximum" Int="100"/>
        </Property>
      </ComplexType>

      <ComplexType Name="StorageControllerLinks" BaseType="Storage.v1_4_0.StorageControllerLinks">
        <NavigationProperty Name="PCIeFunctions" Type="Collection(PCIeFunction.PCIeFunction)">
          <Annotation Term="OData.Description" String="An array of links to the PCIe functions that the stroage controller produces."/>
          <Annotation Term="OData.LongDescription" String="This property shall link to a Resource of type PCIeFunction that represents the PCIe functions associated with this Resource."/>
          <Annotation Term="OData.AutoExpandReferences"/>
        </NavigationProperty>
      </ComplexType>
    </Schema>

    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Storage.v1_7_1">
      <Annotation Term="Redfish.OwningEntity" String="DMTF"/>
      <Annotation Term="OData.Description" String="This version was created to update descriptions that this schema defines."/>
      <EntityType Name="Storage" BaseType="Storage.v1_7_0.Storage"/>
    </Schema>

In my opinion, the Storage.v1_7_1 will continue to inherit from the parent BaseType, so the Storage.v1_7_1.StorageController is a correct type. When I modify the payload response @odata.type to "#Storage.v1_7_0.StorageController", the validator still shows an error. Is this a bug of the validator? Or can you tell me where did I go wrong?

And the storage related contents of my metadata shows below:
If there are something missing?

......  
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/SimpleStorageCollection_v1.xml">

    <edmx:Include Namespace="SimpleStorageCollection"/>

  </edmx:Reference>

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/SimpleStorage_v1.xml">

    <edmx:Include Namespace="SimpleStorage"/>

    <edmx:Include Namespace="SimpleStorage.v1_2_3"/>

  </edmx:Reference>

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/SoftwareInventoryCollection_v1.xml">

    <edmx:Include Namespace="SoftwareInventoryCollection"/>

  </edmx:Reference>

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/SoftwareInventory_v1.xml">

    <edmx:Include Namespace="SoftwareInventory"/>

    <edmx:Include Namespace="SoftwareInventory.v1_2_3"/>

  </edmx:Reference>

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/StorageCollection_v1.xml">

    <edmx:Include Namespace="StorageCollection"/>

  </edmx:Reference>

  <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Storage_v1.xml">

    <edmx:Include Namespace="Storage"/>

    <edmx:Include Namespace="Storage.v1_7_1"/>

  </edmx:Reference>
....

3) The redfish specification v1.12.0 shows:

6.5.2 Data-oriented

The Redfish data model is developed by focusing on the contents of the payload. By concentrating on the contents of

the payload first, Redfish payloads are easily mapped to schema definition languages and encoding types. The data

model is defined in various schema languages, including OpenAPI YAML, OData CSDL, and JSON Schema.

The specification shows "By concentrating on the contents of the payload first, Redfish payloads are easily mapped to schema definition languages and encoding types."

What is the meaning of encoding types? In my opinion, schema definition languages means the odata xml, odata json and openAPI yaml. Does encoding types mean the different xml or json format payloads?

Thanks for your answers and suggestions.

With kindest regards.

Last Edit: Mar 29, 2021 9:56:27 GMT by siaoleio

mraineri
Administrator

Posts: 1,134

Some questions about metadata, validator, and specification Mar 29, 2021 12:27:59 GMT siaoleio likes this

Quote

Post by mraineri on Mar 29, 2021 12:27:59 GMT

For question 1: Yes, it's up to the developer of the service to create the $metadata document. However, you do not need to simply copy every schema reference for a particular DSP8010 bundle; you only need to create references for what you implement. So, if your service implements Chassis version 1.10.0, then you would make a reference to "Chassis" and "Chassis.v1_10_0". The section "Metadata document" in this paper is a short guide for how you would build the file: www.dmtf.org/sites/default/files/standards/documents/DSP2052_1.0.0.pdf. It's best not to think about it in terms of "My $metadata needs to reflect a DSP8010 version", but rather think about it in terms of "My $metadata needs to reflect what my service has implemented".

For question 2: For embedded objects like "StorageController" within "Storage", we generally don't recommend implementing the @odata.type property. The versioning method we use in our resources focuses on making version numbers for the overall resource. So, the version is really controlled by the root-level @odata.type property ("#Storage.v1_7_1.Storage" in this case).

For question 3: The statement just reflects how we as a working group define the model. We start with specifying what we want users to see once a payload is received, and then build schema definitions from that. Over the wire, it could be JSON, but it could also be compressed JSON (with gzip). Redfish Device Enablement is another standard that defines a different encoding type to represent Redfish resources from a device in the system called "BEJ" (Binary Encoded JSON). A Redfish service wouldn't need to present BEJ to an external client since BEJ is used for a service to monitor devices within the system, but this is an example of another encoding type.

Last Edit: Mar 29, 2021 12:34:46 GMT by mraineri

siaoleio
Minnow

Posts: 11

Some questions about metadata, validator, and specification Mar 30, 2021 1:04:13 GMT

Quote

Post by siaoleio on Mar 30, 2021 1:04:13 GMT

Mar 29, 2021 12:27:59 GMT mraineri said:

For question 2: For embedded objects like "StorageController" within "Storage", we generally don't recommend implementing the @odata.type property. The versioning method we use in our resources focuses on making version numbers for the overall resource. So, the version is really controlled by the root-level @odata.type property ("#Storage.v1_7_1.Storage" in this case).

Hi Mraineri，

Thanks a lot for your answer.

With kindest regards.