A File Format for YANG Instance Data
Extracted elements (31)
Partial data sets are explicitly allowed (principle P6), meaning mandatory, min-elements, require-instance, must, and when constraints MAY be violated. This enables offline documentation of incomplete configurations such as default access control rules without requiring a full valid YANG tree.
The URI method for content-schema specification avoids repeating schema information in every file, which is advantageous when a system generates instance data files frequently (e.g., every minute for diagnostics in UC5) and the schema is stable across all files.
The YANG module uses the 'sx:structure' extension (RFC 8791) rather than a container or list, because instance data sets are not managed objects on a running server but standalone documents; the security considerations template for YANG models (RFC 8407 Section 3.7.1) is therefore deliberately not followed.
Two standard formats (XML and JSON) were defined to reuse existing YANG encoding rules (RFC 7950 and RFC 7951) rather than inventing a new encoding, satisfying principles P1 and P2. Future encodings (e.g., CBOR) may be added as they are standardized.
An instance data set defined using a specific content-schema may not be directly usable with a server supporting a different YANG module set; compatibility depends on differences in modules, revisions, features, deviations, and the scope of the instance data.
Use of the simplified-inline method implies that listed modules are used without any deviations and with all features supported. YANG modules required only for import-only dependencies MAY be excluded, in which case the consumer must apply YANG language rules to resolve imports.
A YANG instance data file MUST contain a single instance data set and no additional data.
Content-data SHALL follow the encoding rules defined in RFC 7950 for XML and RFC 7951 for JSON, and MUST use UTF-8 character encoding.
If the datastore leaf cannot identify a single specific datastore, the leaf MUST be absent; if absent, the datastore to which the instance data belongs is unspecified.
If the revision-date is present in both the filename and the instance data header, the revision date in the filename MUST be set to the latest revision date inside the instance data set.
In the simplified-inline method, multiple revisions of the same module MUST NOT be specified, and the list entry value SHALL start with the module name, optionally followed by a revision date.
Metadata MUST be included in the instance data set, and MUST include the version of the YANG instance data format (if not explicitly present, the default value is used).
The content-data part MUST conform to the content-schema, with exceptions allowing partial data sets where mandatory, min-elements, require-instance true, must, and when constraints MAY be violated.
The 'same-schema-as-file' leaf SHALL contain a URI referencing another YANG instance data file; referenced files using inline or simplified-inline methods MUST be supported, and URL schemes file:// and https:// MUST be supported.
Unknown metadata in content-data MUST be ignored by users of instance data, allowing it to be used later for other purposes.
When specifying the content-schema within the instance data set, one of three methods MUST be used: inline, simplified-inline, or URI method.
The content-schema container provides a choice of three methods for specifying the YANG modules defining the instance data: simplified-inline (leaf-list of module names with optional revision dates), inline (anydata carrying ietf-yang-library conformant data), or uri (same-schema-as-file leaf referencing another instance data file).
The datastore leaf (type ds:datastore-ref) optionally identifies the NMDA datastore associated with the instance data set, e.g., the datastore from which data was read or into which data may be loaded.
The format-version leaf holds the revision date of the ietf-yang-instance-data module used to encode the instance-data-set, with a default value of '2022-01-20'. Its pattern enforces YYYY-MM-DD format.
The includes-defaults leaf (type ncwd:with-defaults-mode, default 'report-all') indicates how data nodes with default values are represented; for JSON files, the 'report-all-tagged' encoding follows RFC 8040 Section 4.8.9.
The instance-data-set structure (defined via sx:structure extension) comprises a header part with metadata and a content-data anydata node carrying the actual instance data. Key header nodes include name, format-version, includes-defaults, content-schema, description, contact, organization, datastore, revision list, and timestamp.
The module-with-revision-date typedef defines a string type matching a YANG module name (pattern [a-zA-Z_][a-zA-Z0-9\-_.]*) with an optional @YYYY-MM-DD revision date suffix, used for simplified-inline content-schema specification.
The revision list (keyed by date) tracks editorial changes to the instance data set. Specification or design-effort instance data sets SHOULD have at least one entry; instance data produced by a server or subject to frequent updates SHOULD NOT use revision entries.
The timestamp leaf (type yang:date-and-time) records when the instance data set was last modified, and SHOULD be present for server-produced or frequently updated instance data. If both revision and timestamp are present, they SHOULD agree on the latest date.
RFC 9195 registers one URI in the IETF XML Registry (RFC 3688): URI 'urn:ietf:params:xml:ns:yang:ietf-yang-instance-data', designating an XML namespace with no associated XML schema.
RFC 9195 registers the YANG module 'ietf-yang-instance-data' in the 'YANG Module Names' registry (RFC 6020), with namespace 'urn:ietf:params:xml:ns:yang:ietf-yang-instance-data' and prefix 'yid'.
The content-data part may contain sensitive data whose security sensitivity depends entirely on the content-schema. Instance data files MAY need to be handled securely; the same protections applied to a live read operation returning equivalent data should apply to the file at rest and in transit.
The header part is usually not security sensitive, but may become sensitive if the URI method is used and the URI includes a userinfo subcomponent, or if description text contains sensitive information. Instance data files should be protected against modification or unauthorized access using normal file-handling mechanisms.
When the URI method is used for content-schema specification, the referenced YANG instance data file may be altered maliciously or changed as part of normal handling, causing the actual content-schema to differ from what is expected. Integrity and stability of the referenced file must be ensured.
The filename SHOULD follow the ABNF form: instance-data-set-name ["@" (revision-date / timestamp)] (".xml" / ".json"), with colons in timestamps replaced by underscores for filesystem compatibility.
Two wire formats are specified: XML (per RFC 7950 encoding rules) and JSON (per RFC 7951). The file is structured as a YANG 'sx:structure' named instance-data-set, with file extension .xml or .json respectively. Both MUST use UTF-8 character encoding.