Write down the dbus->redfish conversion rules
We have a lot of DBus rules that bmcweb tries to abide by because of
history and maintainability reasons. These have never been well
documented, which causes problems at review time, with maintainers
having no place to point to.
This commit attempts to write down the guidelines we aim to hit.
Signed-off-by: Ed Tanous <edtanous@google.com>
Change-Id: Icee6f4740d24a69fb2209a7e2c8586bc018ec29a
diff --git a/DBUS_USAGE.md b/DBUS_USAGE.md
new file mode 100644
index 0000000..354a79b
--- /dev/null
+++ b/DBUS_USAGE.md
@@ -0,0 +1,24 @@
+The following are guidelines for bmcweb's use of DBus to construct Redfish
+schemas:
+
+- Do not require (ie set 500 internal error on) an implementation present a
+ property that wasn't in the first commit of the interface unless it can be
+ verified that _all_ OpenBMC implementers of the interface support that
+ property.
+- If an implementation presents a property that doesn't match the type specified
+ by the interface at any version, it shall be repored as a 500 error.
+- If the DBus interface definition has an "unknown" or "unspecified" value,
+ detecting these will omit the property from the Redfish tree, in line with the
+ Redfish specification.
+- All DBus interfaces on all object paths are optional. An object missing an
+ interface is never an error, and shall simply omit the relevant properties
+ and/or actions from that Redfish Resource.
+- bmcweb will code to the DBus interface itself. This means that daemons are
+ expected to handle functionally bad, but DBus-correct input in their own
+ process, and return appropriate return codes. This is done to reduce the
+ duplication in input processing between the various user-facing daemons.
+- There are interfaces for which there is an expectation that there will only
+ ever be one producer in the project (ex bmc networking, user management). In
+ these cases, it is desirable to call the daemon by well known name directly.
+ Bmcweb APIs should call the mapper in cases where it's reasonably expected
+ that multiple implementations exist (ex, CPU management, Sensors).