> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Structuring Requirement IDs and Identities in xspec

> Requirement IDs in xspec are structural dot-paths. Learn the segment rules, full identity format, and naming conventions that keep your graph valid.

Every requirement section in xspec is identified by a dot-path that mirrors the nesting of `<S>` tags in your MDX file. Because the ID encodes structure, the graph can validate parent-child relationships at build time and give you stable, human-readable addresses for every requirement — from the top-level domain all the way down to an individual acceptance criterion.

## Structural Dot-Paths

A child's ID must equal its parent's ID followed by a `.` and one new segment. This rule is enforced at build time; a mismatch is a build error.

```mdx theme={null}
<S id="auth">
  <S id="auth.login">
    <S id="auth.login.valid">
      The system accepts a correct username and password.
    </S>
  </S>
</S>
```

In the example above, `auth.login.valid` is valid because it extends `auth.login`, which extends `auth`. Skipping a level — writing `auth.valid` as a child of `auth.login` — is a structural violation.

<Note>
  Every non-root section **must** declare an `id`. Sections without an `id` are a build error.
</Note>

## Segment Rules

Each dot-separated segment must satisfy all of the following:

* **Non-empty** — a segment cannot be a blank string
* **No special characters** — segments may not contain `.`, `#`, whitespace, or ASCII control characters
* **Not a reserved word** — the following identifiers are reserved and cannot be used as segments: `$`, `__proto__`, `prototype`, `constructor`, `then`
* **No duplicates** — two sibling sections sharing the same full ID is a build error

<Tip>
  Use **camelCase** for segments whenever possible. camelCase segments are valid JavaScript identifiers, which means xspec can expose them via dot notation in TypeScript without requiring bracket notation.
</Tip>

If you have a segment that is not a valid JavaScript identifier — for example a slug like `login-v2` — you can still use it, but you will need bracket notation when accessing it programmatically:

```ts theme={null}
graph["auth"]["login-v2"]  // bracket notation required for non-identifier segments
graph.auth.loginV2          // camelCase avoids this
```

## Full Identity: `path#id`

A requirement ID alone is scoped to a file. The globally unique address of a node combines the file path and the ID with a `#` separator:

```
specs/AUTH.mdx#auth.login.valid
```

You use full identities whenever you reference a requirement from outside its own file — in `d` props, `{text(...)}` expressions, `xspec show` arguments, and TypeScript markers.

## Root Nodes

Each spec file has an implicit **root node** identified by its file path alone, with no `#id` suffix:

```
specs/AUTH.mdx
```

The root node is the structural parent of every top-level `<S>` in the file. You do not declare it; xspec creates it automatically. Root nodes are excluded from coverage requirements by default.

## Exploring IDs

Use `xspec ids` to list every requirement ID in the project. The `--tree` flag renders the hierarchy so you can spot structural problems at a glance:

```sh theme={null}
xspec ids --tree
```

To inspect a single node in full — including its edges, hashes, and metadata — use `xspec show` with the full identity:

```sh theme={null}
xspec show specs/AUTH.mdx#auth.login.valid
```