Table of contents:
Addresses: CPS-287 - Getting issue details... STATUS
YANG schema mount mechanism overview
The YANG schema mount mechanism is described in RFC-8528.
In opposite to standard YANG's "use" and "augment" the schema mount mechanism allows the model modification at runtime.
While parent (extendable) module require to define the mount point(s) any already defined (legacy) module (including standard)
can be used as a mounted model.
The ietf-yang-schema-mount module defined in RFC-8528 defines structures for following entities:
- mount-point - for mount point(s) definition within parent (extendable) module
- schema-mounts - describes the model for actual assignment of mounted models to mount points
mount-point
Mount point is uniquely identified by its name (label) and the only requirements are
- allocation only within a YANG module of version 1.1+
- allocation only within a "
container" or a "list" definition
Below is example of simple mount-point definition within a YANG module
module test-mount {
yang-version 1.1;
namespace "org:onap:cps:test-mount";
prefix tmount;
revision "2020-02-02";
import ietf-yang-schema-mount {
prefix yangmnt;
}
container root-element {
yangmnt:mount-point "root-mp";
}
}
schema-mounts
While mount-point is a part of YANG definition the schema-mounts definition is delivered as data and it's expected
the server is capable to recognize this data as a model configuration update (modification).
The schema-mounts data describes which module to be attached to which mount-point (uniquely identified by
extended module name and mount point label). The reference to mount point is (expected to be) unique combination
of module name and a label assigned to mount point. The reference to mounted model could be various (described below).
Below is example of schema-mount JSON referencing model to be taken from a library:
{
"ietf-yang-schema-mount:schema-mounts": {
"mount-point": [{
"module": "test-mount",
"label": "root-mp",
"shared-schema": {}
}]
}
}
Addressing mounted modules
Mounted model can be addressed the one of the following ways:
Known library item
Using shared-schema empty body (as in example above) indicates the model will be referenced by data while
it's expected (assumed) the model definition (YANG) to be taken from a server library identified earlier.
So if the data looks like below (addresses test-mount module described above):
{
"test-mount:root-element": {
"root-mp": { // mount point
"mounted-module:mounted-container": { // mounted module reference
// data associated to mounted module
}
}
}
}
it assumes there is a module with name "mounted-module" (known by the server) having root level container
named "mounted-container".
In order to address a mounted module as belonging to shared "shared-schema" the server needs a configuration
instruction as described RFC-8525, the yang-library message to be like below
{
"ietf-yang-library:yang-library": {
"content-id": "some-id",
"module-set": [
{
"name": "module-set",
"module": [
{
"name": "mounted-module",
"revision": "2020-02-02",
"namespace": "urn:org:onap:cps:test:mounted-module"
}
// other modules
]
}
]
}
}
So the data on model dependencies will be as shown on diagram
Inline (data embedded) reference
The reference to mounted module could be embedded directly into mount point and delivered together with a data.
The mounted module reference is expected to be described as ietf-yang-library component
{
"ietf-yang-schema-mount:schema-mounts": {
"mount-point": [{
"module": "test-mount",
"label": "root-mp",
"inline": {}
}]
}
}
The data then will look like below
{
"test-mount:root-element": {
"root-mp": { // mount point
"ietf-yang-library:modules-state": { // mounted module (and dependencies) descriptor
"module-set-id": "some-id",
"module": [{
"name": "mounted-module",
"revision": "2020-02-02",
"namespace": "urn:org:onap:cps:test:mounted-module",
"conformance-type": "import"
}
// other modules
]
},
"mounted-module:mounted-container": { // actual mounted module data
// data associated to mounted module
}
}
}
}
Reference by xpath
If the parent (extendable) module already contains references to mountable modules (i.e. other module imports)
then the required module(s) can be mounted via xpath reference.
module test-mount {
yang-version 1.1;
namespace "org:onap:cps:test-mount";
prefix tmount;
revision "2020-02-02";
import ietf-yang-schema-mount {
prefix yangmnt;
}
import mounted-module {
prefix mntm;
}
container root-element {
yangmnt:mount-point "root-mp";
}
}
The schema-mount
{
"ietf-yang-schema-mount:schema-mounts": {
"namespace": [{
"prefix": "mntm",
"uri": "urn:org:onap:cps:test:mounted-module"
}],
"mount-point": [{
"module": "test-mount",
"label": "root-mp",
"shared-schema": {
"parent-reference": ["/mntm:mounted-container"]
}
}]
}
}
Other examples
The examples of schema mounts can be also found on following resources
- RFC-8528 YANG Schema Mount - Appendix A: Examples
- RFC-8530 YANG Model for Logical Network Elements - Appendix A: Examples
Schema mount support in a context of CPS
The abilities of CPS regarding YANG model and associated data parsing is heavily dependent on
features provided by ODL YangTools library.
In current implementation following yangtools components are involved:
- YANG Parser (Reactor) - builds a SchemaContext object, which holds a static model definitions
- Data Parser (JSON) - converts incoming data into structured tree object using SchemaContext instance as a dictionary
Yang Parser
YANG parser already supports the mount-point definition. Minimal changes are required on CPS side in order to support
mount-point to accept it as a valid statement:
import org.opendaylight.yangtools.rfc8528.parser.MountPointStatementSupport;
// ...
private static SchemaContext generateSchemaContext(final Map<String, String> yangResourceNameToContent) {
final CrossSourceStatementReactor.BuildAction reactor = RFC7950Reactors.vanillaReactorBuilder()
.addStatementSupport(ModelProcessingPhase.FULL_DECLARATION, MountPointStatementSupport.getInstance())
.build().newBuild();
//...
return reactor.buildEffective();
//...
}
Taken from MountPointTest @ git.opendaylight.org
Data Parser
There is no issue parsing the actual schema-mounts JSON. It just treats the JSON as data and converts it into NormalizedNode instance.
The problem is the schema-mount JSON is not a data, it's an instruction to server to modify the model it holds runtime. Unfortunately
taking into account the context (separating a treating differently the actual data from the instruction) in not fully implemented yet.
Currently the ODL Yangtools library supports schema-mount for XML parser only (not JSON one). The schema-mount instruction require to
be pre-processed into a MountPointContext object and passed to the parser as a context to be taken into account.
See XmlParserStream @ git.opendaylight.org
It means the MountPointContext is not a part of SchemaContext which holds a static information on YANG resources involved, but a
runtime context used on data parsing.
Schema mount support for JSON parser was requested via https://jira.opendaylight.org/browse/YANGTOOLS-1267
Analysis summary
- While schema-mounts is only supported by XML data parser for now it will require either awaiting (request) for similar functionality
to be implemented in JSON parser or to provide own JSON parser which supports it (significant extra effort). - CPS requires additional logic and persistence layer update in order to support YANG schema/library management requests like
data implementing ietf-yang-schema-mount and/or ietf-yang-library - CPS requires mechanism to store and retrieve on data parse the MountPointContext based on schema-mounts updates.