NAIM: A Canonical Semantic Representation for AI-Assisted YANG Modeling and Validation

1.1. 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.¶

1.2. 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.¶

1.3. 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.¶

1.4. 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:¶

Design-time:  Natural Language -> NAIM Document -> YANG
Runtime:      Natural Language -> Operation IR -> [validated against
              NAIM Document] -> NETCONF/RESTCONF execution

1.5. 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.¶

4.1. Three-Layer Model

                    +-----------------------+
                    |   Skill Layer         |
                    |   (AI-driven)         |
                    |   Skills A, B, C, D   |
                    +-----------+-----------+
                                |
                 consumes       |    produces
                 Specification  |    NAIM Documents
                                |
    +------------------+        |        +------------------+
    | Specification    |--------+------->| Tool Layer       |
    | Layer            |                 | (deterministic)  |
    | (format + rules) |<----------------| validation,      |
    +------------------+   validates     | generation,      |
                           against       | conversion       |
                                         +------------------+

4.2. 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.¶

4.3. 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¶

4.4. 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).¶

4.5. Validation-Reflection-Retry Mechanism

When the Tool Layer detects validation errors in AI-generated NAIM Documents, the following three-phase error correction mechanism applies.¶

{
  "error_code": "MissingRequiredField",
  "path": "/nodes/1/type",
  "message": "Node at path '/eth-interface:interfaces/
    interface/bandwidth' is of node-type 'leaf' but is
    missing required field 'type'.",
  "expected": "A type object with at least a 'base' field,
    e.g., {\"base\": \"uint32\"}"
}

5.1. 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.¶

5.2. 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.¶

5.3. 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.¶

5.4. 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.¶

5.5. Top-Level Arrays

5.6. 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.¶

6.1. 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.¶

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.¶

6.3. 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}¶

6.4. 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.¶

6.5. 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.¶

6.6. 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.¶

6.7. 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.¶

7.1. 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.¶

7.2. 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.¶

7.3. 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).¶

7.4. 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.¶

8.1. 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.¶

8.2. 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.¶

8.3. 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.¶

8.4. 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.¶

8.5. 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.¶

8.6. 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.¶

8.7. 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.¶

8.8. 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.¶

9.1. 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.¶

9.2. 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.¶

9.3. 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.¶

9.4. 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.¶

10.1. 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.¶

10.2. 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.¶

10.3. 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.¶

10.4. Union

For union types, the type object MUST contain:¶

• base: The string "union".¶
• types: An array of type objects, each conforming to this section.¶

10.5. 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.¶

10.6. 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.¶

10.7. 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.¶

11.1. 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" } }¶

11.2. 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.¶

15.1. 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.¶

15.2. 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.¶

15.3. 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].¶

15.4. 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.¶

20.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
           the Network Configuration Protocol (NETCONF)", RFC 6020,
           DOI 10.17487/RFC6020, October 2010,
           <https://www.rfc-editor.org/rfc/rfc6020>.

[RFC6901]  Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
           "JavaScript Object Notation (JSON) Pointer", RFC 6901,
           DOI 10.17487/RFC6901, April 2013,
           <https://www.rfc-editor.org/rfc/rfc6901>.

[RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
           RFC 7950, DOI 10.17487/RFC7950, August 2016,
           <https://www.rfc-editor.org/rfc/rfc7950>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174,
           DOI 10.17487/RFC8174, May 2017,
           <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON)
           Data Interchange Format", STD 90, RFC 8259,
           DOI 10.17487/RFC8259, December 2017,
           <https://www.rfc-editor.org/rfc/rfc8259>.

20.2. Informative References

[RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
           and A. Bierman, Ed., "Network Configuration Protocol
           (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
           <https://www.rfc-editor.org/rfc/rfc6241>.

[RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
           Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
           <https://www.rfc-editor.org/rfc/rfc8040>.

[RFC8340]  Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
           BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
           <https://www.rfc-editor.org/rfc/rfc8340>.

[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.