Phase 2 — Field vocabulary

Authoring is invite-only private beta. Everything on this page needs an Aethis API key with authoring scopes, plus your own model-provider key for the generation steps. Request access, or start on the open evaluate tier with your first decision — no key required. The two tiers are set out on Capabilities and access.

Authoring is invite-only private beta — request 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:

{
  "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.

Pin field notes exactly

Use notes on a field spec when the note content is authoritative. It is an ordered list of objects. Each has a required note_text string, an optional source string, and an optional metadata object. The metadata is opaque JSON: the engine preserves it without assigning meaning to its keys.

curl -s -X POST "https://api.aethis.ai/api/v1/public/projects/$PROJECT_ID/fields/spec" \
  -H "X-API-Key: $AETHIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_fields": [
      {
        "key": "example.confirmed",
        "sort": "Bool",
        "notes": [
          {
            "note_text": "Confirm the supplied record.",
            "source": "example-policy#1",
            "metadata": { "type": "rationale" }
          }
        ]
      }
    ]
  }'

{ "project_id": "proj_...", "expected_field_count": 1 }

From the CLI, write the same shape in fields/fields.yaml:

fields:
  - key: example.confirmed
    type: bool
    notes:
      - note_text: Confirm the supplied record.
        source: example-policy#1
        metadata:
          type: rationale

Each call replaces the project’s entire field spec, so include every expected field, not only the one you are pinning. The property has three states:

Omit notes on a field to leave its notes to the model.
Send notes: [] to clear the field’s notes authoritatively.
Do not send notes: null. The API rejects it with a 422; use [] to clear.

Each note may use only note_text, source, and metadata. An unknown key, or an entry without note_text, is rejected with a 422. The CLI (v0.43.0+) applies the same checks to fields.yaml before it makes any engine call, and sends each entry exactly as written. During generation, the engine checks an authored list exactly, including list order and metadata (object key order does not matter), and checks it again before it saves the resulting ruleset. If the generated ruleset’s notes still differ, the generation fails with authored_notes_mismatch. When you refine a ruleset whose fields already carry the declared notes, the refinement can leave them unchanged. aethis_validate_fields is a separate check. It compares field keys, types, and enum values; it does not validate authored notes.

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):

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

Returns (mismatch):

{
  "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.

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.

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

Phase 2 — Field vocabulary

Why field vocabulary matters

Step 1 — Discover fields from source text

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

Pin field notes exactly

Step 3 — Explicit validation

Refine if fields are wrong

Field naming conventions

After field vocabulary

​Why field vocabulary matters

​Step 1 — Discover fields from source text

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

​Pin field notes exactly

​Step 3 — Explicit validation

​Refine if fields are wrong

​Field naming conventions

​After field vocabulary

Why field vocabulary matters

Step 1 — Discover fields from source text

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

Pin field notes exactly

Step 3 — Explicit validation

Refine if fields are wrong

Field naming conventions

After field vocabulary