NAIM: A Canonical Semantic Representation for AI-Assisted YANG Modeling and Validation
fengchongllly@gmail.com
Operations and Management NETMOD YANG NAIM AI network management This document defines the NAIM (Natural AI Interface Modeling) framework, a canonical semantic intermediate representation between natural language descriptions and YANG data models (RFC 7950). NAIM addresses a recognized gap in the YANG authoring and network management workflow: direct conversion from natural language to YANG is error-prone because essential modeling semantics -- including configuration versus state distinction, list key identification, constraint expressions, operational preconditions, and cross-module relationships -- are routinely absent or ambiguous in natural language input. NAIM makes these semantics explicit, structurally consistent, and machine-verifiable. This document defines: the NAIM Document format (Canonical JSON and derived Markdown View); the LLM Context View for AI prompt context distribution; the three-layer architecture (Specification, Skill, Tool); Skills A-D for conversational modeling, summarization, YANG generation, and reverse engineering; and the Validation-Reflection-Retry mechanism for AI output quality control. The NAIM Document format is designed to serve two roles: as the intermediate representation for design-time YANG authoring, and as the runtime semantic authority against which AI-generated operation intents are validated. The runtime validation usage is specified in [NAIM-OP]; this document defines the format, derived views, and design-time workflows.
Introduction The YANG data modeling language [RFC7950] is the foundation of model-driven network management and is widely deployed in NETCONF [RFC6241], RESTCONF [RFC8040], and related systems. Despite its importance, authoring high-quality YANG modules requires simultaneous fluency in network protocol behavior, data modeling methodology, and YANG syntax. This combination makes YANG authoring a specialized skill that limits the pace at which network management models can be developed and maintained. Recent progress in large language model (LLM) technology has created an opportunity to partially automate and assist the YANG authoring process. However, this opportunity cannot be fully realized through direct conversion from natural language to YANG. The gap between natural language and YANG is not primarily syntactic; it is semantic. Natural language descriptions routinely omit, conflate, or leave ambiguous precisely the distinctions that YANG modeling requires.
Problem Statement Direct conversion from natural language to YANG exhibits three recurring failure modes. Semantic ambiguity. Natural language descriptions commonly omit distinctions that are essential to correct YANG modeling. Whether a field represents configuration or operational state, whether an entity is a list keyed by an identifier or a singleton container, and whether two fields are siblings or parent and child are all questions that a natural language description frequently leaves unanswered. Without an explicit clarification step, an automated tool must guess -- and guesses in structural modeling propagate into downstream protocol behavior. Implicit constraint loss. Operational constraints, preconditions for node creation or deletion, cross-node dependencies, and side effects of configuration changes are often treated as common knowledge in human discourse and are therefore omitted from natural language descriptions. YANG models that omit these constraints are structurally valid but operationally incorrect. Structural inference errors. Hierarchy relationships, augmentation targets, leafref paths, grouping reuse, and cross-module import requirements all require precise structural reasoning. Without a structured intermediate step, automated tools generate models that syntactically resemble correct YANG but contain incorrect structural relationships that are difficult to detect without domain expertise.
Motivation for an Intermediate Representation A structured semantic intermediate representation addresses these failure modes by externalizing implicit knowledge into a machine-verifiable form before YANG generation is attempted. Rather than asking an automated system to traverse in one step from natural language to YANG, the workflow is decomposed into two controlled stages:
  1. Natural language input is converted into a structured, semantically explicit NAIM Document through a clarification and elicitation process. At this stage, missing or ambiguous information is identified and resolved.
  2. The completed NAIM Document is transformed into a YANG module by deterministic tooling. Because the input to this stage is already structurally explicit and constraint-complete, the transformation can be made reliable.
The NAIM Document format defined in this document is the artifact that bridges these two stages. It is designed to be simultaneously suitable for automated processing, human review, and version control. It is important to note that NAIM is not a JSON encoding of YANG. A NAIM Document can be transformed into YANG, but it carries semantics that YANG syntax does not represent, including operational descriptions, explanatory context, usage examples, cross-node relationship descriptions, and visibility conditions expressed in natural language. YANG is a target output of the NAIM workflow, not a semantic equivalent of NAIM.
Relationship to YANG NAIM is not a replacement for YANG. YANG [RFC7950] remains the authoritative data modeling language for network management, and the ultimate source of truth for configuration semantics, protocol operations, and data constraints. NAIM is positioned as a semantic bridge between natural language (or high-level intent) and the YANG ecosystem, designed to bring the existing YANG infrastructure into the era of AI-assisted network management. The YANG ecosystem -- including YANG validators, NETCONF/RESTCONF servers, and the large body of standardized and vendor YANG modules -- represents more than a decade of modeling investment and operational deployment. NAIM does not seek to duplicate or supplant this ecosystem. Instead, NAIM provides a structured intermediate representation that enables AI systems to interact with YANG-based infrastructure more reliably, by making the implicit modeling knowledge required for YANG authoring explicit and machine-processable. The relationship can be characterized as follows:
  • YANG is the target, NAIM is the path. Every NAIM Document is designed to be transformed into a valid YANG module (design-time) or validated against YANG-derived semantics (runtime). NAIM exists to improve the quality and reliability of this transformation, not to serve as an independent modeling language.
  • YANG-based systems remain the authoritative validators. NAIM performs structural and formal validation: schema conformance, type checking, required field presence, path format correctness, and node template completeness. However, true semantic validation -- including must and when expression evaluation, leafref target resolution, instance-level data validation, and cross-module augmentation consistency -- remains the responsibility of YANG-based systems such as YANG validators, NETCONF servers, and RESTCONF servers. A NAIM Document that passes NAIM-level validation is not guaranteed to produce a YANG module that will pass all semantic checks in a target YANG-based system.
  • NAIM enables YANG ecosystem evolution. By providing a representation that is simultaneously suitable for AI consumption and deterministic YANG generation, NAIM enables the YANG ecosystem to benefit from advances in AI-assisted design, natural language interaction, and automated modeling -- without requiring changes to the YANG language itself or to existing YANG-based infrastructure.
Dual-Purpose Design While the primary workflow described in this document is design-time YANG authoring (natural language -> NAIM Document -> YANG), the NAIM Document format is deliberately designed to serve a second role: as the runtime semantic authority against which AI-generated operation intents are validated. The operational semantics carried in NAIM Documents -- preconditions, side effects, constraints, and writable status -- enable deterministic validation of structured operation objects produced by AI systems, without requiring the AI to be trusted for execution decisions. This explains why the NAIM Document format carries fields such as operations.preconditions and operations.side-effects that go beyond what is strictly needed for YANG generation: they serve as machine-processable validation rules at runtime. This runtime usage is specified in [NAIM-OP]; the present document defines only the format and its design-time workflows. The two documents together implement a complete pipeline from natural language intent to validated network execution: NAIM Document -> YANG Runtime: Natural Language -> Operation IR -> [validated against NAIM Document] -> NETCONF/RESTCONF execution ]]>
Scope of This Document This document defines the NAIM framework. It is intended for implementors who build tools that produce, validate, transform, or consume NAIM Documents, and for protocol engineers who wish to understand the semantic representation choices made by the format. This document defines:
  • the NAIM Document format (Canonical JSON and Markdown View);
  • the LLM Context View (derived format for AI prompt context);
  • the three-layer architecture (Specification, Skill, Tool);
  • Skills A-D (Conversational Modeling, Summarization, YANG Generation, Reverse Engineering);
  • the Validation-Reflection-Retry mechanism; and
  • interoperability expectations for tools that exchange NAIM artifacts.
This document does not specify a specific AI model or LLM backend, prompt engineering strategies, confidence scoring algorithms, implementation-internal workflow logic, or runtime network operation execution.
Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Terminology NAIM: Natural AI Interface Modeling. NAIM Document: A structured artifact conforming to the canonical JSON schema defined in this document. A NAIM Document represents the semantics of one YANG module or one YANG submodule. Canonical JSON Format: The normative JSON representation of a NAIM Document. All interoperable tools MUST treat the canonical JSON format as the authoritative source of NAIM Document content. Markdown View: A human-readable rendering derived from the canonical JSON representation. The Markdown View is a presentation artifact; it is not normatively authoritative over the canonical JSON. LLM Context View: A derived, token-efficient Markdown format intended for consumption by AI systems as prompt context. Retains semantic fields while omitting structural boilerplate and execution details. See Section 7. Node Template: A structured schema pattern describing one category of semantic model node within a NAIM Document. Visibility Condition: A declaration associated with a node that specifies the conditions under which the node is present or applicable. Corresponds to YANG if-feature and when constructs. Deviation Declaration: A structured statement describing the ways in which a specific device implementation departs from a base YANG module. Skill: A named, versioned, independently customizable process specification that defines the inputs, outputs, and behavioral rules for one stage of the NAIM workflow. Skills do not implement AI models; they specify what AI participation looks like. Structured Error Report: A machine-readable error object produced by the Tool Layer when validation fails, containing error type, path, message, and expected format.
Architectural Framework NAIM is organized as a three-layer architecture that separates concerns between specification, AI-driven processes, and deterministic execution.
Three-Layer Model | Tool Layer | | Layer | | (deterministic) | | (format + rules) |<----------------| validation, | +------------------+ validates | generation, | against | conversion | +------------------+ ]]>
Specification Layer The Specification Layer defines the NAIM Document format itself:
  • Canonical JSON structure and JSON Schema;
  • Node template families;
  • Type representation rules;
  • Path conventions;
  • Markdown View and LLM Context View generation rules.
This is the static normative layer. Sections 5-14 of this document constitute the Specification Layer.
Skill Layer The Skill Layer defines the AI-driven processes that operate on NAIM Documents. Each Skill specifies:
  • what its inputs and outputs are;
  • what conditions must hold before it can proceed;
  • what behavioral rules govern AI participation.
Skills are decoupled from the Specification Layer: the format can remain stable while Skill implementations are versioned and customized independently for different user populations and deployment contexts. For example, the same NAIM Specification can support a simplified question flow for network operators and an expert-mode flow for protocol engineers. This document defines four Skills (Section 15):
  • Skill A: Conversational Modeling
  • Skill B: Natural Language Summarization
  • Skill C: YANG Generation
  • Skill D: Reverse Engineering
Tool Layer The Tool Layer performs deterministic operations on NAIM Documents. Tools are not AI systems; they are conventional software components that provide correctness guarantees that AI systems cannot. Tool Layer responsibilities:
  • JSON Schema validation of NAIM Documents;
  • Structured Error Report generation for validation failures;
  • Bidirectional conversion between Canonical JSON and Markdown View;
  • Generation of LLM Context Views from Canonical JSON;
  • Compilation of YANG modules from confirmed NAIM Documents;
  • Structural extraction from existing YANG modules (for Skill D).
Validation-Reflection-Retry Mechanism When the Tool Layer detects validation errors in AI-generated NAIM Documents, the following three-phase error correction mechanism applies.
Phase 1: Structured Error Report The Tool Layer MUST emit a Structured Error Report containing:
Field Description
error_code Machine-readable error category, e.g., MissingRequiredField, InvalidPathFormat, TypeConstraintViolation
path JSON Pointer [RFC6901] to the failing field, e.g., /nodes/2/type
message Human-readable error description, suitable for AI consumption
expected Expected format or valid value range
Example:
Phase 2: Context Injection and Silent Retry The system SHOULD automatically inject the Structured Error Report into the Skill's prompt context and retry generation. The retry process SHOULD be transparent to the user: the Skill regenerates corrected output and resubmits it for Tool Layer validation without user intervention.
Phase 3: Maximum Retry and Degradation The system MUST enforce a maximum automatic retry count (RECOMMENDED value: 3). If retries are exhausted and validation still fails:
  • The system MUST stop automatic retries;
  • The active Skill MUST convert the remaining errors into targeted natural language questions directed at the user;
  • The user MUST receive a clear indication of what specific field or constraint the system could not resolve automatically;
  • The entire error correction history SHOULD be recorded in audit logs.
NAIM Document Format
Canonical JSON as Normative Source A NAIM Document MUST be represented as a JSON object [RFC8259] that conforms to the schema expectations defined in this document. The canonical JSON representation is the normative source of NAIM Document content. All interoperable tools that exchange NAIM Documents MUST treat the canonical JSON format as authoritative. The Markdown View defined in Section 6 is a derived presentation artifact; it does not override the canonical JSON. When any discrepancy exists between the canonical JSON and a corresponding Markdown View, the canonical JSON MUST take precedence.
Top-Level Object Structure The top-level JSON object of a NAIM Document MUST contain:
  • version: A string identifying the NAIM format version. For documents conforming to this specification, the value MUST be "1.0".
  • Exactly one of module or submodule. A top-level object MUST NOT contain both.
The top-level object MAY additionally contain any of the following arrays:
  • revisions
  • features
  • typedefs
  • groupings
  • identities
  • extensions
  • nodes
A conforming NAIM Document representing usable model content SHOULD contain a nodes array with at least one node object.
The module Object When the top-level object contains module, it represents a YANG main module. The module object MUST contain:
  • name: A string. The YANG module name. It MUST conform to the identifier syntax defined in Section 6.2 of [RFC7950].
  • description: A string. A human-readable description of the module's purpose and scope.
The module object MAY contain:
  • organization: A string identifying the organization responsible for the module.
  • contact: A string providing contact information for the module.
  • reference: A string citing an external document relevant to the module.
  • deviations: An array of deviation objects as defined in Section 12.
The submodule Object When the top-level object contains submodule, it represents a YANG submodule. The submodule object MUST contain:
  • name: A string. The submodule name.
  • belongs-to: A string. The name of the YANG main module to which this submodule belongs.
The submodule object MAY contain:
  • description: A string.
A NAIM Document containing a submodule object MUST NOT also contain a module object at the top level.
Top-Level Arrays
revisions The revisions array MAY be present. Each entry in the array MUST contain:
  • revision: A string in the format YYYY-MM-DD representing the revision date.
  • description: A string describing what changed in this revision.
Each entry MAY also contain:
  • reference: A string citing an external document.
features The features array MAY be present. Each entry represents a YANG feature and MUST contain:
  • name: A string. The feature name.
  • description: A string describing the feature.
Each entry MAY also contain:
  • status: A string. If present, it MUST be one of "current", "deprecated", or "obsolete".
  • reference: A string.
typedefs The typedefs array MAY be present. Each entry defines a reusable type. See Section 9.1.
groupings The groupings array MAY be present. Each entry defines a reusable structural fragment. See Section 9.2.
identities The identities array MAY be present. Each entry defines a YANG identity. See Section 9.3.
extensions The extensions array MAY be present. Each entry defines an extension keyword. See Section 9.4. Extension use within nodes is described in Section 13.
nodes The nodes array MAY be present. Each entry is a node object conforming to one of the node template families defined in Section 8. The nodes array is the primary structural content of a NAIM Document. When present, it MUST contain only objects that conform to a recognized node template family.
Path Conventions All path fields in node objects MUST be expressed as absolute schema paths using the following conventions:
  • The path MUST begin with /.
  • Path segments representing nodes in a specific YANG module MUST be qualified with the module name as a prefix, using the colon (:) separator. For example: /ietf-interfaces:interfaces/interface.
  • The prefix used MUST be the YANG module name, not the YANG prefix shorthand. This ensures path stability across implementations that may choose different YANG prefix values.
  • For list nodes, key predicates SHOULD be omitted in schema paths but MAY be included when a specific instance is referenced in an operational context outside the scope of this data format.
Tools that generate YANG from a NAIM Document MAY derive YANG prefix shorthand and corresponding import statements from the module-name prefixes used in path fields, without requiring explicit import declarations in the NAIM Document.
Markdown View
Purpose and Normative Status The Markdown View is a human-readable rendering of a NAIM Document, intended for human review, version-controlled document exchange, and editorial discussion. The Markdown View is a derived artifact; it is not independently normative. Implementations that produce a Markdown View MUST derive it deterministically from the canonical JSON. Implementations that accept a Markdown View as input MAY use it to construct or update a canonical JSON document, subject to the constraints in Section 6.2.
Source of Truth Principle The canonical JSON representation is the sole authoritative source of NAIM Document content. When a Markdown View is used as input to reconstruct or update a canonical JSON document, implementations MUST NOT silently discard existing canonical JSON content. Specifically:
  • Fields present in the canonical JSON but absent from the Markdown View MUST be preserved in the resulting canonical JSON unless the Markdown View contains an explicit deletion signal defined by the implementation.
  • If the Markdown View and the canonical JSON express conflicting values for the same field, the implementation MUST resolve the conflict explicitly. The RECOMMENDED resolution strategy is to treat the Markdown View as expressing only the fields it explicitly represents, leaving all other canonical JSON fields unchanged.
Header Rules A Markdown View MUST begin with a document header. The header rules are:
  • For a main module document, the first line MUST be: # module: {name}
  • For a submodule document, the first line MUST be: # submodule: {name} and the second line MUST be: ## belongs-to: {parent-module-name}
  • The module or submodule description SHOULD immediately follow as: ## description: {description}
Section Blocks For each top-level array that is present in the canonical JSON, the Markdown View SHOULD include a corresponding section. Section headings SHOULD be:
  • ## Revisions
  • ## Features
  • ## Typedefs
  • ## Groupings
  • ## Identities
  • ## Extensions
Each section SHOULD present its entries in list form, with enough detail to allow a reader to understand the content without reference to the canonical JSON.
Tree Diagram The Markdown View SHOULD include a tree diagram following the section blocks and preceding the node definitions. The tree diagram is an informative visual aid only; it is not a normative representation of the schema. The tree diagram SHOULD follow the YANG tree diagram conventions described in [RFC8340], using ASCII art to represent schema hierarchy. Conventions include:
  • +--rw for read-write nodes,
  • +--ro for read-only nodes,
  • * to indicate list nodes, and
  • ? to indicate optional nodes.
Because the tree diagram is informative and not used for round-trip reconstruction, implementations MAY omit it or vary its format.
Flat Node Definitions Following the tree diagram, the Markdown View MUST include a flat definition block for each node in the nodes array. The flat definition format MUST follow these rules:
  • Each node definition MUST begin with a heading of the form: ### {local-name} ({node-type}) where {local-name} is the last path segment of the node's path field and {node-type} is the value of the node's node-type field.
  • Node fields SHOULD be rendered in the following order when present: path, description, type, writable, key, operations, visibility, related-nodes, constraints, examples.
  • Nodes MUST be presented in depth-first traversal order derived from their path field values.
Round-Trip Requirements The combination of canonical JSON and the Markdown View MUST satisfy the following round-trip property: given a canonical JSON document J, a Markdown View M derived from J, and a reconstruction process R that produces JSON from M, the result R(M) MUST be semantically equivalent to J for all fields that the Markdown View represents. Implementations MUST NOT produce Markdown Views in which the rendering of any represented field loses information relative to the canonical JSON representation of that field.
LLM Context View
Purpose The LLM Context View is a derived Markdown format optimized for consumption by AI systems as prompt context. It is designed to provide the semantic information an AI system needs to generate correct Operation IRs [NAIM-OP] or to participate in NAIM Skills, while minimizing token consumption. The LLM Context View is distinct from the Markdown View defined in Section 6: the Markdown View is designed for human review and round-trip fidelity; the LLM Context View is designed for AI consumption and token efficiency.
Mandatory Fields An LLM Context View MUST include:
  • resource/node name and node-type;
  • all field names with semantic types, required/optional status (derived from the mandatory field for leaf and leaf-list nodes, and from min-elements for leaf-list and list nodes), and constraints;
  • writable status for each field;
  • visibility conditions (if-feature, when) that affect field availability;
  • supported operations for container and list nodes, derived from the operations object defined in Section 8.3;
  • for each operation: preconditions and side effects;
  • illustrative examples where present in the canonical JSON; and
  • the Operation IR schema reference URI, when the LLM Context View is used for runtime operation intent generation.
Omitted Fields The following MUST be omitted from all LLM Context Views:
  • NETCONF XML / RESTCONF request construction details;
  • internal metadata (version, organization, ownership);
  • raw JSON Schema syntax of the Canonical JSON;
  • deviation declarations (these are server-internal concerns); and
  • extension definitions (only extension uses relevant to visible nodes are retained).
Generation Rules Implementations that produce LLM Context Views MUST derive them deterministically from the canonical JSON. Given the same canonical JSON input, all conforming implementations MUST produce semantically equivalent LLM Context Views. The LLM Context View is a derived, non-authoritative format. It MUST NOT be used as input to reconstruct canonical JSON documents. The round-trip requirement defined in Section 6.7 does not apply to LLM Context Views.
Node Template Families A node object in the nodes array MUST conform to one of the node template families defined in this section. Each node object MUST contain a node-type field whose value identifies the applicable template family.
Common Semantic Fields The following fields MAY appear in any node object regardless of its template family:
  • path (string, REQUIRED for all node templates): The absolute schema path of this node, following the conventions in Section 5.6.
  • description (string, REQUIRED for all node templates): A human-readable description of the node's purpose, semantics, and operational meaning.
  • visibility (object, OPTIONAL): Conditions under which this node is present or applicable. See Section 11.
  • related-nodes (array, OPTIONAL): References to other nodes that are semantically related to this node. Each entry SHOULD contain:
    • path: The absolute schema path of the related node.
    • relationship: A human-readable description of the relationship.
  • constraints (string or object, OPTIONAL): Operational constraints applying to this node beyond what the type system expresses. It MAY be a natural-language string or an object with xpath and description fields.
  • examples (array, OPTIONAL): Usage examples. Each entry SHOULD contain:
    • scenario: A description of the scenario.
    • operation: A value or operation illustrating the scenario.
  • status (string, OPTIONAL): The lifecycle status of this node. If present, it MUST be one of "current", "deprecated", or "obsolete". Corresponds to the YANG status statement. Defaults to "current" if absent.
  • extensions (array, OPTIONAL): Extension annotations applied to this node. Each entry MUST conform to the extension-use object structure defined in Section 13.
leaf and leaf-list A node object with node-type value "leaf" or "leaf-list" represents a YANG leaf or leaf-list node. REQUIRED fields:
  • node-type
  • path
  • description
  • type: An object describing the data type. See Section 10.
  • writable: A boolean. true indicates a configuration node; false indicates a state node.
OPTIONAL fields:
  • mandatory: A boolean. If true, this node MUST be present when its parent exists. Corresponds to the YANG mandatory statement. Defaults to false if absent. Applicable to leaf only; for leaf-list, cardinality is expressed via min-elements.
  • min-elements (applicable to leaf-list only): An integer. The minimum number of entries that MUST be present. Corresponds to the YANG min-elements statement.
  • max-elements (applicable to leaf-list only): An integer or the string "unbounded". The maximum number of entries permitted. Corresponds to the YANG max-elements statement.
  • ordered-by (applicable to leaf-list only): A string. If present, it MUST be one of "system" or "user". Corresponds to the YANG ordered-by statement. Defaults to "system" if absent.
All common semantic fields defined in Section 8.1 apply.
container and list A node object with node-type value "container" or "list" represents a YANG container or list node. REQUIRED fields:
  • node-type
  • path
  • description
  • writable: A boolean.
  • key (REQUIRED when node-type is "list" and writable is true): A string containing the space-separated list key leaf names. This reflects the YANG requirement that a key statement MUST be present if the list represents configuration [RFC7950, Section 7.8.2]. A state list (writable is false) MAY omit the key field.
OPTIONAL fields:
  • uses: A string reference to a grouping defined in the groupings array.
  • operations: An object describing operational semantics. It SHOULD contain:
    • preconditions: A string describing conditions that must hold before this node can be created or modified.
    • side-effects: A string describing the effects of creating, modifying, or deleting this node.
  • presence (applicable to container only): A string. If present, this container is a YANG presence container, and the string value is the meaning of the container's presence. Corresponds to the YANG presence statement. If absent, the container is a non-presence (structural) container.
  • min-elements (applicable to list only): An integer. The minimum number of list entries that MUST be present. Corresponds to the YANG min-elements statement.
  • max-elements (applicable to list only): An integer or the string "unbounded". The maximum number of list entries permitted. Corresponds to the YANG max-elements statement.
  • unique (applicable to list only): An array of strings. Each string is a space-separated list of descendant schema node identifiers that MUST be unique across all list entries. Corresponds to the YANG unique statement.
  • ordered-by (applicable to list only): A string. If present, it MUST be one of "system" or "user". Corresponds to the YANG ordered-by statement. Defaults to "system" if absent.
All common semantic fields defined in Section 8.1 apply. Key leaf consistency rule. When node-type is "list", each leaf node identified in the key field MUST have its writable value equal to the writable value of the enclosing list node. This reflects the YANG requirement that a key leaf's config value MUST match that of its parent list [RFC7950, Section 7.8.2]. The Tool Layer MUST reject NAIM Documents that violate this rule.
choice A node object with node-type value "choice" represents a YANG choice node containing mutually exclusive alternatives. A case is not an independent node-type value. Cases are represented inline within the cases array of the enclosing choice node object and do not appear as separate entries in the nodes array. REQUIRED fields:
  • node-type
  • path
  • description
  • cases: An array of case objects. Each case object MUST contain:
    • name: The case name.
    • nodes: An array of absolute schema paths identifying the nodes belonging to this case. Each case object SHOULD also contain:
    • description: A string.
OPTIONAL fields:
  • mandatory: A boolean. If true, exactly one case MUST be selected.
All common semantic fields defined in Section 8.1 apply.
rpc and action A node object with node-type value "rpc" or "action" represents a YANG RPC or action node. REQUIRED fields:
  • node-type
  • path
  • description
OPTIONAL fields:
  • input: A string giving the absolute schema path of the input container.
  • output: A string giving the absolute schema path of the output container.
  • preconditions: A string describing conditions required before invocation.
  • side-effects: A string describing effects of successful invocation.
  • error-conditions: A string describing conditions under which the operation fails.
All common semantic fields defined in Section 8.1 apply.
notification A node object with node-type value "notification" represents a YANG notification node. REQUIRED fields:
  • node-type
  • path
  • description
OPTIONAL fields:
  • trigger: A string describing the condition that causes this notification to be emitted.
  • data: An array of objects, each describing a data item carried by the notification. Each entry SHOULD contain:
    • name: The item name.
    • type: The item type.
    • description: A description.
  • side-effects: A string describing effects of notification emission.
All common semantic fields defined in Section 8.1 apply.
anydata and anyxml A node object with node-type value "anydata" represents a YANG 1.1 anydata node [RFC7950]. An anydata node models an unknown set of YANG-modeled data nodes whose structure is not specified at design time. A node object with node-type value "anyxml" represents a YANG anyxml node. An anyxml node models an opaque XML subtree whose content is not constrained by a YANG schema. REQUIRED fields (both types):
  • node-type
  • path
  • description
  • writable: A boolean.
OPTIONAL fields: All common semantic fields defined in Section 8.1 apply. Note: The presence of any anydata node in a NAIM Document triggers automatic upgrade to YANG 1.1 output (see Section 15.3.3). anyxml nodes do not trigger this upgrade, as anyxml is available in both YANG 1.0 and YANG 1.1.
Node Ordering In YANG, the order of schema nodes in a module definition has no semantic meaning [RFC7950]. Accordingly, this document does not define a required ordering of node objects within the nodes array. Implementations MUST NOT assign semantic meaning to the position of a node object within the array. For deterministic output, implementations SHOULD produce canonical JSON and Markdown Views using a consistent, documented traversal strategy. Depth-first traversal ordered by path value is RECOMMENDED.
Top-Level Array Entry Schemas
typedef A typedef entry in the typedefs array defines a reusable named type. Each typedef object MUST contain:
  • name: A string. The typedef name.
  • description: A string.
  • base-type: A string identifying the built-in or derived type on which this typedef is based.
Each typedef object MAY contain:
  • range: A string expressing a numeric range constraint.
  • length: A string expressing a string length constraint.
  • pattern: A string expressing a regular expression constraint.
  • units: A string identifying a unit of measurement.
  • default: A string expressing a default value.
grouping A grouping entry in the groupings array defines a reusable structural fragment. Each grouping object MUST contain:
  • name: A string. The grouping name.
  • description: A string.
  • contains: An array of absolute schema paths identifying the nodes that constitute this grouping.
identity An identity entry in the identities array defines a YANG identity. Each identity object MUST contain:
  • name: A string. The identity name.
  • description: A string.
Each identity object MAY contain:
  • base: A string identifying the base identity. It MAY use a module-prefixed form such as "module-name:identity-name".
  • status: A string. If present, it MUST be one of "current", "deprecated", or "obsolete".
  • reference: A string.
extension Definition An extension entry in the extensions array defines an extension keyword. Each extension object MUST contain:
  • name: A string. The extension keyword name.
  • description: A string.
Each extension object MAY contain:
  • argument: A string identifying the argument name if the extension takes an argument.
  • reference: A string citing the specification that defines the extension.
Type Representation All leaf and leaf-list nodes MUST carry a type field. The type field MUST be a JSON object containing at minimum a base field that identifies the type.
Simple Types and Constraints For YANG built-in scalar types (string, boolean, uint8, uint16, uint32, uint64, int8, int16, int32, int64, decimal64, empty), the type object MUST contain:
  • base: A string identifying the built-in type name.
The type object MAY contain the following constraint fields, expressed as strings using the same syntax as the corresponding YANG statement:
  • range: Applicable to numeric types. Example: "1..65535".
  • length: Applicable to string. Example: "1..64".
  • pattern: Applicable to string. A regular expression. Multiple patterns MAY be expressed as an array of strings.
  • default: A string expressing the default value.
  • units: A string identifying the unit of measurement.
Constraint fields SHOULD only be included when they are semantically applicable to the declared base type. In particular, range, length, and pattern have no meaning for boolean and empty types and MUST NOT be included for those types.
Enumeration For enumeration types, the type object MUST contain:
  • base: The string "enumeration".
  • enum: An array of enumeration entries.
Each entry in the enum array MAY be either:
  • A string (short form), in which case the implementation MAY assign integer values sequentially starting from zero, or
  • An object containing name (string, REQUIRED) and value (integer, OPTIONAL).
Implementations that require stable enumeration value mappings SHOULD use the object form with explicit value fields.
Bits For bits types, the type object MUST contain:
  • base: The string "bits".
  • bits: An array of bit entries.
Each entry in the bits array SHOULD contain:
  • name: A string. The bit name.
  • position: An integer. The bit position. If absent, the implementation MAY assign positions sequentially starting from zero.
Union For union types, the type object MUST contain:
  • base: The string "union".
  • types: An array of type objects, each conforming to this section.
Leafref For leafref types, the type object MUST contain:
  • base: The string "leafref".
  • path: A string giving the absolute schema path of the referenced leaf, following the path conventions in Section 5.6.
The type object MAY contain:
  • require-instance: A boolean. Corresponds to the YANG require-instance statement. Defaults to true if absent.
Identityref For identityref types, the type object MUST contain:
  • base: The string "identityref".
  • identity: A string identifying the base identity. It MAY use a module-prefixed form.
Typedef Reference When a node's type is a previously defined typedef rather than a built-in type, the type object MUST contain:
  • base: A string giving the typedef name.
The implementation is responsible for resolving the typedef name against the typedefs array of the same NAIM Document or against known external type definitions. When resolving the base field, an implementation MUST first check whether the value matches an entry in the typedefs array of the same NAIM Document. If a match is found, the type is treated as a typedef reference. If no match is found, the value is interpreted as a YANG built-in type name. Typedef names SHOULD NOT duplicate YANG built-in type names to avoid ambiguity.
Visibility Fields The visibility field of a node object expresses the conditions under which the node is present or applicable. This field corresponds to the YANG if-feature and when constructs.
if-feature The if-feature field within a visibility object declares that the node is conditional on one or more features. The if-feature value MAY be:
  • A simple string naming a single feature, or
  • A logical expression object using and, or, or not keys. and and or values are arrays of feature names or nested logical expression objects. not value is a single feature name or nested logical expression object.
Examples:
  • Single feature: { "if-feature": "high-speed" }
  • Conjunction: { "if-feature": { "and": ["feature-a", "feature-b"] } }
  • Nested: { "if-feature": { "or": ["feature-a", { "and": ["feature-b", "feature-c"] }] } }
  • Negation: { "if-feature": { "not": "feature-a" } }
when The when field within a visibility object declares a conditional expression that must evaluate to true for the node to be present. The when value MAY be:
  • A natural-language string describing the condition, or
  • An object containing:
    • xpath (string, REQUIRED in this form): An XPath expression.
    • description (string, OPTIONAL): A human-readable description of the condition.
When when is expressed as a natural-language string, implementations SHOULD attempt to derive an equivalent XPath expression during YANG generation. If a reliable XPath expression cannot be derived, the implementation MUST NOT silently discard the condition. The implementation SHOULD either report that the condition requires manual completion or retain the natural-language form in the generated YANG description statement with a clear annotation that XPath completion is pending.
Deviation Declarations Deviation declarations describe the ways in which a specific device implementation departs from a base YANG module. They correspond to the YANG deviation statement. Deviation objects MAY appear in the deviations field of the module object defined in Section 5.3. Each deviation object MUST contain:
  • target: A string. The absolute schema path of the node being deviated.
  • type: A string. It MUST be one of "not-supported", "add", "replace", or "delete".
  • reason: A string. A human-readable explanation of why this deviation exists.
Deviation objects of type "add", "replace", or "delete" MAY contain additional fields describing the specific property being added, replaced, or deleted, using the same field names as the corresponding node template fields.
Extension Use Extension use within a node object allows a node to carry annotations defined by extension declarations in the extensions array or by external modules. When present, the extensions field of a node object MUST be an array. Each entry MUST contain:
  • name: A string. The qualified extension keyword, typically in the form "prefix:keyword".
  • source-module: A string. The name of the YANG module that defines the extension.
  • meaning: A string. A human-readable description of why this extension is applied to this node and what it semantically conveys.
Each entry MAY contain:
  • value: A string. The literal argument value passed to the extension.
If any of the required fields above cannot be determined, the implementation MUST omit the extension-use entry entirely rather than emit an incomplete representation. The implementation SHOULD inform the user or operator that the extension entry was omitted and that manual completion may be required.
Submodule Handling A NAIM Document representing a YANG submodule MUST contain a submodule object at the top level instead of a module object, as specified in Section 5.4. A submodule NAIM Document MAY contain typedefs, groupings, identities, extensions, features, and nodes arrays. When a conforming implementation transforms a submodule NAIM Document into YANG, the result MUST:
  • include a belongs-to statement referencing the parent module name given in the belongs-to field of the submodule object;
  • include a prefix sub-statement within belongs-to, as required by [RFC7950, Section 7.2.2] -- the prefix value is derived using the same automatic derivation rule defined in Section 15.3.2;
  • NOT include a namespace statement, as the namespace is inherited from the parent module; and
  • NOT include a module-level prefix statement for the same reason.
NAIM Skills This section defines four Skills that constitute the Skill Layer of the NAIM architecture. Each Skill specifies inputs, outputs, and behavioral rules for AI participation in the modeling workflow. Skills are independently versionable and customizable: implementations MAY adapt question strategies, presentation styles, and interaction patterns to their target user populations without violating the normative requirements of this section.
Skill A: Conversational Modeling Skill A transforms natural language modeling intent into a complete NAIM Document through structured dialogue. Input: Natural language description of a network resource, or an existing NAIM Document with incremental modeling requirements. Output: A complete NAIM Document in Canonical JSON.
Behavioral Requirements Skill A MUST:
  • when the user expresses modeling intent, first determine whether this is a new model or a continuation of an existing model;
  • generate an initial draft, marking uncertain fields with [PENDING];
  • identify missing required fields and prompt for clarification;
  • ask one question at a time;
  • prioritize structural questions before type and constraint questions;
  • identify opportunities for typedef and grouping abstraction when repeated types or structures are detected;
  • not proceed to Skill B until the document meets the completeness criteria defined in Section 15.1.2.
Completeness Criteria A NAIM Document is considered complete for the purposes of Skill A when:
  • all nodes have path, description, and node-type;
  • all list nodes have key;
  • all leaf and leaf-list nodes have type and writable;
  • all choice nodes have a non-empty cases array;
  • each case has name and nodes;
  • all container and list nodes have operations.preconditions and operations.side-effects; and
  • no [PENDING] markers remain.
Recommended Question Priority
  1. Node type and hierarchy structure
  2. Writable (configuration vs. state)
  3. Type and value constraints
  4. Related nodes
  5. Preconditions and side effects
  6. Visibility conditions
  7. Extension keywords and additional semantics
Skill B: Natural Language Summarization Skill B transforms a complete NAIM Document into a natural language summary for human confirmation before proceeding to generation. Input: A complete NAIM Document in Canonical JSON. Output: A natural language summary.
Output Requirements The summary MUST:
  • not expose internal NAIM syntax or JSON structure;
  • organize content by business function, not by field enumeration;
  • distinguish configurable items from read-only items;
  • describe key constraints and side effects;
  • provide separate descriptions for rpc, action, and notification nodes; and
  • conclude with an explicit request for user confirmation.
Skill C: YANG Generation Skill C transforms a confirmed NAIM Document into a standard YANG module through deterministic tooling. Input: A confirmed NAIM Document in Canonical JSON. Output: A YANG module conforming to [RFC7950] or [RFC6020].
Core Mapping Rules
  • path determines the node's position in the schema tree;
  • description maps to YANG description;
  • writable: false maps to config false;
  • type is generated per the type representation rules in Section 10;
  • natural-language constraints and when SHOULD be converted to XPath where possible; if conversion is not reliable, the implementation MUST report the issue rather than silently discard the constraint;
  • cross-module paths automatically generate import statements;
  • if-feature logical expressions are converted to valid YANG if-feature statements; and
  • all top-level arrays (features, typedefs, groupings, identities, extensions, deviations, revisions) map to their corresponding YANG statements.
Prefix and Namespace Generation
  • YANG prefix MAY be derived automatically from the module name (e.g., taking the first letter of each hyphen-separated segment). The same derivation rule applies to the prefix sub-statement within belongs-to for submodule generation (see Section 14).
  • namespace is generated from a template:
    • IETF-style modules: urn:ietf:params:xml:ns:yang:{module-name}
    • Private modules: organization-specific template, e.g., urn:example:{module-name}
YANG Version Strategy Unless the NAIM Document explicitly models YANG 1.1-only semantics, Skill C MUST default to generating YANG 1.0 RFC6020. Skill C SHOULD automatically upgrade to YANG 1.1 RFC7950 when the NAIM Document contains any of the following:
YANG 1.1-only feature NAIM modeling indicator
action node node-type is "action" (distinct from top-level rpc)
anydata node-type is "anydata" (see Section 8.7)
if-feature logical expression visibility.if-feature uses and/or/not compound objects
modifier (invert-match) type.pattern includes negation semantics
augment with when A node whose path targets another module's namespace (cross-module augmentation) and whose visibility.when is present
If a YANG 1.1-only feature is detected but the target environment is explicitly constrained to YANG 1.0, the implementation MUST report the incompatibility rather than silently downgrade or skip the affected nodes.
Submodule Generation When the input is a submodule-type NAIM Document, the YANG generation rules defined in Section 14 apply.
Skill D: Reverse Engineering Skill D transforms existing YANG modules into NAIM Documents, enriching them with AI-generated semantic annotations. Input: An existing YANG module. Output: A NAIM Document in Canonical JSON with confidence annotations.
Dual-Component Architecture Skill D is implemented as two complementary components: Structural extraction (Tool Layer): Deterministic extraction of YANG-derivable fields at high confidence:
  • node-type, path, key, config/writable status
  • type (including range, length, pattern, enum, bits)
  • default values, must/when expressions, if-feature
  • typedef, grouping, rpc/action/notification structure
Semantic completion (AI): AI-assisted enrichment of fields not directly present in YANG syntax:
  • enhanced natural language descriptions
  • relationship explanations
  • operational semantics (preconditions, side-effects)
  • usage examples
Confidence Levels All AI-generated fields in Skill D output MUST carry confidence annotations:
  • high: Directly derived from YANG structure; no AI inference.
  • medium: Derived from YANG description statements or referenced RFC text; moderate inference.
  • review-required: AI-inferred from context; MUST be reviewed by a qualified person before production use.
Review Requirements
  • Structurally extracted fields MAY be used without additional review.
  • AI-generated descriptions, preconditions, side-effects, and error-conditions with review-required confidence MUST NOT be published to production model assets without human confirmation.
  • AI-generated regular expressions, XPath expressions, and constraint expressions MUST be treated as review-required regardless of the AI system's stated confidence.
Known Limitations NAIM improves the reliability of AI-assisted YANG modeling by making implicit semantics explicit and machine-verifiable. However, the following limitations apply:
  • NAIM does not replace expert review for complex XPath expressions, cross-module constraint interactions, and security implications of modeled operations.
  • The quality of Skill A output is bounded by the quality of the underlying AI system. NAIM provides structure and guardrails, not intelligence.
  • Skill D output at review-required confidence MUST NOT be treated as authoritative. AI-inferred operational semantics (preconditions, side-effects) may be plausible but incorrect.
  • Reliable generation of complex XPath from natural language remains best-effort. Implementations MUST report when XPath generation is uncertain rather than emit incorrect expressions.
  • NAIM does not model cross-module augmentation relationships, mount points, or YANG library structures. These are outside the scope of the current version.
  • NAIM does not model YANG refine statements within uses applications.
Interoperability Expectations Interoperability in this specification is defined at the representation level. Independent implementations conforming to this document SHOULD be able to exchange canonical NAIM Document JSON objects and interpret them consistently. Specifically, conforming implementations:
  • MUST accept and produce canonical JSON objects that conform to the top-level structure defined in Section 5.
  • MUST interpret node-type values consistently with the node template families defined in Section 8.
  • MUST interpret type field contents consistently with the type representation rules defined in Section 10.
  • MUST preserve the path, description, writable, and type fields of node objects when exchanging NAIM Documents.
  • SHOULD preserve all optional semantic fields when exchanging NAIM Documents, even if the receiving implementation does not use those fields internally.
  • MUST NOT reject NAIM Documents solely because they contain fields that the implementation does not recognize. Unknown fields SHOULD be preserved and forwarded without modification.
  • SHOULD produce Markdown Views that conform to the rendering rules in Section 6 when a Markdown View is requested.
  • SHOULD produce LLM Context Views that conform to the requirements in Section 7 when an LLM Context View is requested.
Implementations are NOT required to share identical AI interaction logic, reconstruction algorithms, confidence handling strategies, or YANG generation internals. Interoperability is defined at the data format boundary, not at the workflow boundary. Implementations SHOULD clearly distinguish between NAIM-level validation (structural conformance to this specification) and YANG-level validation (semantic conformance to YANG rules and target device constraints). A NAIM Document that conforms to the schema defined in Appendix A is structurally valid but is not guaranteed to produce a YANG module that will pass validation in any specific YANG-based system. Authoritative semantic validation -- including evaluation of YANG must, when, and leafref expressions, uniqueness constraints, and instance-level data validation -- is the responsibility of the target YANG validation environment, not of NAIM tools (see Section 1.3).
Security Considerations NAIM Documents are semantic model artifacts. They do not themselves constitute executable code or protocol messages, but they may drive downstream processes -- including YANG module generation and, through [NAIM-OP], runtime network configuration -- that have direct operational consequences. The following security considerations apply. Integrity of NAIM Documents. Because a NAIM Document may be used as input to deterministic tool pipelines that generate YANG modules or as the validation authority for runtime Operation IRs [NAIM-OP], unauthorized modification of a NAIM Document can introduce incorrect or malicious semantics into downstream artifacts. Implementations SHOULD protect NAIM Documents in storage and transit using integrity mechanisms appropriate to the deployment environment. Confidentiality of semantic model assets. NAIM Documents may contain detailed descriptions of network topology, device capabilities, and operational constraints. This information may be sensitive. Implementations SHOULD apply confidentiality protections appropriate to the sensitivity of the modeled information. Validation before downstream use. Implementations that consume NAIM Documents as input to YANG generation or runtime validation MUST validate the structural conformance of the document before processing. Accepting malformed or adversarially crafted NAIM Documents without validation may produce incorrect YANG modules or permit invalid Operation IRs to pass validation. AI-generated content review. When a NAIM Document is produced in whole or in part by an AI-assisted authoring process (Skills A and D), the resulting document SHOULD be subject to human review before it is used to generate or deploy production YANG modules or serve as a runtime validation authority. AI-generated semantic content may contain inaccuracies that are not apparent from structural validation alone. External document integrity. If Skill D retrieves external documents (RFCs, vendor documentation) during reverse engineering, implementations SHOULD verify the authenticity and integrity of those documents to prevent contamination of the modeling result. Audit logging. Implementations that participate in workflows where NAIM Documents drive operational changes SHOULD maintain audit logs sufficient to reconstruct the chain of actions from a NAIM Document to a resulting downstream state change. Skill A dialogue logs and intermediate JSON artifacts may contain sensitive network information and SHOULD be subject to access control and retention policies.
IANA Considerations This document has no IANA actions. Future companion documents defining a media type for the NAIM canonical JSON format MAY request registration of an appropriate media type with IANA at that time.
References
Normative References . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . ]]>
Informative References . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . [NAIM-OP] Feng, C., "Operation Intent Intermediate Representation for Model-Driven Network Execution", Work in Progress, Internet-Draft, draft-feng-netconf-naim-op-00, April 2026. ]]>
NAIM Canonical JSON Schema The following is the normative JSON Schema for NAIM Documents. Implementations that validate NAIM Documents MUST accept documents conforming to this schema.
Example: Canonical JSON Document The following is an example of a conforming canonical NAIM Document representing a simplified Ethernet interface module.
Example: Derived Markdown View The following is the Markdown View derived from the canonical JSON document in Appendix B.
End-to-End Example with YANG Output This appendix presents the YANG module that a conforming implementation would produce from the canonical JSON document in Appendix B. Per the YANG version strategy defined in Section 15.3.3, this example uses YANG 1.0 because no YANG 1.1-only features are present. Note: The admin-status node in Appendix B carries a natural-language constraint ("The admin-status MUST be set to 'down' before the interface can be deleted.") that cannot be reliably converted into a YANG XPath expression by deterministic tooling. Per Section 15.3.1, a conforming implementation MUST NOT silently discard such a constraint. In this example, the constraint is retained in the generated YANG description statement with an annotation indicating that manual completion of a must statement is required (see Section 11.2).