1 Overview

The Redfish standard comprises a set of specifications maintained by the Redfish Forum, a working group within 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 for data payloads.

1.1 Who should read this document?

This document is useful to people who are consumers of the Redfish interface and want to understand the Redfish data model. These users might not be developing Redfish-enabled software.

1.2 How can I provide feedback?

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

• Redfish User Forum: https://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 DMTF and the Redfish Forum.

1.3 Where can I find more information?

The following web sites provide more information about the Redfish standard:

• Redfish Developer Hub

  Resources for developers who use Redfish to build applications. Contains an interactive schema explorer, hosted schema, and other links.

• Redfish Specification Forum

  DMTF Redfish-monitored user forum. Answers questions about Redfish-related topics.

• DMTF GitHub repositories

  Open source tools and libraries for working with Redfish.

• Redfish standards

  Schemas, specifications, mockups, white papers, FAQ, educational material, and more.

• DMTF Redfish Forum

  Working group that maintains the Redfish standard. Site lists member companies, future work and schedules, charter, and information about joining.

1.4 Related documents

The following documents are part of the Redfish development effort. They can be accessed or downloaded from DMTF's Redfish Standards web site: https://www.dmtf.org/standards/redfish

• DSP0218 - Platform Level Data Model (PLDM) for Redfish Device Enablement Specification - Binary-encoded JSON (BEJ) and dictionary-based mapping of Redfish schemas and properties into PLDM messages.
• DSP0266 - Redfish Specification - Main Redfish Specification.
• DSP0268 - Redfish Data Model Specification - Normative descriptions and additional text for every schema defined in DSP8010 and example payloads for every resource.
• DSP0270 - Redfish Host Interface Specification - "In-band" or "OS-based" Redfish host interface.
• DSP0272 - Redfish Interoperability Profiles Specification - Structure and JSON document that is used to define and publish an interoperability profile that checks an implementation's conformance to a defined minimum set of functionality.
• DSP2043 - Redfish Mockups Bundle - Set of mockups that can be used as sample output from GET responses from a Redfish service. Informative in nature, it was used to develop the schema. A person can set up an NGINX or similar server and configure it to output JSON format and then use this directory for demonstration purposes.
• DSP2044 - Redfish White Paper - Non-normative document helping those new to Redfish understand how to interact with the Redfish service and understand common functions and tasks.
• DSP2046 - Redfish Resource and Schema Guide - Informative documentation regarding common Redfish resource properties and a listing of properties that can be found in each of the Redfish resources.
• DSP2053 - Redfish Property Guide - Informative documentation providing an index to individual property definitions across all Redfish schema.
• DSP2065 - Redfish Message Registry Guide - Informative documentation providing details regarding the messages defined in Redfish standard message registries.
• DSP8010 - Redfish Schema - Redfish schema definitions. These files are normative in nature and are normatively referenced by the Redfish Specification. The three schema formats are CSDL (OData Common Schema Definition Language format, which is in XML), JSON Schema, and OpenAPI schema. These schema definitions should be functionally equivalent, thus specifying the schema in three different languages.
• DSP8011 - Redfish Standard Registries - Redfish registry definitions. This bundle of Redfish registries includes message registries used for Redfish-defined messages including events and privilege maps.
• DSP8013 - Redfish Interoperability Profiles Bundle - Bundle of published Redfish interoperability profile documents and supporting schema and sample documents used for creating profiles.

2 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 that defines a 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 name, current version, and description of the schema.
• The release history of the schema. Lists each minor schema version and the DSP8010 release bundle that included it.
• List of the possible URIs where schema-defined resources can appear in a Redfish service following specification version v1.6 or later. See URI listings.
• Table that defines each property. Shows additional details for those properties when needed.
• List of available actions defined for the schema.
• Example JSON payload for a resource using the schema.

The property-level details include:

2.1 URI listings

The Redfish Specification v1.6.0 added mandatory support for the OpenAPI Specification v3.0. 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.

Support for v1.6.0 and OpenAPI can be determined by comparing the value of the RedfishVersion property in the service root (/redfish/v1/). Services that report a 1.6.0 or higher value, such as 1.6.1 or 1.7.0, adhere to the URI definitions.

The URI listings do not apply to Redfish services that support specification versions earlier than v1.6.0. For those services, clients must use the hypermedia features of the API to discover hyperlinks from the service root to each resource. While services typically match the URIs listed in this document for many of their resources, this match is not guaranteed and results in errors.

3 Common properties

3.1 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 here in this guide to avoid repetition in the Reference guide property tables.

Note: Several of these properties are payload annotations but appear here because they are required for all Redfish resources.

3.1.1 Properties

3.2 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.

3.2.1 Properties

3.3 Payload annotations

Payload annotations are a mechanism in which a service provides additional information about a given property or object. Redfish limits usage of these annotations to OData core terms, Redfish extensions, or Redfish messages.

3.3.1 Property-level annotations

A payload annotation for a single property takes the form of an additional property named Property@Schema.Term, where Property is the JSON property being annotated, Schema is the schema file where the definition for the annotation is found, and Term is the name of the annotation.

3.3.2 Properties

In the following example, the property ResetType is annotated with the Redfish schema-defined AllowableValues term. Redfish is an alias for RedfishExtensions. This term indicates to the client that the service supports the values On and ForceOff for ResetType.

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

3.3.3 Resource-level or object-level annotations

A payload annotation for an entire Resource or a JSON object takes the @Schema.Term form, where Schema 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.

3.3.4 Properties

3.3.5 Property details

3.3.5.1 @Redfish.OperationApplyTime

The client's requested apply time to complete a create, delete, or action operation.

This example annotates the object with the Redfish schema-defined action info 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"
    }
}

4 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.

4.1 Actions

The Actions object contains the available actions for a resource.

4.1.1 Properties

4.2 Capacity

4.2.1 Description

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

4.2.2 Properties

4.3 Condition

4.3.1 Description

A condition that requires attention.

4.3.2 Properties

4.3.3 Property details

4.3.3.1 Severity

The severity of the condition.

4.4 Identifier

4.4.1 Description

Any additional identifiers for a resource.

4.4.2 Properties

4.4.3 Property details

4.4.3.1 DurableNameFormat

The format of the durable name property.

4.5 IOStatistics

4.5.1 Description

The properties of this type represent IO statistics.

4.5.2 Properties

4.6 IPv4Address

4.6.1 Description

This type describes an IPv4 address.

4.6.2 Properties

4.6.3 Property details

4.6.3.1 AddressOrigin

This indicates how the address was determined.

4.7 IPv6Address

4.7.1 Description

This type describes an IPv6 address.

4.7.2 Properties

4.7.3 Property details

4.7.3.1 AddressOrigin

This indicates how the address was determined.

4.7.3.2 AddressState

The current RFC4862-defined state of this address.

4.8 IPv6GatewayStaticAddress

4.8.1 Description

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

4.8.2 Properties

4.9 IPv6StaticAddress

4.9.1 Description

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

4.9.2 Properties

4.10 Location

4.10.1 Description

The location of a resource.

4.10.2 Properties

4.10.3 Property details

4.10.3.1 LocationType

The type of location of the part.

4.10.3.2 Orientation

The orientation for the ordering of the slot enumeration used by the LocationOrdinalValue property.

4.10.3.3 RackOffsetUnits

The type of rack units in use.

4.10.3.4 Reference

The reference point for the part location. Provides guidance about the general location of the part.

4.11 Message

4.11.1 Description

The message that the Redfish service returns.

4.11.2 Properties

4.11.3 Property details

4.11.3.1 MessageSeverity

The severity of the message.

4.12 Redundancy

4.12.1 Description

The common redundancy definition and structure used in other Redfish schemas.

4.12.2 Properties

4.12.3 Property details

4.12.3.1 Mode

The redundancy mode of the group.

4.13 RedundantGroup

4.13.1 Description

The redundancy information for the devices in a redundancy group.

4.13.2 Properties

4.13.3 Property details

4.13.3.1 RedundancyType

The redundancy mode of the group.

4.14 ReplicaInfo

4.14.1 Description

Defines the characteristics of a replica of a source.

4.14.2 Properties

4.14.3 Property details

4.14.3.1 ConsistencyState

The current state of consistency.

4.14.3.2 ConsistencyStatus

The current status of consistency.

4.14.3.3 ConsistencyType

Indicates the consistency type used by the source and its associated target group.

4.14.3.4 ReplicaFaultDomain

ReplicaFaultDomain describes the fault domain (local or remote) of the replica relationship.

4.14.3.5 ReplicaPriority

The priority of background copy engine I/O to be managed relative to host I/O operations during a sequential background copy operation.

4.14.3.6 ReplicaProgressStatus

The status of the session with respect to Replication activity.

4.14.3.7 ReplicaReadOnlyAccess

This property specifies whether the source, the target, or both elements are read only to the host.

4.14.3.8 ReplicaRecoveryMode

Describes whether the copy operation continues after a broken link is restored.

4.14.3.9 ReplicaRole

The source or target role of this replica.

4.14.3.10 ReplicaState

ReplicaState describes the state of the relationship with respect to Replication activity.

4.14.3.11 ReplicaType

ReplicaType describes the intended outcome of the replication.

4.14.3.12 ReplicaUpdateMode

Describes whether the target elements will be updated synchronously or asynchronously.

4.14.3.13 RequestedReplicaState

The last requested or desired state for the relationship.

4.14.3.14 UndiscoveredElement

This property specifies whether the source, the target, or both elements involved in a copy operation are undiscovered.

4.15 ResolutionStep

4.15.1 Description

This type describes a recommended step of the service-defined resolution.

4.15.2 Properties

4.15.3 Property details

4.15.3.1 ResolutionType

The type of the resolution step.

4.16 Schedule

4.16.1 Description

Schedule a series of occurrences.

4.16.2 Properties

4.16.3 Property details

4.16.3.1 EnabledDaysOfWeek

Days of the week when scheduled occurrences are enabled, for enabled days of the month and months of the year. If not present, all days of the week are enabled.

4.16.3.2 EnabledMonthsOfYear

The months of the year when scheduled occurrences are enabled. If not present, all months of the year are enabled.

4.17 Status

4.17.1 Description

The status and health of a resource and its children.

4.17.2 Properties

4.17.3 Property details

4.17.3.1 Health

The health state of this resource in the absence of its dependent resources.

4.17.3.2 HealthRollup

The overall health state from the view of this resource.

Methods used to determine the value of this property can vary between different architectures and requirements of the underlying product. This property does not necessarily surface the most degraded health from all subordinate resources. For example, if a PowerSupply resource contains Critical for its Health property, but belongs to a redundancy group that is still able to power the parent Chassis resource, the Chassis resource could report Warning for the HealthRollup property, depending on the redundancy policy for the Chassis resource. Using the same PowerSupply example, the ComputerSystem resource associated with this Chassis resource could degrade its HealthRollup, even though the PowerSupply resource is not subordinate to the ComputerSystem resource. In this case, the ComputerSystem resource is dependent on the PowerSupply, but are in two different resource hierarchies.

4.17.3.3 Severity

The severity of the condition.

4.17.3.4 State

The state of the resource.

5 Resource collections

A resource collection is a core concept in Redfish. A resource 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 collection contains 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 will have the same resource type with the same major version, but can vary in minor or errata schema versions.

The properties of a resource collection are:

5.0.1 Properties

As shown in the following example, a Redfish service may provide management functionality for several ComputerSystem resources, and therefore a ComputerSystemCollection resource is provided. This example shows a service with four ComputerSystem instances inside the Members array.

{
    "@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.id": "/redfish/v1/Systems"
}

5.1 Collection capabilities annotation (#CollectionCapabilities)

This annotation is used to inform the client how to form the request body for a create (POST) operation to a given collection based on a specified use case, which will result in a new member being added to the given collection.

5.1.1 Properties

5.1.2 Property details

5.1.2.1 UseCase

The use case in which a client can issue a POST request to the collection.

5.1.3 Example collection capabilities annotation

{
    "@Redfish.CollectionCapabilities": {
        "@odata.type": "#CollectionCapabilities.v1_1_0.CollectionCapabilities",
        "Capabilities": [
            {
                "CapabilitiesObject": {
                    "@odata.id": "/redfish/v1/Systems/Capabilities"
                },
                "UseCase": "ComputerSystemComposition",
                "Links": {
                    "TargetCollection": {
                        "@odata.id": "/redfish/v1/Systems"
                    }
                }
            },
            {
                "CapabilitiesObject": {
                    "@odata.id": "/redfish/v1/Systems/ConstrainedCompositionCapabilities"
                },
                "UseCase": "ComputerSystemConstrainedComposition",
                "Links": {
                    "TargetCollection": {
                        "@odata.id": "/redfish/v1/Systems"
                    }
                }
            }
        ]
    },
    ...
}

5.2 Resource collection URIs in Redfish v1.6 and later

The following table lists all Redfish-defined resource collections and the URIs where they can appear.

Note: The URIs listed are valid for Redfish services that conform to the Redfish Specification v1.6.0 or higher. Services built on earlier specification versions might use different URIs, which must be discovered by following the hyperlinks from the service root (/redfish/v1/).

6 Reference Guide

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

6.1 AccelerationFunction 1.0.5

6.1.1 Description

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.

6.1.2 URIs

/​redfish/​v1/​Systems/​{ComputerSystemId}/​Processors/​{ProcessorId}/​AccelerationFunctions/​{AccelerationFunctionId}
* Note: Some URIs omitted for brevity, refer to schema for the complete list.

6.1.3 Properties

6.1.4 Property details

6.1.4.1 AccelerationFunctionType

The acceleration function type.

6.1.5 Example response

{
    "@odata.type": "#AccelerationFunction.v1_0_5.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": []
    },
    "@odata.id": "/redfish/v1/Systems/1/Processors/FPGA1/AccelerationFunctions/Compression"
}

6.2 AccountService 1.15.1

6.2.1 Description

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. Properties and actions in this service specify general behavior that should be followed for typical accounts, however implementations might override these behaviors for special accounts or situations to avoid denial of service or other deadlock situations.

6.2.2 URIs

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

6.2.3 Properties

6.2.4 Property details

6.2.4.1 AccountProviderType

The type of external account provider to which this service connects.

6.2.4.2 Authentication

The information required to authenticate to the external service.

6.2.4.3 AuthenticationType

The type of authentication used to connect to the external account provider.

6.2.4.4 BypassTypes

The types of multi-factor authentication this account or role mapping is allowed to bypass.

6.2.4.5 CertificateMappingAttribute

The client certificate attribute to map to a user.

6.2.4.6 ExternalAccountProvider

The external account provider services that can provide accounts for this manager to use for authentication.

6.2.4.7 HTTPBasicAuth

Indicates if HTTP Basic authentication is enabled for this service.

6.2.4.8 LDAPService

The settings required to parse a generic LDAP service.

6.2.4.9 LocalAccountAuth

An indication of how the service uses the accounts collection within this account service as part of authentication. The enumerated values describe the details for each mode.

6.2.4.10 Mode

The mode of operation for token validation.

6.2.4.11 OAuth2Service

Various settings to parse an OAuth 2.0 service.

6.2.4.12 PasswordExchangeProtocols

Indicates the allowed TACACS+ password exchange protocols.

6.2.4.13 RestrictedPrivileges

The set of restricted Redfish privileges.

6.2.4.14 SupportedAccountTypes

The account types supported by the service.

6.2.4.15 TACACSplusService

Various settings to parse a TACACS+ service.

6.2.5 Example response

{
    "@odata.type": "#AccountService.v1_15_1.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"
    },
    "RequireChangePasswordAction": false,
    "@odata.id": "/redfish/v1/AccountService"
}