# nsx-module.yaml

Module metadata. Declares what a module is, what it builds, what it needs and what it is compatible with.

## Fields

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| schema_version | int (1), required |  | Module metadata schema version. |
| module.name | string, required |  | Module name. Must match the name used in the registry and in nsx.yml. |
| module.type | string (sdk_provider, soc, board, runtime, portable_api, algorithm, tooling, backend_specific), required |  | What kind of module this is. Drives resolution order and compatibility rules. |
| module.version | string, required |  | Module version string. |
| module.category | string |  | Grouping used by the module catalog. |
| module.provider | string |  | Organization or project that supplies the module. |
| support.ambiqsuite | bool (true), required |  | Whether the module builds against AmbiqSuite. NSX requires true. |
| support.zephyr | bool, required |  | Whether the module ships a Zephyr integration. When true, integrations.zephyr becomes required. |
| build.cmake.package | string, required |  | CMake package name the module exports. |
| build.cmake.targets | list of string, required |  | CMake targets the module exports. Must be non-empty. |
| depends.required | list of string, required |  | Modules that must be present. May be empty. |
| depends.optional | list of string, required |  | Modules used when present. May be empty. |
| compatibility.boards | list of string, required |  | Boards the module supports. Must be non-empty. |
| compatibility.socs | list of string, required |  | SoCs the module supports. Must be non-empty. |
| compatibility.toolchains | list of string, required |  | Toolchains the module supports. Must be non-empty. |
| integrations.zephyr.path | string, required when support.zephyr is true |  | Zephyr module directory. Required when support.zephyr is true. |
| integrations.zephyr.module_yml | string, required when support.zephyr is true |  | Path to the Zephyr module.yml. Required when support.zephyr is true. |
| integrations.zephyr.kconfig | string, required when support.zephyr is true |  | Path to the module's Kconfig. Required when support.zephyr is true. |
| constraints.required_sdk_provider | string |  | SDK provider module this module must be built against. |
| summary | string |  | One-line description shown in the module catalog. |
| capabilities | list of string |  | What the module provides, for search and agent discovery. |
| use_cases | list of string |  | Situations the module suits. |
| anti_use_cases | list of string |  | Situations the module does not suit. |
| agent_keywords | list of string |  | Extra search terms for agent tooling. |
| example_refs | list of string |  | Examples that use the module. |
| composition_hints | list of string |  | Modules this one is usually combined with. |

## Example

```yaml
schema_version: 1
module:
  name: nsx-board-apollo510-evb
  type: board
  version: "0.1.0"
support:
  ambiqsuite: true
  zephyr: false
build:
  cmake:
    package: nsx_board_apollo510_evb
    targets:
      - nsx::board_apollo510_evb
depends:
  required:
    - nsx-ambiq-hal
  optional: []
compatibility:
  boards:
    - apollo510_evb
  socs:
    - apollo510
  toolchains:
    - arm-none-eabi-gcc
```

## How it is read

NSX reads `nsx-module.yaml` through `neuralspotx.metadata.validate_nsx_module_metadata`, which raises `ValueError` when the document is invalid. The supported `schema_version` is `1`.

**Unknown keys:** Kept. The validator checks the keys it knows and ignores the rest.