nvueschema

package module
v0.0.0-...-a870357 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 24, 2026 License: MIT Imports: 15 Imported by: 0

README

nvueschema

Fetch the configuration schema from Cumulus Linux NVUE OpenAPI specs and view, diff, validate, or convert them to other formats.

demo

This tool exists because the only schema Nvidia provides is a full OpenAPI spec including all API endpoints, which makes it harder to reason about or validate just the configuration.

Install

go install github.com/nemith/nvueschema/cmd/nvueschema@latest

Usage

Anywhere a spec is expected, you can pass a version number instead of a file path. Specs are cached locally in ~/.cache/nvueschema and validated with If-Modified-Since. Use --no-cache to skip the cache.

# Download the 5.16 spec from Nvidia and save it as spec.json
nvueschema fetch 5.16 -o spec.json

# Show a tree of all the `bridge` options in the 5.16 spec
nvueschema show 5.16 --path bridge

# Show a tree of differences between version 5.14 to 5.16
nvueschema diff 5.14 5.16

# Show a flat (one change per line) differences between 5.15 and 5.16 only for the interface top-level
nvueschema diff 5.15 5.16 --path interface -O flat

# Validate that the config.yaml file is valid for version 5.16
nvueschema validate 5.16 config.yaml

# Generate different config schemas
nvueschema gen -f pydantic 5.16 -o nvue.py
nvueschema gen -f yang 5.14
nvueschema gen -f proto --validate 5.16
nvueschema gen -f go 5.16 -o nvue.go

Output formats

The supported output schemas for the gen command.

Format Flag Notes
JSON Schema jsonschema, js Draft 2020-12 with $defs for format types
Pydantic pydantic, py v2 models with Field(pattern=...) validation
YANG yang Module with typedefs, inet: types, leaf-list
OpenAPI openapi, oas Minimal 3.1 spec, config schema only
Go go, golang Structs with json/yaml tags, net/netip types
Protobuf protobuf, proto Proto3 messages, optional --validate for buf protovalidate

All formats include pattern-validated types for MAC addresses, interface names, route distinguishers, BGP communities, etc.

Library

You can also use the Go package directly.

import nvue "github.com/nemith/nvueschema"

p, _ := nvue.NewParser(reader)
cfg, _ := p.ConfigSchema()

// Generate
nvue.WriteYANG(os.Stdout, cfg, p.Info())

// Diff
diff := nvue.DiffSchemas(oldCfg, newCfg, "")
for _, c := range diff.Changes {
    fmt.Println(c.Kind, c.Path)
}

// Validate
doc := cfg.JSONSchemaDoc()

Documentation

Overview

Package nvueschema extracts and generates config schemas from Cumulus Linux NVUE OpenAPI specs.

Index

Constants

View Source 
const UserAgent = "cumulus-schema/1.0"

userAgent must be set on all requests to api-prod.nvidia.com. Akamai's bot protection blocks Go's default "Go-http-client/1.1" UA, causing the connection to hang indefinitely.

Variables

This section is empty.

Functions

func ConfigLeafPaths 

func ConfigLeafPaths(config any, schemas ...*Config) []string

ConfigLeafPaths walks a parsed config value (from YAML/JSON) alongside the schema tree and returns all paths in schema notation (with [*] for map keys). Both schemas should be provided to handle keys that may only exist in one version.

func FetchSpec 

func FetchSpec(v VersionInfo) ([]byte, error)

FetchSpec downloads the spec for the given version from Nvidia.

func SpecURL 

func SpecURL(v VersionInfo) string

SpecURL returns the download URL for a given version. Versions 5.0-5.8 use the old docs.nvidia.com path. Versions 5.9+ use the new api-prod.nvidia.com endpoint.

func WriteGoStructs 

func WriteGoStructs(w io.Writer, schema *Config, info map[string]any) error

WriteGoStructs outputs the config schema as Go struct definitions with json tags.

func WriteJSONSchema 

func WriteJSONSchema(w io.Writer, schema *Config, info map[string]any) error

WriteJSONSchema outputs the config schema as a standalone JSON Schema draft-07 document.

func WriteOpenAPI 

func WriteOpenAPI(w io.Writer, schema *Config, info map[string]any) error

WriteOpenAPI outputs a minimal OpenAPI 3.0 spec containing only the config schema.

func WriteProtobuf 

func WriteProtobuf(w io.Writer, schema *Config, info map[string]any, validate bool) error

WriteProtobuf outputs the config schema as a .proto file. If validate is true, buf protovalidate constraints are included.

func WritePydantic 

func WritePydantic(w io.Writer, schema *Config, info map[string]any) error

WritePydantic outputs the config schema as Python Pydantic v2 model classes.

func WriteYANG 

func WriteYANG(w io.Writer, schema *Config, info map[string]any) error

WriteYANG outputs the config schema as a YANG module.

Types

type Change 

type Change struct {
	Path       string
	Kind       string // "added", "removed", "changed"
	Desc       string
	TypeSegs   []TypeSegment // type info for added/removed leaves
	DefaultVal string        // default value for added/removed leaves
}

Change represents a single schema difference.

type Config 

type Config struct {
	Description          string             `json:"description,omitempty"`
	Type                 string             `json:"type,omitempty"`
	Nullable             bool               `json:"nullable,omitempty"`
	Properties           map[string]*Config `json:"properties,omitempty"`
	AdditionalProperties *Config            `json:"additionalProperties,omitempty"`
	Items                *Config            `json:"items,omitempty"`
	AllOf                []*Config          `json:"allOf,omitempty"`
	OneOf                []*Config          `json:"oneOf,omitempty"`
	AnyOf                []*Config          `json:"anyOf,omitempty"`
	Enum                 []any              `json:"enum,omitempty"`
	Default              any                `json:"default,omitempty"`
	Minimum              *float64           `json:"minimum,omitempty"`
	Maximum              *float64           `json:"maximum,omitempty"`
	MinLength            *int               `json:"minLength,omitempty"`
	MaxLength            *int               `json:"maxLength,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	Format               string             `json:"format,omitempty"`
	Required             []string           `json:"required,omitempty"`
	XModelName           string             `json:"x-model-name,omitempty"`
	SourceRef            string             `json:"-"` // x-defs key or API path, not serialized
}

Config is a resolved JSON-Config-like node (no $ref remaining).

func FlattenComposite 

func FlattenComposite(s *Config) *Config

FlattenComposite merges allOf, anyOf, and oneOf into a single Schema by combining all their properties, additionalProperties, etc. In the NVUE spec these composition keywords are used to express "this object has all of these property groups", so merging is the right interpretation.

func SubSchema 

func SubSchema(s *Config, path string) (*Config, error)

SubSchema walks the schema tree to the given dotted path.

func (*Config) JSONSchemaDoc 

func (s *Config) JSONSchemaDoc() map[string]any

JSONSchemaDoc builds a complete JSON Schema 2020-12 document, including $schema and $defs for format types.

func (*Config) ToJSONSchema 

func (s *Config) ToJSONSchema() map[string]any

ToJSONSchema converts a Schema to a JSON Schema map.

type Diff 

type Diff struct {
	Changes []Change
}

Diff holds the result of comparing two schemas.

func DiffSchemas 

func DiffSchemas(old, newer *Config, path string) *Diff

DiffSchemas compares two schemas and returns a Diff.

func (*Diff) Filter 

func (d *Diff) Filter(paths []string) *Diff

Filter returns a new Diff containing only changes under the given paths.

func (*Diff) FilterAffected 

func (d *Diff) FilterAffected(configPaths []string) *Diff

FilterAffected returns a new Diff containing only changes that overlap with the given config paths. A change is included if it is at, above, or below any config path (bidirectional prefix match).

type Node 

type Node struct {
	Name       string
	TypeSegs   []TypeSegment // type annotation segments
	DefaultVal string        // default value, rendered separately
	Desc       string
	Children   []*Node
}

Node represents a node in the show tree.

func BuildShowTree 

func BuildShowTree(name string, s *Config) *Node

BuildShowTree creates a Node tree from a schema.

func CollapseNode 

func CollapseNode(n *Node) (string, *Node)

CollapseNode collapses single-child chains.

type Parser 

type Parser struct {
	// contains filtered or unexported fields
}

Parser resolves $ref pointers within x-defs and extracts the config tree.

func NewParser 

func NewParser(r io.Reader) (*Parser, error)

NewParser parses an OpenAPI JSON spec from an io.Reader.

func (*Parser) ConfigPaths 

func (e *Parser) ConfigPaths() []string

ConfigPaths returns all paths that have a PATCH operation (i.e., configurable).

func (*Parser) ConfigSchema 

func (e *Parser) ConfigSchema() (*Config, error)

ConfigSchema returns the fully-resolved config schema starting from the PATCH request body of the root path ("/").

func (*Parser) Info 

func (e *Parser) Info() map[string]any

Info returns the spec info block.

type TypeSegment 

type TypeSegment struct {
	Text    string
	Literal bool // true for enum/literal values, false for type names
}

TypeSegment is a piece of a type annotation, either a type name or a literal value.

func LeafTypeSegs 

func LeafTypeSegs(s *Config) (segs []TypeSegment, defaultVal string)

LeafTypeSegs returns the type segments and default value for a leaf schema.

func ScalarUnionTypeSegs 

func ScalarUnionTypeSegs(s *Config) (segs []TypeSegment, defaultVal string)

ScalarUnionTypeSegs returns type segments for a scalar union schema.

type VersionInfo 

type VersionInfo struct {
	Major int
	Minor int
	Slug  string
}

VersionInfo holds parsed version information.

func ParseVersion 

func ParseVersion(version string) (VersionInfo, error)

ParseVersion parses a Cumulus Linux version string (e.g. "5.14").

Source Files

View all Source files

Directories

Path Synopsis
cmd
nvueschema command
Command nvueschema is a CLI for extracting and generating config schemas from Cumulus Linux NVUE OpenAPI specs.
 Command nvueschema is a CLI for extracting and generating config schemas from Cumulus Linux NVUE OpenAPI specs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.