You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2018/12/31 16:35:57 UTC
[isis] 03/08: ISIS-2003: adds documentation for mml schema.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch release-1.17.0-RC1
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 261e2258d7431e42609a9ccc04816e755c4e61ec
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Dec 31 16:11:51 2018 +0000
ISIS-2003: adds documentation for mml schema.
---
.../asciidoc/guides/rgcms/_rgcms_schema-chg.adoc | 35 +-
.../asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc | 9 +-
.../guides/rgcms/_rgcms_schema-common.adoc | 7 +-
.../asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc | 6 +-
.../asciidoc/guides/rgcms/_rgcms_schema-mml.adoc | 362 +++++++++++++++++++++
.../main/asciidoc/guides/rgcms/_rgcms_schema.adoc | 3 +
6 files changed, 390 insertions(+), 32 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
index 7b6b3b7..14638b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
@@ -6,12 +6,10 @@
-The changes ("chg") schema defines the serialized form identifying which objects have been created,
-updated or deleted as the result of invoking an action or editing a property. It also captures a number of other
-metrics counts (number of objects loaded, number of object properties modified), useful for profiling.
+The changes ("chg") schema defines the serialized form identifying which objects have been created, updated or deleted as the result of invoking an action or editing a property.
+It also captures a number of other metrics counts (number of objects loaded, number of object properties modified), useful for profiling.
-An instance of the DTO (corresponding to this schema) is used within the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`] SPI, identifying changed objects that are to be
+An instance of the DTO (corresponding to this schema) is used within the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`] SPI, identifying changed objects that are to be
published (as per xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] or equivalent).
@@ -49,30 +47,28 @@ The `changesDto` root element is defined as:
...
</xs:schema>
----
-<1> the changes schema has a namespace URI of "http://isis.apache.org/schema/chg". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
+<1> the changes schema has a namespace URI of "http://isis.apache.org/schema/chg".
+Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema].
-<3> definition of the `changesDto` root element. The corresponding XML will use this as its top-level element.
+<3> definition of the `changesDto` root element.
+The corresponding XML will use this as its top-level element.
<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
-<5> unique identifier for the transaction in which this interaction is being executed. The transaction Id is used to
-correlate back to the xref:../rgcms/rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
-execution, as well as to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes said command.
-<6> uniquely identifies this set of changes within the interaction. Can be combined with `transactionId` to create a
-unique identifier (across all other changed object events and also any interaction executions) of this particular set
-of changed objects.
+<5> unique identifier for the transaction in which this interaction is being executed.
+The transaction Id is used to correlate back to the xref:../rgcms/rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this execution, as well as to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes said command.
+<6> uniquely identifies this set of changes within the interaction.
+Can be combined with `transactionId` to create a unique identifier (across all other changed object events and also any interaction executions) of this particular set of changed objects.
<7> the date/time that the transaction that dirtied this objects completed
<8> the user that executed the (top-level) action invocation/property edit.
<9> identifies the objects that have changed.
-The `ChangesDto` DTO corresponding to the `changesDto` root element can be marshalled to/from XML using the
-`ChangesDtoUtils` class.
+The `ChangesDto` DTO corresponding to the `changesDto` root element can be marshalled to/from XML using the `ChangesDtoUtils` class.
== `objectsDto`
-The `objectsDto` complex type actually identifies the objects created, updated or deleted. It also captures additional
-metrics counters:
+The `objectsDto` complex type actually identifies the objects created, updated or deleted.
+It also captures additional metrics counters:
[source,xml]
----
@@ -93,5 +89,4 @@ metrics counters:
<2> the identities of the objects that were, respectively, created, updated or deleted within the transaction.
<3> the number of objects' properties changed, in total, by the interaction.
-The xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn[interaction] schema also provides metrics on the number of objects loaded/changed,
-but is more granular, each figure relating to a single (sub-)execution within an interaction.
+The xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn[interaction] schema also provides metrics on the number of objects loaded/changed, but is more granular, each figure relating to a single (sub-)execution within an interaction.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
index a0597b3..259290b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
@@ -5,8 +5,7 @@
:_imagesdir: images/
-The command ("cmd") schema defines the serialized form of the __intention__ to invoke an action or to
-edit a property.
+The command ("cmd") schema defines the serialized form of the __intention__ to invoke an action or to edit a property.
It can be supplemented with optional timings capturing the actual invocation of a command (introduced to support the replication of commands in a master/slave arrangement).
@@ -63,14 +62,14 @@ The `commandDto` root element is defined as:
...
</xs:schema>
----
-<1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd".
+Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema].
<3> definition of the `commandDto` root element.
The corresponding XML will use this as its top-level element.
<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
<5> unique identifier for the transaction in which this command is created.
-The transaction Id is used to correlate to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
-xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
+The transaction Id is used to correlate to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
<6> the name of the user who created the command (whose intention it is to invoke the action/edit the property).
<7> the target object (or objects) to be invoked.
A bulk action will create multiple commands, each with only a single target.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
index b5c8175..ffcc753 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
@@ -57,7 +57,8 @@ The `objectState` attribute can usually be omitted (indicating a persistent obje
xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table` attributes), or to the (JDO) xref:../rgant/rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation.
If none is specified, then the fully qualified class name will be used.
<4> the object identifier (aka primary key), converted to string form.
-<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object. In previous versions of the schema the attribute was defaulted to "persistent"; the "persistent" state is assumed if the attribute is omitted.
+<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object.
+In previous versions of the schema the attribute was defaulted to "persistent"; the "persistent" state is assumed if the attribute is omitted.
<6> Models a list of OIDs.
This is used by the xref:../rgcms/rgcms.adoc#_rgcms_schema_cmd["cmd" schema] to represent the
intention to perform a bulk actions (against a number of selected objects).
@@ -68,11 +69,11 @@ The element form can still be used, but is deprecated.
The `oidDto` complex type is used in a number of places by the framework:
* first, as a means of serializing JAXB view model/DTOs (annotated with
-xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities.
+
These references are serialized instead into OIDs
-* second, as references to the target of a command representing the _intention_ to invoke an action or edit a property, as described by the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" (command)] schema. +
+* second, as references to the target of a command representing the _intention_ to invoke an action or edit a property, as described by the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" (command)] schema.
+
They are also used to represent references to any action arguments/properties that take domain object entities/view models.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
index 6071d01..e9d22f2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
@@ -6,10 +6,8 @@
-The interaction ("ixn") schema defines the serialized form of an action invocation or a property
-edit.
-In fact, it actually defines a call-graph of such executions for those cases where the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
+The interaction ("ixn") schema defines the serialized form of an action invocation or a property edit.
+In fact, it actually defines a call-graph of such executions for those cases where the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
Each execution identifies the target object, the member to invoke, and the arguments.
It also captures metrics about the execution, and the result of the execution (eg return value of an action invocation).
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-mml.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-mml.adoc
new file mode 100644
index 0000000..c51a49d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-mml.adoc
@@ -0,0 +1,362 @@
+[[_rgcms_schema-mml]]
+= MetaModel
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The metamodel ("mml") schema defines the serialized form of the metamodel, used by the framework to render and interact with the application's domain objects.
+
+The top-level metamodel consists of a set of domain classes, which in turn contain members (actions, properties and collections).
+Actions also have action parameters.
+All of the elements of the metamodel (domain classes, domain class members and action parameters) can have multiple facets associated with them.
+Some facets relate to presentational aspects (for example the name), others to the domain layer (for example the presence of a `validateXxx()` method to enforce business rules).
+
+
+[[__rgcms_schema-mml_metamodelDto]]
+== `metamodelDto`
+
+The `metamodelDto` root element is defined as:
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/metamodel" <!--1-->
+ elementFormDefault="qualified"
+ xmlns="http://isis.apache.org/schema/metamodel"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ <xs:element name="metamodelDto"> <!--2-->
+ <xs:complexType>
+ <xs:sequence minOccurs="1" maxOccurs="unbounded"> <!--3-->
+ <xs:element ref="domainClassDto"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ ...
+</xs:schema>
+----
+<1> the metamodel schema has a namespace URI of "http://isis.apache.org/schema/mml".
+Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<2> definition of the `metamodelDto` root element.
+The corresponding XML will use this as its top-level element.
+<6> consists of a list of `domainClassDto`, defined below.
+
+
+
+[[__rgcms_schema-mml_domainClassDto]]
+== `domainClassDto`
+
+The `domainClassDto` element describes the behaviour and structure of a single domain class within the metamodel.
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:element name="domainClassDto"> <!--1-->
+ <xs:complexType>
+ <xs:complexContent>
+ <xs:extension base="facetHolder"> <!--2-->
+ <xs:sequence>
+ <xs:element name="majorVersion" type="xs:string" <!--3-->
+ minOccurs="0" maxOccurs="1" default="1"/>
+ <xs:element name="minorVersion" type="xs:string"
+ minOccurs="0" maxOccurs="1" default="0"/>
+ <xs:element name="properties" minOccurs="0"> <!--4-->
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="prop" type="property"
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ <xs:element name="collections" minOccurs="0"> <!--5-->
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="coll" type="collection"
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ <xs:element name="actions" minOccurs="0"> <!--6-->
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="act" type="action"
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:ID"/> <!--7-->
+ <xs:attribute name="service" type="xs:boolean"/> <!--8-->
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+ </xs:element>
+ ...
+</xs:schema>
+----
+<1> `domainClassDto` is defined as an element so that if necessary each domain class can be serialized to XML independently (rather than only within an outer `metamodelDto`.
+
+<2> extends from `facetHolder` type, defined below.
++
+This allows a map of facets to be associated with the domain class.
+
+<3> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
+
+<4> the collection of properties (if any) of this domain class.
++
+This will include any mixin properties.
+<5> the collection of collections (if any) of this domain class.
++
+This will include any mixin collections.
+<6> the collection of actions (if any) of this domain class.
++
+This will include any mixin actions.
+
+<7> The fully qualified class name of the underlying Java class.
++
+This is declared as 'xs:ID' so can be referenced elsewhere (using 'xs:IDREF').
+
+<8> Whether this is domain type is a domain service
+
+
+[[__rgcms_schema-mml_member]]
+== `member`
+
+The `member` (abstract) complex type is the supertype for properties, collections and actions.
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="member">
+ <xs:complexContent>
+ <xs:extension base="facetHolder"> <!--1-->
+ <xs:attribute name="id" type="xs:string"/> <!--2-->
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+ ...
+</xs:schema>
+----
+<1> Inherits from `facetHolder`, allowing a set of facets to be associated with the member.
+<2> The id of the member, which should be unique within the domain class.
++
+[NOTE]
+====
+This assumes no overloading of method names.
+====
+
+
+[[__rgcms_schema-mml_property]]
+== `property`
+
+The `property` complex type represent a scalar association returning a single value (eg `getFirstName()`).
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="property">
+ <xs:complexContent>
+ <xs:extension base="member"> <!--1-->
+ <xs:sequence>
+ <xs:element name="type" type="xs:IDREF"/> <!--2-->
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+ ...
+</xs:schema>
+----
+<1> Extends from `member` complex type, defined above.
+Every property therefore has an id (unique within the domain class), and a set of facets.
+<2> A (reference to ) the type of this property, eg a String or a Customer.
++
+This will be the value of the `id` of some other `domainClassDto`.
+
+
+[[__rgcms_schema-mml_collection]]
+== `collection`
+
+Like `property` (above), the `collection` complex types represent an association, but this time one that is a vector, in other words returning multiple instances (eg `getOrders()`).
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="collection">
+ <xs:complexContent>
+ <xs:extension base="member"> <!--1-->
+ <xs:sequence>
+ <xs:element name="type" type="xs:IDREF"/> <!--2-->
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+ ...
+</xs:schema>
+----
+<1> Extends from `member` complex type, defined above.
+Every collection therefore has an id (unique within the domain class), and a set of facets.
+<2> A (reference to ) the _element_ type of this collection, eg a Customer.
++
+This will be the value of the `id` of some other `domainClassDto`.
+
+
+[[__rgcms_schema-mml_action]]
+== `action`
+
+The `action` complex type represents a behaviour of the domain object.
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="action">
+ <xs:complexContent>
+ <xs:extension base="member"> <!--1-->
+ <xs:sequence>
+ <xs:element name="returnType" type="xs:IDREF"/> <!--2-->
+ <xs:element name="params">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="param" type="param" <!--3-->
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+
+ ...
+</xs:schema>
+----
+<1> Extends from `member` complex type, defined above.
+Every action therefore has an id (unique within the domain class), and a set of facets.
+<2> (A reference to) the return type of this action, eg a String or a Customer.
+<3> Each action has a collection of parameters (possibly none).
+
+
+[[__rgcms_schema-mml_action-parameters]]
+== Action parameters
+
+The `param` (abstract) complex type represents a parameter of an `action`.
+The concrete implementations are either `scalarParam` or `vectorParam`.
+
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="param"> <!--1-->
+ <xs:complexContent>
+ <xs:extension base="facetHolder"> <!--2-->
+ <xs:sequence>
+ <xs:element name="type" type="xs:IDREF"/> <!--3-->
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:string"/> <!--4-->
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="scalarParam"> <!--5-->
+ <xs:complexContent>
+ <xs:extension base="param">
+ <xs:sequence>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="vectorParam"> <!--6-->
+ <xs:complexContent>
+ <xs:extension base="param">
+ <xs:sequence>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+ ...
+</xs:schema>
+----
+<1> defines the `param` (abstract) complex type
+<2> inherits from `facetHolder`, allowing a set of facets to be associated with the action parameter.
+<3> A (reference to) the type of this action parameter, eg a String or a Customer.
++
+For vector parameters, this is the _element_ type of the collection parameter.
+<4> The id of the parameter, which should be unique within the action.
+<5> defines the `scalarParam` (concrete) complex type
+<6> defines the `vectorParam` (concrete) complex type
+
+
+[[__rgcms_schema-mml_action-facetholder-and-facet]]
+== `facetHolder` and `facet`
+
+The `facetHolder` (abstract) complex type defines a collection of ``facet``s, where a `facet` is in effect just a type and an implementation.
+In most cases the type has a particular purpose, for example representing the means to obtain the icon of a domain class, or the name of a parameter.
+
+Each `facet` can also have bag of associated attributes (each attribute is just a tuple of key/value pairs).
+The meaning of the attributes depends on the facet implementation.
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/mml" ... >
+ ...
+ <xs:complexType name="facetHolder"> <!--1-->
+ <xs:sequence>
+ <xs:element name="facets" minOccurs="0"> <!--2-->
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="facet" type="facet"
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:complexType name="facet"> <!--3-->
+ <xs:sequence>
+ <xs:element name="attr" type="facetAttr" <!--4-->
+ minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:string"/> <!--5-->
+ <xs:attribute name="fqcn" type="xs:string"/> <!--6-->
+ </xs:complexType>
+
+ <xs:complexType name="facetAttr"> <!--7-->
+ <xs:simpleContent>
+ <xs:extension base="xs:string">
+ <xs:attribute name="name" type="xs:string"/> <!--8-->
+ </xs:extension>
+ </xs:simpleContent>
+ </xs:complexType>
+ ...
+</xs:schema>
+----
+<1> defines the `facetHolder` (abstract) complex type
+
+<2> \... which contains a set of ``facet``s
+
+<3> defines the `facet` complex type
+
+<4> \... which contains a set of ``facetAttr``s.
++
+The meaning of the attributes depends on the implementation of the facet.
+
+<5> the identifier of the _type_ of the facet, well-known by the framework as representing a certain semantic (eg icon name or name of an action parameter)
+
+<6> the fully qualified class name of the implementation of the facet
+
+<7> defines the `facetAttr` complex type
+
+<8> the name of the attribute, unique across all facet attributes of a facet.
++
+Note this complexType extends from `xs:string,` which defines the attribute's corresponding value.
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
index 359ce8f..16f9f4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
@@ -9,6 +9,8 @@ Most applications need to integrate with other apps in the enterprise. To facil
Apache Isis defines a number of standard XSD schemas:
+* the xref:../rgcms/rgcms.adoc#_rgcms_schema-mml[metamodel] schema, which allows the internal metamodel to be exported in a canonical fashion
+
* the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] schema, which captures the __intention__ of a user
to invoke an action or edit a property
@@ -28,6 +30,7 @@ corresponding applib objects (`Command`, `Interaction.Execution` and `PublishedO
The sections below discuss these schemas in more detail.
+include::_rgcms_schema-mml.adoc[leveloffset=+1]
include::_rgcms_schema-cmd.adoc[leveloffset=+1]
include::_rgcms_schema-ixn.adoc[leveloffset=+1]
include::_rgcms_schema-chg.adoc[leveloffset=+1]