Revisit OEM schemas
This documentation was written a while ago, and needs some updates in
its statements, as well as updates that have happened to the Redfish
spec in the meantime.
There's lots of wording here that implies a level of control for
maintainers, when really, it's about the ecosystem as a whole. Overall
goals in the rewording:
- Added emphasis on the Redfish specification rules, not maintainers.
- Addition of the OpenBMC namespace (now called out int he
specification) and guides to reuse.
Signed-off-by: Ed Tanous <edtanous@google.com>
Change-Id: Iffb88f8c466743fe0badb61d5d5bebfa6741b876
diff --git a/OEM_SCHEMAS.md b/OEM_SCHEMAS.md
index 0758097..7d30cba 100644
--- a/OEM_SCHEMAS.md
+++ b/OEM_SCHEMAS.md
@@ -1,73 +1,101 @@
-# Redfish OEM Resources
+# Redfish OEM Schemas
The Redfish specification allows for OEM resources and properties to be
-implemented by OEMs. As a general rule, OpenBMC discourages the use of OEM
-namespaces in APIs. In line with this, bmcweb does not expose an API for adding
-OEM properties in a backward API compatible way for resources that have not been
-merged to master.
+implemented by OEMs. bmcweb does not expose a stable API for adding OEM
+properties in a backward API compatible way for code that has not been merged to
+master.
-## Why?
+## OEM Compatibility and authority
-OEM properties in an open source project pose many problems when compared to
-their closed source brethren in terms of reliability, code reuse, compatibility,
-and maintenance.
+Generally, a single individual or group of senior individuals in a corporate
+organization is responsible for maintaining that company's OEM namespace. They
+ensure that it remains correct, doesn't duplicate functionality found elsewhere,
+and can be maintained forever. Within OpenBMC, we have no such group of
+individuals with that authority, knowledge, willpower, and scope that covers the
+entire project.
-1. As a general rule, OpenBMCs external Redfish API aims to be as compatible
- between systems as possible. Adding machine-specific resources, properties,
- and types largely defeats some of that goal, as clients must implement
- machine-specific APIs, some of which are likely to overlap, which increases
- the amount of code overall. OpenBMC also has very little visibility into
- clients that might interface with Redfish, and therefore needs to take care
- when adding new, non-standard APIs.
+Because of that, OEM properties in an open-source project pose many problems
+when compared to their closed source brethren.
-2. In practice, OEM resources trend toward a lower level of quality and testing
- than their spec-driven alternatives, given the lack of available systems to
- test on, and the limited audience of both producers and consumers. This poses
- a problem for maintenance in the long run, as it is very difficult to make a
- breaking change to an external API, given that clients are likely to be
- implemented in projects that OpenBMC isn't aware of.
+OpenBMC's external Redfish API aims to be as compatible between systems as
+possible. Adding machine-specific resources, properties, and types defeats a
+large amount of reuse, as clients must implement machine-specific APIs, some of
+which are likely to overlap, which increases the amount of code overall. OpenBMC
+also has very little visibility into clients that might interface with Redfish,
+and therefore needs to take care when adding new, non-standard APIs, given the
+lack of compatibility rules in such a case.
-3. If a given workflow eventually becomes standardized, OpenBMC OEM endpoints
- now have to break an API boundary to be able to move to the standard
- implementation. Given the amount of effort it takes to break an API, it is
- much simpler to wait for the standard to be completed before merging the OEM
- code to master.
+In the experience of the project, OEM resources trend toward a lower level of
+quality and testing than their spec-driven alternatives, given the lack of
+available systems to test on, and the limited audience of both producers and
+consumers. This poses a problem for maintenance, as it is very difficult to make
+a breaking change to an external API, given that clients are likely to be
+implemented in projects that OpenBMC isn't aware of.
-4. DMTF has many more Redfish experts than OpenBMC. While the bmcweb maintainers
- do their best to stay current on the evolving Redfish ecosystem, we have
- significantly limited scope, knowledge, and influence over the standard when
- compared to the experts within DMTF. Getting a DMTF opinion almost always
- leads to positive API design changes up front, which increases the usefulness
- of the code we write within the industry.
+If a given feature eventually becomes standardized, OpenBMC OEM endpoints now
+have to break an API boundary to move to the standard implementation. Given the
+effort it takes to break an API, it is much simpler to wait for the standard to
+be completed before merging the OEM code to master.
-## How?
+DMTF has many more Redfish experts than OpenBMC. While the bmcweb maintainers do
+their best to stay current on the evolving Redfish ecosystem, we have
+significantly limited scope, knowledge, and influence over the standard when
+compared to the experts within DMTF. Getting a DMTF opinion almost always leads
+to positive API design changes up front, which increases the usefulness of the
+code we write within the industry.
+
+In the current implementation, OEM schemas for all namespaces are shipped on all
+systems. It's undesirable to have another company's, possibly a competitor, name
+show up in the public facing API as it exports a level of support that doesn't
+exist on those systems.
+
+## How do I write an OEM schema?
If you've read the above, and still think an OEM property is warranted, please
take the following steps.
-1. Present the new feature and use case to DMTF either through the
+1. Read all the relevant documentation on OEM schema technical implementation
+ present in the Redfish specification. This includes examples of schemas that
+ can be used as a template.
+2. Present the new feature and use case to DMTF either through the
[Redfish forum](https://www.redfishforum.com), or at a DMTF meeting. If
possible, message the new feature through the normal openbmc communications
channels to ensure OpenBMC is properly represented in the meeting/forum.
-2. If DMTF is interested in the proposal, proceed using their documented process
+3. If DMTF is interested in the proposal, proceed using their documented process
for change requests, and get your schema changes standardized; While OpenBMC
does not merge new schemas that have not been ratified by DMTF, feel free to
- push them to gerrit. If the features are major enough to warrant it, feel
- free to discuss with maintainers about hosting a branch within gerrit while
- your DMTF proposal is in progress. If the DMTF feedback is documented as
- something to the effect of "this use case is unique to OpenBMC", proceed to
- write an OpenBMC design document about the new feature you intend to
- implement as OEM, under the OpenBMC (generic to all platforms) OEM namespace.
-3. If OpenBMC feedback is that this feature is specific to a single OEM or ODM,
- and is unlikely to be used across platforms, then maintainers will provide
- you the option of adding your feature under an OEM/ODM specific namespace.
+ push them to gerrit. Maintainers are tasked with doing their best to
+ accommodate active development; OEM schemas are no different. If the DMTF
+ feedback is documented as something to the effect of "this use case is unique
+ to OpenBMC", proceed to write an OpenBMC design document about the new
+ feature you intend to implement as OEM, under the OpenBMC (generic to all
+ platforms) OEM namespace.
+4. If OpenBMC feedback is that this feature is specific to a single OEM or ODM,
+ and is unlikely to be used across platforms, then engage with bmcweb
+ maintainers, and they will walk you through how to develop the feature under
+ an OEM/ODM specific namespace.
Regardless of the OEM namespace being used, implementations should plan to
implement all appropriate CSDL and OpenAPI schemas for their given OEM
-resources, should pass the redfish service validator, and should follow redfish
-API design practices. We require this same level of quality as non OEM to ensure
-that OEM is truly required by the contributor to satisfy their use case. If OEM
-were held to a lesser level of quality requirements, bwcweb would consist
-entirely of OEM code.
+resources, should pass the redfish service validator, should pass the csdl
+validator and should follow redfish API design practices. We require OEM to have
+the same level of quality as non-OEM.
bmcweb maintainers retain the final approval on OEM schemas.
+
+The OpenBMC project maintains OEM schemas within the OpenBMC namespace, which,
+from section 9.8.1 of the Redfish specification states:
+
+''' There are organizations for which DMTF has a working relationship, and have
+registered their OEM namespace directly in the specification to allow extensions
+of the ICANN domain name requirements above. The following organization OEM
+namespaces shall be considered reserved: OpenBMC '''
+
+To avoid versioning complications with clients, schemas within the OpenBMC
+namespace should not be modified without appropriate versioning information.
+Given the nature of semantic versioning, Redfish does not directly have support
+for schema branching within a namespace, therefore, if a system intends to ship
+a version of the schemas that have been modified from the version available at
+https://github.com/openbmc/bmcweb/tree/master/static/redfish/v1/schema, the
+Redfish specification _requires_ that the namespace be changed to avoid
+collisions.