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

1 files changed, 85 insertions, 57 deletions

diff --git a/OEM_SCHEMAS.md b/OEM_SCHEMAS.md
index 075809736e..7d30cba457 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.
-
-## Why?
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-## How?
+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.
+
+## OEM Compatibility and authority
+
+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.
+
+Because of that, OEM properties in an open-source project pose many problems
+when compared to their closed source brethren.
+
+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.
+
+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.
+
+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.
+
+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.