Clarifications related to PATCH on Array Properties

ginugeorge
Minnow

Posts: 28

Clarifications related to PATCH on Array Properties Dec 8, 2022 18:23:34 GMT

Quote

Post by ginugeorge on Dec 8, 2022 18:23:34 GMT

Consider the attribute "SupportedCollectionFunctions" under the Telemetry Service Root URI /redfish/v1/TelemetryService has the below mentioned values :

{
    .....,

    "SupportedCollectionFunctions": [
        "Average",
        "Maximum",
        "Minimum",
        "Summation"
    ],
    .....
}

Consider that an end-user is trying to modify the values of the SupportedCollectionFunction, which is an array type attribute, by issuing a PATCH request. Please help to clarify the below mentioned points :

1. Does the below mentioned rule needs to be mandatorily applied to all array type attributes mentioned in the Redfish Schema ? or it it optional ?

7.7 PATCH on array properties
The Array properties clause describes the three styles of array properties in a resource.
Within a PATCH request, the service shall accept null to remove an element, and accept an empty object {} to
leave an element unchanged. Array properties that use the fixed or variable length style remove those elements,
while array properties that use the rigid style replace removed elements with null elements. A service may indicate
the maximum size of an array by padding null elements at the end of the array sequence.

2. Please help to explain the below statement with the help of an example :

Array properties that use the fixed or variable length style remove those elements,
while array properties that use the rigid style replace removed elements with null elements.

3. What will be the value of the attribute "SupportedCollectionFunctions" if the user tries to pass the below request body in PATCH :

{
    .....,

    "SupportedCollectionFunctions": [
        {},
        {},
        {}
    ],
    .....
}

4. What will be the value of the attribute "SupportedCollectionFunctions" if the user tries to pass the below request body in PATCH :

{
    .....,

    "SupportedCollectionFunctions": [
        null,
        null,
        null
    ],
    .....
}

5. What will be the value of the attribute "SupportedCollectionFunctions" if the user tries to pass the below request body in PATCH :

{
    .....,

    "SupportedCollectionFunctions": [
        "Average",
        null,
        "Minimum",
        {}
    ],
    .....
}

Last Edit: Dec 8, 2022 18:24:27 GMT by ginugeorge

mraineri
Administrator

Posts: 1,048

Clarifications related to PATCH on Array Properties Dec 8, 2022 19:22:38 GMT

Quote

Post by mraineri on Dec 8, 2022 19:22:38 GMT

1. That rule is mandatory. Without it, there is no interoperability in with array manipulation.

2. Fixed and variable length arrays do not have "empty slots" in the middle of the array; when you remove a value from the array, the service shifts values up in the array's order. The "PATCH on array properties" section has an example of this behavior. Rigid arrays do not have this shifting behavior; rigid arrays, by definition, maintain their array positions for all members (hence their rigidness). However, we have no rigid arrays in the model at this time.

3. It will be "SupportedCollectionFunctions": [ "Average", "Maximum", "Minimum" ]. You told the service to "leave the first three members alone, and delete the remaining members".

4. It will be "SupportedCollectionFunctions": []. You told the service to "delete the first three members, and delete the remaining members".

5. It will be "SupportedCollectionFunctions": [ "Average", "Minimum" ]. You told the service to set the first member to "Average", delete the second member, set the third member to "Minimum", and delete the remaining members.

However, looking at this specific example, I do not know why "SupportedCollectionFunctions" is writable in the first place. From the semantics of the property, this looks like a capability of the service, meaning it should be read-only.

ginugeorge
Minnow

Posts: 28

Clarifications related to PATCH on Array Properties Dec 13, 2022 8:43:02 GMT

Quote

Post by ginugeorge on Dec 13, 2022 8:43:02 GMT

With reference to the Telemetry schema redfish.dmtf.org/schemas/v1/TelemetryService.v1_2_1.json

We can see that the attribute SupportedCollectionFunctions is a read-write attribute

"SupportedCollectionFunctions": {
     "description": "The functions that can be performed over each metric.",
     "items": {
          "anyOf": [
               {
                    "$ref": "#/definitions/CollectionFunction"
               },
               {
                    "type": "null"
               }
           ]
     },
     "longDescription": "This property shall contain the function to apply over the collection duration.",
     "readonly": false,
     "type": "array"
}

Do you mean that the attribute SupportedCollectionFunctions must be a read-only attribute and that the schema needs an update ? Please advise.

Last Edit: Dec 13, 2022 8:43:42 GMT by ginugeorge

mraineri
Administrator

Posts: 1,048

Clarifications related to PATCH on Array Properties Dec 13, 2022 14:07:38 GMT

Quote

Post by mraineri on Dec 13, 2022 14:07:38 GMT

Yes, the schema currently marks the "SupportedCollectionFunctions" as writable. However, this looks like a mistake; the usage of the property should be for a client to discover what the service supports (which can affect how a client describes desired metric reports); clients cannot program new capabilities in a service. I'm raising this with others to see if we need to fix the schema to show the property is read-only.

Last Edit: Dec 13, 2022 14:07:46 GMT by mraineri

AMI_Mani
Tuna

AMI

Posts: 175

Clarifications related to PATCH on Array Properties Apr 16, 2023 5:24:20 GMT

Quote

Post by AMI_Mani on Apr 16, 2023 5:24:20 GMT

Hi,

We have below point in specification related to patching array attributes

A PATCH request with fewer elements than in the current array shall remove the remaining elements of the array.

Assume implementation supports empty object({}) to leave an element unchanged, then support null to remove an element, do we need to support above point also?

Below is the post request for Composed system and ResourceBlocks is an array

POST /redfish/v1/Systems HTTP/1.1

Content-Type: application/json;charset=utf-8

Content-Length: <computed length>

OData-Version: 4.0

{

"Name": "Sample Composed System",

"Links": {

"ResourceBlocks": [{

"@odata.id": "/redfish/v1/CompositionService/ResourceBlocks/ComputeBlock0"

}, {

"@odata.id": "/redfish/v1/CompositionService/ResourceBlocks/DriveBlock2"

}, {

"@odata.id": "/redfish/v1/CompositionService/ResourceBlocks/NetBlock4"

}]

}

After composed system, User can patch ResourceBlocks,

If user provide patch request like below

Scenario 1
PATCH /redfish/v1/Systems/NewSystem, please try below requests.

Request:

(1) {

"Links": {

"ResourceBlocks": [

{

"@odata.id": "/redfish/v1/CompositionService/ResourceBlocks/ComputeBlock0"

}

]

}

}
Do we need to remove DriveBlock2, NetBlock4 after patch request?

Scenario 2
PATCH /redfish/v1/Systems/NewSystem, please try below requests.

Request:

(1) {

"Links": {

"ResourceBlocks": [

{

null,
"@odata.id": "/redfish/v1/CompositionService/ResourceBlocks/ComputeBlock0",

null
}

]

}

}

As per this scenario DriveBlock2, NetBlock4 will be removed

Is implementation needs to support both Scenario 1, Scenario 2 or can support any one Scenario in this use case?
Please explain based on A PATCH request with fewer elements than in the current array shall remove the remaining elements of the array.

Thanks,
Mani

jautor
Administrator

Posts: 502

Clarifications related to PATCH on Array Properties Apr 17, 2023 0:47:41 GMT

Quote

Post by jautor on Apr 17, 2023 0:47:41 GMT

Yes, you must support that to avoid interoperability issues... Without that support, a client would be required to GET the resource to discover the number of array elements, in order to PATCH to replace the entire array. In other words, with the exception of the empty object or a null element, the entire array is replaced with the value in the PATCH. It's those exceptions that allow short cuts to make it easier to modify an array from a simple script or by a manually crafted command.

Your Scenario 2 has those elements in the wrong order (should be ["ComputeBlock0", null, null]), but yes, both of those must work and would produce the same results. In addition, the easiest way for a client to perform this would be a PATCH with a single empty object to "preserve" the existing value:

"ResourceBlocks": [ {} ]

or even
"ResourceBlocks": [ {}, null, null]

Jeff

AMI_Caffrey Minnow Posts: 39	Clarifications related to PATCH on Array Properties Jul 14, 2023 3:56:29 GMT Quote Select Post Deselect Post Link to Post Back to Top Post by AMI_Caffrey on Jul 14, 2023 3:56:29 GMT hi, I see in latest schema, "SupportedCollectionFunctions" is still writable. Please kindly arrange schema update if its need to be corrected. Thank you. BR, Caffrey

jautor
Administrator

Posts: 502

Clarifications related to PATCH on Array Properties Jul 14, 2023 4:39:14 GMT

Quote

Post by jautor on Jul 14, 2023 4:39:14 GMT

Jul 14, 2023 3:56:29 GMT AMI_Caffrey said:

hi,

I see in latest schema, "SupportedCollectionFunctions" is still writable. Please kindly arrange schema update if its need to be corrected.
Thank you.

BR,
Caffrey

It has been corrected in the latest schema (DSP8010 2023.1), TelemetryService.v1_2_4 or TelemetryService.v1_3_2.

If you're seeing something different, let me know.

Jeff

AMI_Caffrey Minnow Posts: 39	Clarifications related to PATCH on Array Properties Jul 14, 2023 5:30:18 GMT Quote Select Post Deselect Post Link to Post Back to Top Post by AMI_Caffrey on Jul 14, 2023 5:30:18 GMT Hi Jeff, Thanks for the reminder. I was checking TelemetryService.v1_3_1.json. BR, Caffrey

Clarifications related to PATCH on Array Properties

Post by ginugeorge on Dec 8, 2022 18:23:34 GMT

Post by mraineri on Dec 8, 2022 19:22:38 GMT

Post by ginugeorge on Dec 13, 2022 8:43:02 GMT

Post by mraineri on Dec 13, 2022 14:07:38 GMT

Post by AMI_Mani on Apr 16, 2023 5:24:20 GMT

Post by jautor on Apr 17, 2023 0:47:41 GMT

Post by AMI_Caffrey on Jul 14, 2023 3:56:29 GMT

Post by jautor on Jul 14, 2023 4:39:14 GMT

Post by AMI_Caffrey on Jul 14, 2023 5:30:18 GMT