Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content
updated by
- rfc-7952 — Defining and Using Metadata with YANG
Extracted elements (25)
The mapping is split into two steps: first, YANG modules are translated to a single intermediate 'hybrid schema' (a RELAX NG schema with foreign-namespace annotations) that cannot be used for validation directly; second, the hybrid schema is transformed on demand into a coordinated set of DSDL schemas tailored to a specific document type and context. This avoids maintaining a parallel set of long-lived schemas alongside the YANG source modules.
The mapping preserves the granularity of the source YANG module rather than flattening it to a RELAX NG flat style. YANG 'augment' and 'refine' can address arbitrary schema depths via path expressions, so the fine granularity needed for RELAX NG extensibility is unnecessary; generating ad hoc schemas also makes flattening unnecessary since the schemas are not expected to be externally extended.
The mapping uses RELAX NG XML syntax exclusively rather than the compact syntax. Although compact syntax is preferred for human readability in publications, it is significantly harder to generate programmatically (no library support) and makes foreign-namespace annotations far less readable due to requiring four distinct syntactic constructs instead of a uniform XML element/attribute form.
YANG 'refine' and 'augment' substatements of 'uses' are handled by fully expanding the referenced grouping in place and applying the modifications, rather than mapping them to RELAX NG override mechanisms. This is because RELAX NG modifications only apply at the topmost level of a named pattern, whereas YANG can refine nodes at arbitrary depths.
RELAX NG intentionally avoids infoset augmentation such as defining default values, delegating that task to DSRL. This architectural constraint of the DSDL framework is the reason the mapping requires three coordinated schema outputs (RELAX NG, Schematron, DSRL) rather than a single unified schema.
YANG and RELAX NG have fundamentally different modularity models: YANG 'import' gives access only to definitions (groupings/typedefs) without importing the data tree, whereas RELAX NG <rng:include> imports both named pattern definitions and the entire schema tree. Also, RELAX NG named patterns share a single flat namespace within a grammar, requiring name mangling to map YANG's lexically scoped symbols.
All implicit containers and leaf nodes that inherit their default value from a typedef (without a direct @nma:default attribute) MUST be marked in the hybrid schema with the attribute @nma:implicit='true'. A leaf is implicit if and only if it has a default value; a container is implicit if and only if it lacks the 'presence' substatement, none of its children are mandatory, and at least one child is implicit.
All XPath expressions in YANG 'must', 'when', and 'path' statements MUST be translated to fully conformant XPath 1.0: every unprefixed node name MUST be prepended with the local module's namespace prefix. Inside top-level groupings, the local prefix MUST instead be represented as the variable '$pref' so that the Schematron schema can substitute the correct module namespace at validation time.
An implementation of the mapping algorithm MUST accept one or more valid YANG modules as its input, since multiple modules may be negotiated for a NETCONF session and the resulting datastore content is the union of data trees across modules, which may produce multiple root nodes.
Dublin Core metadata annotations and RELAX NG DTD compatibility annotations SHOULD be included in the hybrid schema and MAY also appear in the final validation schemas, since they carry important documentation information for data model implementers even though they are not used for formal validation.
Global named pattern definitions (mapped from top-level YANG groupings) MUST be placed as children of the outer <rng:grammar> element, and the RELAX NG schema file containing them MUST NOT define any namespace via the @ns attribute. Non-global named pattern definitions MUST be placed as children of the corresponding embedded <rng:grammar> element.
If a YANG grouping is used both in RPC input/output parameters and elsewhere, it MUST be mapped to two different named pattern definitions — one with fixed element order (for RPC) and one with arbitrary order (for other contexts). The fixed-order version MUST have the suffix '__rpc' appended to its mangled name.
If at least one 'anyxml' statement occurs in any input YANG module, a single global RELAX NG named pattern '__anyxml__' MUST be added exactly once as a child of the root <rng:grammar> element; it accepts any combination of attributes, child elements (recursively), and text.
In both the hybrid schema and validation RELAX NG schemas, the root <rng:grammar> MUST have @xmlns:xxx attributes declaring prefixes of all namespaces used in the data model (prefixes SHOULD match those in the YANG 'prefix' statements), and each embedded <rng:grammar> MUST declare its module's namespace using the @ns attribute.
The mapping MUST use specified rules to determine whether each YANG node is optional, and if so wrap it in <rng:optional>. However, alternatives inside <rng:choice> MUST NOT be defined as optional individually; if a choice is not mandatory, the entire <rng:choice> pattern MUST be wrapped in <rng:optional>.
When a top-level 'augment' statement augments a YANG module that is not processed within the same mapping session, the 'augment' statement MUST be ignored. If the augmented module is co-processed, the augment contents are added to the foreign module's schema fragment with the augmenting module's namespace.
When a YANG derived type is used with additional restrictions, its definition MUST be expanded in place so that only the ancestor built-in type appears in the hybrid schema, combined with all restrictions from the full type derivation chain. If the expanded type (or an ancestor) contains a 'default' statement, the @nma:default attribute arising from the expansion MUST be attached to the pattern where the expansion occurs.
Within the <nma:rpcs> subtree, subelement definitions in the hybrid schema MUST follow the order specified in the source YANG module. For 'list' statements, all keys MUST come before other subelements and in the key declaration order; remaining subelements MUST be enclosed in <rng:interleave>. Otherwise, all subelement definitions MUST be enclosed in <rng:interleave>.
YANG grouping and typedef names MUST be disambiguated when mapped to RELAX NG named patterns: top-level names are prefixed with the module name and '__'; nested names are further prefixed with ancestor data node names separated by '__'; grouping names are additionally prefixed with a leading underscore '_' to distinguish them from type definitions in the shared RELAX NG pattern namespace.
NETMOD-specific annotations are XML elements and attributes qualified with namespace URI 'urn:ietf:params:xml:ns:netmod:dsdl-annotations:1'. They include attributes such as @nma:config, @nma:default, @nma:if-feature, @nma:implicit, @nma:key, @nma:leaf-list, @nma:leafref, @nma:mandatory, @nma:min-elements, @nma:max-elements, @nma:ordered-by, @nma:status, @nma:unique, @nma:units, @nma:when, and elements such as <nma:must>, <nma:error-app-tag>, <nma:error-message>, and <nma:instance-identifier>.
The document defines namespace URI mappings for all annotation vocabularies used in the hybrid schema: 'a' (RELAX NG DTD compatibility), 'dc' (Dublin Core), 'dsrl' (DSRL), 'en' (NETCONF notifications), 'nc' (NETCONF base), 'nma' (NETMOD annotations), 'nmf' (NETMOD XPath extensions), 'rng' (RELAX NG), 'sch' (ISO Schematron), and 'xsd' (W3C XML Schema).
The hybrid schema uses special marker elements in the NETMOD annotation namespace ('urn:ietf:params:xml:ns:netmod:dsdl-annotations:1') to demarcate sub-schemas: <nma:data> for configuration/state data, <nma:rpcs> and <nma:rpc> for RPC operations, <nma:input> and <nma:output> for RPC request/reply, and <nma:notifications>/<nma:notification> for event notifications.
The document registers the XML namespace 'urn:ietf:params:xml:ns:netmod:dsdl-annotations:1' for NETMOD-specific schema annotations and 'urn:ietf:params:xml:ns:netmod:xpath-extensions:1' for NETMOD-specific XPath extension functions, per the IANA Considerations in Section 13.
The document includes a Security Considerations section (Section 14). The mapping process itself transforms YANG data models into validation schemas; the security properties of the resulting NETCONF content validation depend on the correctness of the mapping implementation and the completeness of the generated DSDL schemas in capturing all YANG constraints.
NETCONF content validation proceeds in three ordered steps: (1) the XML instance document is checked against the RELAX NG schema for grammatical and data type validity; (2) default values for leaf nodes are inserted and their ancestor containers added by the DSRL schema — this step modifies the information set and must precede XPath evaluation; (3) semantic constraints are checked using the Schematron schema against the augmented document.