Annotation confusion in many Assertions about redfish-service-conformance-check HOT 6 CLOSED

I took a look at the spec, the schemas and the output of the tool for this assertion (as well as several other similar assertions as mentioned in issue #57).

The applicable section of the spec is 7.5 Schema definition. In 7.5.1. Common annotations it generally states:

    All Redfish types and properties shall include description and long description annotations.

And then in subsequent subsections, it makes more specific requirements that these resources and types require Description and LongDescription annotations. Here is a summary:

7.5.3. Resource type definitions (<EntityType> elements, tested by Assertion_7_5_3())

    All resources shall include Description and LongDescription annotations.

7.5.4. Resource properties (<Property> elements, tested by Assertion_7_5_5())

    All properties shall include Description and LongDescription annotations.

7.5.4.1.2. Structured types (<ComplexType> elements, tested by Assertion_7_5_8())

    Structured types shall include Description and LongDescription annotations.

7.5.4.1.3. Enums (<EnumType> elements, tested by Assertion_7_5_9())

    Enumeration Types shall include Description and LongDescription annotations.

7.5.5. Reference properties (<NavigationProperty> elements, tested by Assertion_7_5_16())

    All reference properties shall include Description and LongDescription annotations.

Now, looking at the first couple of errors emitted by the tool for assertion 7_5_3:

~ Resource: ChassisCollection, BaseType: Resource.1.0.0.ResourceCollection and any of its parent BaseType resources (based on inheritance) does not have annotation 'OData.Description' in its OData schema representation document: redfish-1.0.0/metadata/ChassisCollection.xml

~ Resource: ChassisCollection, BaseType: Resource.1.0.0.ResourceCollection and any of its parent BaseType resources (based on inheritance) does not have annotation 'OData.LongDescription' in its OData schema representation document: redfish-1.0.0/metadata/ChassisCollection.xml

Then if we look at ChassisCollection.xml, the <EntityType> element is:

      <EntityType Name="ChassisCollection" BaseType="Resource.1.0.0.ResourceCollection">
        <NavigationProperty Name="Members" Type="Collection(Chassis.Chassis)">
          <Annotation Term="OData.Permissions" EnumMember="OData.Permissions/Read"/>
          <Annotation Term="OData.Description" String="Contains the members of this collection."/>
          <Annotation Term="OData.AutoExpandReferences"/>
        </NavigationProperty>
      </EntityType>

And indeed the ChassisCollection <EntityType> does not contain an OData.Description or OData.LongDescription annotation. (Note there is an OData.Description annotation in the schema snippet above, but that is of course for the <NavigationProperty>, not the <EntityType>.)

So, from my reading of the spec, the tool is correctly flagging these missing OData.Description and OData.LongDescription annotations in the schemas.

Since there were hundreds of such instances flagged, I only spot checked the output of the tool assertions 7_5_3, 7_5_5, 7_5_8, 7_5_9 and 7_5_16. But every one I checked correctly identified a missing but required annotation.

from redfish-service-conformance-check.

So .... does that mean the schemas are incorrect?
Or that our APIs are incorrect?
Or both?
Thanks.

from redfish-service-conformance-check.

It looks like a schema problem to me.

There's no API problem; those annotations are for human consumption.

from redfish-service-conformance-check.

@billdodd will file an issue in the SPMF to discuss further; the spec does state that Descriptions and LongDescriptions are mandatory. We've been making several fixes over the months in this space, but have not completed it.

from redfish-service-conformance-check.

SPMF Issue filed. Think this issue (and #57) can be closed now.

from redfish-service-conformance-check.

Closing; issue has been migrated and schemas will be updated in the future.

from redfish-service-conformance-check.