Design a vocabulary

A vocabulary is the reviewed naming contract between source documentation and a compiled schema. It tells the schemafier which fields may exist and which phrases in the source refer to them. A good vocabulary prevents the extractor from turning incidental wording into permanent field IDs.

Copy this vocabulary template:

my_concept:
  fields:
    - canonical: timeout_seconds
      aliases:
        - request timeout
        - timeout duration
        - timeout
      assignment_excludes:
        - connection timeout

    - canonical: retry_policy
      aliases:
        - retry behavior
        - retries
        - retry configuration

    - canonical: metadata.name
      aliases:
        - resource name
        - object name

What each part means

Concept key

my_concept must match the name supplied to scull-schemafier run --concept. Keep the concept focused enough that its fields belong together and that agents would reasonably search them as one topic.

Canonical name

canonical becomes the stable field ID in the schema and query layer. Prefer the source API's exact property path when one exists, such as metadata.name. For conceptual fields without a source key, use a short descriptive snake_case name such as retry_policy.

Treat canonical names as an API. Renaming one after release can break callers and reviewed caveat attachments, so choose for stability rather than mirroring a page heading that may be rewritten.

Aliases

Aliases are exact alternate phrases the source actually uses for the same field. Include spelling, capitalization, abbreviations, or prose wording that materially differs from the canonical name.

Do not add every vaguely related synonym. Broad aliases make different fields overlap and increase the risk of a plausible-looking misassignment. An alias should answer: “If the source says this, does it unambiguously mean this canonical field?”

Assignment exclusions

assignment_excludes is optional reviewer-owned evidence that a phrase belongs somewhere else. Use it only after identifying a real collision—for example, when timeout correctly maps to timeout_seconds but connection timeout must not. The extraction prompt and the deterministic assignment audit both use these exclusions.

A practical workflow

1. List the fields and operations explicitly present in the structured spec.
2. Read the prose headings, parameter tables, and examples for alternate wording.
3. Choose one stable canonical name for each distinct behavior.
4. Add only source-grounded aliases.
5. Look for overlapping aliases and add an exclusion only when a real ambiguity remains.
6. Run extraction, inspect every assignment, then run the committed-schema audit.

For a large docset, the schemafier can draft a proposal:

scull-schemafier vocab bootstrap \
  --concept my_concept \
  --docset /path/to/my-docset \
  --out vocabulary.proposed.yaml

The proposal is not an approved vocabulary. Review it, remove unsupported entries, resolve aliases that could name multiple fields, and then copy the accepted section into vocabulary.yaml.

Review checklist

• The top-level concept key exactly matches --concept.
• Every canonical name represents one distinct field or operation.
• Structured API property names are preserved when stability requires it.
• Every alias appears in, or is directly supported by, the source material.
• No alias reasonably names two canonical fields.
• Exclusions describe observed collisions rather than hypothetical ones.
• The vocabulary contains no descriptions, caveats, defaults, or type declarations; those belong in source extraction and the generated schema.

After extraction, verify the final assignments deterministically:

scull-schemafier audit-assignments \
  --schemas schemas \
  --vocab vocabulary.yaml

Continue with Build a schemaset for the complete source-to-schema workflow.