schema: introduce element
Introduce a new sub schema "EMExposesElement" that enables stricter
validation of Exposes entry elements. The existing aggregate subschema
checks element properties but cannot check that specific combinations of
properties are allowed in the same element. Require that each element
have at a minimum a Type and Name property.
Add documentation that describes an overview and best practices when
adding new schema.
Change-Id: If0a11ac9acde8e574070cccd9bf8d017b6c8e3b1
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/schemas/README.schema b/schemas/README.schema
new file mode 100644
index 0000000..36e44f6
--- /dev/null
+++ b/schemas/README.schema
@@ -0,0 +1,71 @@
+Entity manager configuration file schema
+----------------------------------------
+
+Entity manager configuration files are JSON documents and can be validated with
+a JSON schema[1]. This document provides an overview of the general structure
+of an entity manager configuration file.
+
+An entity manager configuration file consists of one or more entity manager
+configurations. This provides flexibility for system designers - the
+configuration data for an entire platform or set of platforms can be expressed
+in a single file, or can be organized into several smaller files. Thus, the
+top most schema describes a single object or an array of objects.
+
+A single entity manager configuration
+----------------------------------------
+At its core entity manager simply exports objects onto DBus when a specific
+event occurs. As such, an entity manager configuration provides a syntax for
+describing the dbus interfaces to export, the object paths on which to add the
+interfaces and the event that should trigger the export. This is accomplished
+with four properties.
+
+Type
+----------------------------------------
+The type property identifies the type of the configuration. When exported,
+configuration data will be instantiated as grandchildren of
+/xyz/openbmc_project/inventory/system/<Type>. For a comprehensive list of
+supported types, consult the schema (global.json).
+
+Name
+----------------------------------------
+The name property identifies the name of the configuration. When exported,
+configuration data will be instantiated as children of
+/xyz/openbmc_project/inventory/system/<Type>/<Name>. Additionally, any DBus
+interfaces listed in openbmc-dbus.json will be added on
+/xyz/openbmc_project/inventory/system/<Type>/<Name>.
+
+Probe
+----------------------------------------
+The probe property describes the event which will cause entity manager to
+export the configuration to DBus, making it available to other applications.
+
+Exposes
+----------------------------------------
+The exposes property describes the configuration data at its most specific
+level. The exposes property is an array of heterogeneous configuration data.
+Each exposes element has its own schema which is outlined by the subschemas in
+the schemas directory. Each schema must require a type and name (not to be
+confused with the Type and Name properties of the parent JSON object) property
+since entity manager will construct the Dbus interface name and object path
+based on those properties:
+
+/xyz/openbmc_project/inventory/system/Board/RiserCard1/<Name>:
+ xyz.openbmc_project.Configuration.<Type>:
+ <remaining properties defined by exposes subschema>
+
+Adding new exposes property subschema
+----------------------------------------
+New subschema for the exposes property must be added to the schema directory,
+and then referenced from global.json at /definitions/EMExposesElement. Exposes
+element subschema must require a type and name property (the validator will
+fail otherwise) and should explicitly enumerate all properties and use
+additionalProperties so mistakes can be found
+during validation.
+
+Adding new Dbus interfaces
+----------------------------------------
+To export new interfaces on the configuration parent object e.g.:
+/xyz/openbmc_project/inventory/system/Board/RiserCard1 add additional subschema
+to openbmc-dbus.json.
+
+[1] https://json-schema.org/
diff --git a/schemas/global.json b/schemas/global.json
index 911c692..eb1af51 100644
--- a/schemas/global.json
+++ b/schemas/global.json
@@ -1,6 +1,43 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
+ "EMExposesElement": {
+ "description": [
+ "The exposes property element schema. An element of the exposes ",
+ "property is always an array where elements are of type exposes ",
+ "entry."
+ ],
+ "oneOf": [
+ {
+ "$ref": "legacy.json#/definitions/Aggregate"
+ },
+ {
+ "description": [
+ "Ensure the parent oneOf schema does not validate ",
+ "when an element does not define a type property."
+ ],
+ "not": {
+ "required": [
+ "Type"
+ ]
+ },
+ "title": "Missing Type"
+ },
+ {
+ "description": [
+ "Ensure the parent oneOf schema does not validate ",
+ "when an element does not define a name property."
+ ],
+ "not": {
+ "required": [
+ "Name"
+ ]
+ },
+ "title": "Missing Name"
+ }
+ ],
+ "title": "Exposes Property Element"
+ },
"EMConfig": {
"title": "Entity Manager Configuration",
"description": [
@@ -26,7 +63,7 @@
],
"type": "array",
"items": {
- "$ref": "legacy.json#/definitions/Aggregate"
+ "$ref": "#/definitions/EMExposesElement"
}
},
"Logging": {
diff --git a/schemas/legacy.json b/schemas/legacy.json
index f3204be..69d7a19 100644
--- a/schemas/legacy.json
+++ b/schemas/legacy.json
@@ -2,6 +2,11 @@
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Aggregate": {
+ "description": [
+ "Don't add additional properties to this schema. Consult ",
+ "README.schema for instructions on adding new Exposes element ",
+ "sub-schema."
+ ],
"additionalProperties": false,
"properties": {
"Address": {