Validating a collection

[commonism]

Hi,

I'm wondering how to match this collection to the openapi description document:

The specialty is embedding the Members body into the collections Members.

    "Members": [
        {
            "@odata.id": "/redfish/v1/Managers/BMC/LogServices/Log/Entries/1",
            "@odata.type": "#LogEntry.v1_16_1.LogEntry",
            "Id": "1",
            "Name": "Log Entry 1",
            "EntryType": "Event",
            "Severity": "Critical",
            "Created": "2020-03-30T07:44:35-05:00",
            "SensorNumber": 1,
            "Message": "System May be Melting",
            "MessageId": "Event.1.0.TempWayTooHot",
            "MessageArgs": [
                "88"
            ],
            "Links": {
                "OriginOfCondition": {
                    "@odata.id": "/redfish/v1/Chassis/1/Thermal"
                }
            }
        }
    ],

https://github.com/DMTF/Redfish-Publications/blob/5b217908b5378b24e4f390c063427d7a707cd308/mockups/public-nvmeof-jbof/Managers/BMC/LogServices/Log/Entries/index.json#L6-L27

[mraineri]

Well, as far as the service validator is concerned, it doesn't use OpenAPI at all to verify resources; it's designed around parsing CSDL for understanding the data model. In LogEntryCollection_v1.xml, the "Members" property is annotated with "OData.AutoExpand" to indicate the members are expanded inline the response. Members also points to the data type "LogEntry" to express what data to expect when following the references.

In OpenAPI, we carry forward the OData.AutoExpand term as "x-autoExpand" to signify the references will have their payloads expanded:

        Members:
          description: The members of this collection.
          items:
            $ref: http://redfish.dmtf.org/schemas/v1/odata-v4.yaml#/components/schemas/odata-v4_idRef
          readOnly: true
          type: array
          x-autoExpand: true      <--- Comes from OData.AutoExpand in CSDL
          x-longDescription: This property shall contain an array of links to the
            members of this collection.

Now... as I'm looking at that snippet, I'm realizing we made a decision a while ago to always turn references in OpenAPI to simply point to "odata-v4_idRef" to not inadvertently blow up code stubs and documentation... Pointing to the full definition everywhere is not correct.... But, I'm wondering if we need to be a bit more intelligent about this for auto-expanded definitions. Maybe we can point to the resource definition instead of odata-v4_idRef and remove the need for x-autoExpand?

[commonism]

I guess proper defined autoexpand would look similar to

        Members:
          description: The members of this collection.
          items:
            type: object
            oneOf:
            - $ref: http://redfish.dmtf.org/schemas/v1/odata-v4.yaml#/components/schemas/odata-v4_idRef
            - $ref: "#/components/schemas/LogEntry"

in OpenAPI and would be the required compatibility glue for the status quo.

But this depends on if you want to stick to (odata) features which are inconvenient to specify in openapi.

[mraineri]

In this case it wouldn't be a oneOf; I would suggest it looking something like this:

        Members:
          description: The members of this collection.
          items:
            $ref: http://redfish.dmtf.org/schemas/v1/LogEntry.v1_16_1.yaml#/components/schemas/LogEntry_v1_16_1_LogEntry