Document Identifier: DSP2046

Date: 2021-01-18

Version: 2020.4

Redfish Resource and Schema Guide

Copyright Notice

Copyright © 2016-2021 DMTF. All rights reserved.

DMTF is a not-for-profit association of industry members dedicated to promoting enterprise and systems management and interoperability. Members and non-members may reproduce DMTF specifications and documents, provided that correct attribution is given. As DMTF specifications may be revised from time to time, the particular version and release date should always be noted.

Implementation of certain elements of this standard or proposed standard may be subject to third party patent rights, including provisional patent rights (herein "patent rights"). DMTF makes no representations to users of the standard as to the existence of such rights, and is not responsible to recognize, disclose, or identify any or all such third party patent right, owners or claimants, nor for any incomplete or inaccurate identification or disclosure of such rights, owners or claimants. DMTF shall have no liability to any party, in any manner or circumstance, under any legal theory whatsoever, for failure to recognize, disclose, or identify any such third party patent rights, or for such party's reliance on the standard or incorporation thereof in its product, protocols or testing procedures. DMTF shall have no liability to any party implementing such standard, whether such implementation is foreseeable or not, nor to any patent owner or claimant, and shall have no liability or responsibility for costs or losses incurred if a standard is withdrawn or modified after publication, and shall be indemnified and held harmless by any party implementing the standard from any and all claims of infringement by a patent owner for such implementations.

For information about patents held by third-parties that have notified the DMTF that, in their opinion, such patent may relate to or impact implementations of DMTF standards, visit http://www.dmtf.org/about/policies/disclosures.php.

This document's normative language is English. Translation into other languages is permitted.

Contents

Overview

The Redfish standard comprises a set of specifications maintained by the Redfish Forum, a working group within the DMTF. The standard defines a protocol that uses RESTful interfaces to provide access to data and operations associated with the management of systems and networks. One of the strengths of the Redfish protocol is that it works with a wide range of servers: from stand-alone servers to rack-mount and bladed environments to large-scale data centers and cloud environments.

The Redfish standard addresses several key issues for infrastructures that require scalability. Large infrastructures often consist of many simple servers of different makes and types. This hyper-scale usage model requires a new approach to systems management. The Redfish protocol addresses these needs by providing a standard protocol based on out-of-band systems management.

With these goals in mind, the Redfish protocol was designed as an open-industry standard to meet scalability requirements in multi-vendor deployments. It easily integrates with commonly used tools, using RESTful interfaces to perform operations and using JSON and OData formats for data payloads.

Who should read this document?

This document is useful to people who want to understand how to use the Redfish API. This includes application developers who want to create client-side software to communicate with a Redfish Service, and other consumers of the API.

How can I provide feedback?

Feedback on all Redfish specifications and documents is encouraged. Feedback can be directed to the DMTF and the Redfish Forum by the following means:

• Redfish User Forum: http://www.redfishforum.com User forum monitored by DMTF Redfish Forum personnel to answer questions about any Redfish-related topics.
• DMTF Feedback Portal: https://www.dmtf.org/standards/feedback Formal submission portal for enhancements or proposals to the DMTF and Redfish Forum.

Where can I find more information?

These web sites provide more information about the Redfish standard:

• Redfish Developer Hub: http://redfish.dmtf.org Resources for developers building applications using Redfish. An interactive schema explorer, hosted schema and other links.
• Redfish User Forum: http://www.redfishforum.com User forum monitored by DMTF Redfish personnel to answer questions about any Redfish-related topics:
• DMTF Github Repositories: http://www.github.com/DMTF Open source tools and libraries for working with Redfish.
• Redfish Standards: http://www.dmtf.org/standards/redfish Schemas, specs, mockups, white papers, FAQ, educational material and more.
• DMTF Redfish Forum (Working group that maintains the Redfish standard): http://www.dmtf.org/standards/spmf Companies involved, upcoming schedules and future work, charter, and information about joining.

Using this guide

Every Redfish response consists of a JSON payload containing properties that are strictly defined by a schema for that Resource. The schema defining a particular Resource can be determined from the value of the "@odata.type" property returned in every Redfish response. This guide details the definitions for every Redfish standard schema.

Each schema section contains:

• The schema's name, its current version, and description.
• The schema release history, which lists each minor schema version and the DSP8010 release bundle that includes it.
• The list of URIs where schema-defined Resources appear in a Redfish Service v1.6 and later. For more information, see URI listings.
• The table of properties, which includes additional property details, when available.
• The list of available schema-defined actions.
• The example schema-defined JSON payload for a Resource.

The property-level details include:

URI listings

The Redfish Specification v1.6.0 added mandatory OpenAPI Specification v3.0 support. As part of this support, the URIs for every Redfish Resource are defined to appear at known, fixed locations. Resource Collections also appear at fixed locations, with the members of each collection appearing at URIs constructed by using a fixed path structure, with appropriate path segments equal to the value of Id properties of members along the path.

To determine support for v1.6.0 and OpenAPI, compare the RedfishVersion property value in the Service root (\redfish\v1\). Services that report a 1.6.0 or greater value, such as 1.6.1 or 1.7.0, adhere to the URI definitions shown.

The URI listings do not apply to Redfish Services that report support of versions earlier than Specification v1.6.0. For those Services, clients must use the API's hypermedia features to discover links from the Service root to each Resource. While Services typically match the URIs listed in this documents for many of their Resources, this is not guaranteed and results in errors.

Common properties

Properties that all Redfish schemas define

The following properties are defined for inclusion in every Redfish schema, and therefore may be encountered in any response payload. They are documented in this guide to avoid repetition in the Reference Guide property tables. Note that several of these properties are payload annotations, but appear in this guide because they are required for all Redfish Resources.

Frequently used properties

In addition, the following properties are frequently defined in Redfish schemas. Their definition and usage is the same throughout the Redfish data model.

Payload annotations

Payload annotations enable a Service to provide additional information about a property or object. Redfish limits usage of these annotations to OData core terms, Redfish extensions, or Redfish messages.

Property-level annotations

A payload annotation for a single property takes the form of an additional property:

Property@Schema.Term

where

In this example, the ResetType property is annotated with the AllowableValues term, which the Redfish schema defines. Redfish is an alias for RedfishExtensions. This code indicates to the client that the Service supports the On and ForceOff values for ResetType.

{
    "ResetType@Redfish.AllowableValues": [
        "On",
        "ForceOff"
    ]
}

Resource or object-level annotations

A payload annotation for an entire Resource or a JSON object takes the @Schema.Term form, where Namespace is the schema file where the definition is found and Term is the name of the Annotation. These payload annotations are used to provide further information about the object itself.

This example annotates the object with the Redfish schema-defined ActionInfo term. Redfish is an alias for RedfishExtensions. This term indicates that the client can find more information about the #ComputerSystem.Reset action at the /redfish/v1/Systems/1/ResetActionInfo URI:

{
    "#ComputerSystem.Reset": {
        "target": "/redfish/v1/Systems/1/Actions/ComputerSystem.Reset",
        "@Redfish.ActionInfo": "/redfish/v1/Systems/1/ResetActionInfo"
    }
}

Common objects

Redfish schemas frequently define the following JSON objects. Like the individual common properties listed above, these objects share a common definition that is shown here to avoid repetition in the Reference Guide property tables.

Actions

The Actions object contains descriptions of the defined and available actions for this Resource.

Capacity

This is the schema definition for the Capacity of a device. It represents the properties for capacity for any data store.

Identifier

Any additional identifiers for a resource.

IOStatistics

The properties of this type represent IO statistics.

IPv4Address

This type describes an IPv4 address.

IPv6Address

This type describes an IPv6 address.

IPv6GatewayStaticAddress

This type represents a single IPv6 static address to be assigned on a network interface.

IPv6StaticAddress

This type represents a single IPv6 static address to be assigned on a network interface.

Location

The location of a resource.

MaintenanceWindow

The maintenance window assignment for applying settings or operations to a resource.

Message

The message that the Redfish service returns.

OperationApplyTimeSupport

The client can request a specific apply time of a create, delete, or action operation of a resource.

PreferredApplyTime

The preferred time to apply configuration settings.

Redundancy

A reference to a set of Redundancy entities that provide redundant Services for this Resource. See the Redundancy object definition in the Common objects section.

RedundantGroup

The redundancy information for the devices in a redundancy group.

ReplicaInfo

Defines the characteristics of a replica of a source.

Schedule

Schedule a series of occurrences.

Settings

The resource settings.

Status

The status and health of a resource and its children.

Resource collections

A core concept in Redfish is a collection of Resources. A collection is a group of like Resources where the number of instances in the group can shrink or grow depending on the scope of the Redfish Service or the configuration of the devices being managed. Every Resource in a collection has the same set of supported properties, and all contain Collection in the name of their schema. Every Resource linked in the Members array within a Resource Collection have the same Resource type, or the same schema with the same major version, but can vary in minor or errata schema versions, which are all compatible.

The properties of a Resource Collection are as follows:

As shown in the following example, a Redfish Service may provide management functionality for several Computer Systems, and therefore a ComputerSystemCollection Resource is provided. This example shows a Service with multiple ComputerSystem instances, or members.

{
    "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection",
    "Name": "Computer System Collection",
    "Members@odata.count": 4,
    "Members": [{
            "@odata.id": "/redfish/v1/Systems/529QB9450R6"
        },
        {
            "@odata.id": "/redfish/v1/Systems/529QB9451R6"
        },
        {
            "@odata.id": "/redfish/v1/Systems/529QB9452R6"
        },
        {
            "@odata.id": "/redfish/v1/Systems/529QB9453R6"
        }
    ],
    "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection",
    "@odata.id": "/redfish/v1/Systems"
}

Resource collection URIs for Redfish v1.6 and later

The following table lists the Redfish-defined Resource Collections and the URIs where they can appear. NOTE: The URIs listed are valid for Redfish Services conforming to the Redfish Specification v1.6.0 or higher. Services built on earlier versions of the Specification may use different URIs. To discover these URIs, follow the links from the Service Root (/redfish/v1/).

Reference Guide

To produce this guide, DMTF's Redfish Documentation Generator merges the DMTF Redfish Schema bundle (DSP8010) contents with supplemental text.

AccelerationFunction 1.0.3

The AccelerationFunction schema describes an acceleration function that a processor implements. This can include functions such as audio processing, compression, encryption, packet inspection, packet switching, scheduling, or video processing.

URIs:

• /​redfish/​v1/​CompositionService/​ResourceBlocks/​{ResourceBlockId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}
• /​redfish/​v1/​CompositionService/​ResourceBlocks/​{ResourceBlockId}/​Systems/​{ComputerSystemId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}
• /​redfish/​v1/​ResourceBlocks/​{ResourceBlockId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}
• /​redfish/​v1/​ResourceBlocks/​{ResourceBlockId}/​Systems/​{ComputerSystemId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}
• /​redfish/​v1/​Systems/​{ComputerSystemId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}

Example response

{
    "@odata.type": "#AccelerationFunction.v1_0_3.AccelerationFunction",
    "Id": "Compression",
    "Name": "Compression Accelerator",
    "Status": {
        "State": "Enabled",
        "Health": "OK"
    },
    "FpgaReconfigurationSlots": [
        "AFU0"
    ],
    "AccelerationFunctionType": "Compression",
    "Manufacturer": "Intel (R) Corporation",
    "Version": "Green Compression Type 1 v.1.00.86",
    "PowerWatts": 15,
    "Links": {
        "Endpoints": [],
        "PCIeFunctions": []
    },
    "Oem": {},
    "@odata.id": "/redfish/v1/Systems/1/Processors/FPGA1/AccelerationFunctions/Compression"
}

AccountService 1.8.0

The AccountService schema defines an account service. The properties are common to, and enable management of, all user accounts. The properties include the password requirements and control features, such as account lockout. The schema also contains links to the manager accounts and roles.

URIs:

• /​redfish/​v1/​AccountService
• /​redfish/​v1/​Managers/​{ManagerId}/​RemoteAccountService

Example response

{
    "@odata.type": "#AccountService.v1_8_0.AccountService",
    "Id": "AccountService",
    "Name": "Account Service",
    "Description": "Local Manager Account Service",
    "Status": {
        "State": "Enabled",
        "Health": "OK"
    },
    "ServiceEnabled": true,
    "AuthFailureLoggingThreshold": 3,
    "MinPasswordLength": 8,
    "AccountLockoutThreshold": 5,
    "AccountLockoutDuration": 30,
    "AccountLockoutCounterResetAfter": 30,
    "AccountLockoutCounterResetEnabled": true,
    "Accounts": {
        "@odata.id": "/redfish/v1/AccountService/Accounts"
    },
    "Roles": {
        "@odata.id": "/redfish/v1/AccountService/Roles"
    },
    "LocalAccountAuth": "Enabled",
    "LDAP": {
        "AccountProviderType": "LDAPService",
        "ServiceEnabled": false,
        "ServiceAddresses": [
            "ldaps://ldap.example.org:636"
        ],
        "Authentication": {
            "AuthenticationType": "UsernameAndPassword",
            "Username": "cn=Manager,dc=example,dc=org",
            "Password": null
        },
        "LDAPService": {
            "SearchSettings": {
                "BaseDistinguishedNames": [
                    "dc=example,dc=org"
                ],
                "UsernameAttribute": "uid",
                "GroupsAttribute": "memberof"
            }
        },
        "RemoteRoleMapping": [
            {
                "RemoteUser": "cn=Manager,dc=example,dc=org",
                "LocalRole": "Administrator"
            },
            {
                "RemoteGroup": "cn=Admins,ou=Groups,dc=example,dc=org",
                "LocalRole": "Administrator"
            },
            {
                "RemoteGroup": "cn=PowerUsers,ou=Groups,dc=example,dc=org",
                "LocalRole": "Operator"
            },
            {
                "RemoteGroup": "(cn=*)",
                "LocalRole": "ReadOnly"
            }
        ]
    },
    "ActiveDirectory": {
        "AccountProviderType": "ActiveDirectoryService",
        "ServiceEnabled": true,
        "ServiceAddresses": [
            "ad1.example.org",
            "ad2.example.org",
            null,
            null
        ],
        "Authentication": {
            "AuthenticationType": "KerberosKeytab",
            "KerberosKeytab": null
        },
        "RemoteRoleMapping": [
            {
                "RemoteGroup": "Administrators",
                "LocalRole": "Administrator"
            },
            {
                "RemoteUser": "DOMAIN\\Bob",
                "LocalRole": "Operator"
            },
            {
                "RemoteGroup": "PowerUsers",
                "LocalRole": "Operator"
            },
            {
                "RemoteGroup": "Everybody",
                "LocalRole": "ReadOnly"
            }
        ]
    },
    "AdditionalExternalAccountProviders": {
        "@odata.id": "/redfish/v1/AccountService/ExternalAccountProviders"
    },
    "@odata.id": "/redfish/v1/AccountService"
}

ActionInfo 1.1.2

The ActionInfo schema defines the supported parameters and other information for a Redfish action. Supported parameters can differ among vendors and even among Resource instances. This data can ensure that action requests from applications contain supported parameters.

Example response

{
    "@odata.type": "#ActionInfo.v1_1_2.ActionInfo",
    "Id": "ResetActionInfo",
    "Name": "Reset Action Info",
    "Parameters": [
        {
            "Name": "ResetType",
            "Required": true,
            "DataType": "String",
            "AllowableValues": [
                "On",
                "ForceOff",
                "GracefulShutdown",
                "GracefulRestart",
                "ForceRestart",
                "Nmi",
                "ForceOn",
                "PushPowerButton"
            ]
        }
    ],
    "Oem": {},
    "@odata.id": "/redfish/v1/Systems/1/ResetActionInfo"
}

AddressPool 1.1.1

The schema definition of an address pool and its configuration.

URIs:

• /​redfish/​v1/​Fabrics/​{FabricId}/​AddressPools/​{AddressPoolId}