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

# Phase 2 — Field vocabulary

> Establish and validate the input field names before writing test cases.

Authoring is invite-only private beta — [request access](https://aethis.ai/developer-access).

## Why field vocabulary matters

Test cases are written against field names. If the names in your test cases don't exactly match the names the engine expects, the tests will silently fail for the wrong reason — the engine receives an unknown field and treats it as absent.

Phase 2 resolves this before test writing begins. You discover what fields the source text implies, validate them against your expected spec, and confirm names before writing a single test case.

***

## Step 1 — Discover fields from source text

```
aethis_discover_fields({ project_id: "proj_8CzLVwyx53rTGEJv" })
```

**Returns:**

```json theme={null}
{
  "project_id": "proj_8CzLVwyx53rTGEJv",
  "fields": [
    {
      "key": "child.age",
      "sort": "Int",
      "description": "Child's age in whole years at the start of the academic year",
      "source_ref": "FSM Regulations 2014, Regulation 3(1)"
    },
    {
      "key": "child.school_type",
      "sort": "Enum",
      "enum_values": ["state_funded", "independent", "home_educated"],
      "description": "Type of school the child attends",
      "source_ref": "Education Act 1996, s.512(1)"
    },
    {
      "key": "child.year_group",
      "sort": "Enum",
      "enum_values": ["reception", "year_1", "year_2", "year_3_plus"],
      "description": "School year group the child is enrolled in",
      "source_ref": "Children and Families Act 2014, s.105"
    }
  ]
}
```

***

## Step 2 — Set a field spec (optional but recommended)

If you know the fields you expect before discovery, set a spec upfront. `aethis_discover_fields` will auto-validate against it:

```
aethis_set_field_spec({
  project_id: "proj_8CzLVwyx53rTGEJv",
  expected_fields: [
    { key: "child.age", sort: "Int" },
    {
      key: "child.school_type",
      sort: "Enum",
      enum_values: ["state_funded", "independent", "home_educated"]
    }
  ]
})
```

When a spec is set, `aethis_discover_fields` returns a validation result alongside the field list showing any missing fields, type mismatches, or unexpected extras.

***

## Step 3 — Explicit validation

Validate discovered fields against your spec as a gate before writing test cases:

```
aethis_validate_fields({
  project_id: "proj_8CzLVwyx53rTGEJv",
  expected_fields: [
    { key: "child.age", sort: "Int" },
    { key: "child.school_type", sort: "Enum" }
  ]
})
```

**Returns (all match):**

```json theme={null}
{
  "all_match": true,
  "validated_fields": [
    { "key": "child.age", "sort": "Int", "status": "match" },
    { "key": "child.school_type", "sort": "Enum", "status": "match" }
  ],
  "discrepancies": []
}
```

**Returns (mismatch):**

```json theme={null}
{
  "all_match": false,
  "validated_fields": [
    { "key": "child.age", "sort": "Int", "status": "match" },
    { "key": "child.school_type", "sort": "Enum", "status": "type_mismatch", "discovered_sort": "String" }
  ],
  "discrepancies": [
    {
      "type": "type_mismatch",
      "key": "child.school_type",
      "expected_sort": "Enum",
      "discovered_sort": "String",
      "note": "Source text implies a fixed set of values — prefer Enum over String"
    }
  ]
}
```

***

## Refine if fields are wrong

```
aethis_refine_fields({
  project_id: "proj_8CzLVwyx53rTGEJv",
  feedback: "child.school_type should be Enum with values state_funded, independent, home_educated. The FSM Regulations 2014 Regulation 3(2)(b) restricts eligibility to state-funded schools — the type must be captured as an Enum, not a free-text String."
})
```

Feedback must reference the specific field and its source in the legislation. After refining, re-run `aethis_discover_fields` to confirm the change.

***

## Field naming conventions

| Convention                         | Example                                                      |
| ---------------------------------- | ------------------------------------------------------------ |
| Dot-separated namespacing          | `child.age`, `household.annual_net_income`                   |
| Lowercase snake\_case              | `receives_universal_credit` not `receivesUniversalCredit`    |
| Descriptive, not abbreviated       | `annual_net_income` not `ann_net_inc`                        |
| Boolean fields named as predicates | `child.is_looked_after`, `household.receives_income_support` |
| Enum values lowercase snake\_case  | `state_funded` not `StateFunded`                             |

Consistent naming within a domain makes test cases readable and prevents silently mismatched fields. Every field in a domain should follow the same convention.

***

## After field vocabulary

Once field names are validated, write your test cases using those exact field names, then move to [Phase 3 — Rule generation](/authoring/rule-generation).

<Tip>
  Write at least 5–10 test cases before generating rules. Cover: boundary values (just below, at, and above every threshold), every Enum value, and any combination of fields that exercises a distinct code path. The quality and coverage of your test suite determines how quickly rule generation converges.
</Tip>