# YAML Schema for type-spec documents
type: object
properties:
  type:
    type: string
    description: Path to parent type-spec or self-reference
    pattern: "^types/.*\\.md$"
  name:
    type: string
    description: Short human-facing type name
    minLength: 1
    pattern: "^[a-z][a-z0-9-]*$"
  description:
    type: string
    description: Retrieval description for this type contract
    minLength: 10
  schema:
    type: [string, "null"]
    description: Path to schema file or null
    pattern: "^types/.*\\.schema\\.yaml$|^null$"
  subtype_field:
    type: [string, "null"]
    description: Name of the frontmatter field on instances of this type that carries its subtype/category (e.g. entity_type), or null/omitted if this type has no subtype field
    pattern: "^[a-z][a-z0-9_]*$"
  layout:
    type: object
    description: >-
      Optional map of subtype value -> {dir, title}, declaring where instances
      of each subtype are written under wiki/ and what section title/order to
      use in wiki/index.md. Only types with subtype-driven directory
      placement (e.g. entity) need this; omit for types with a single flat
      directory.
    additionalProperties:
      type: object
      properties:
        dir:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
      required:
        - dir
        - title
      additionalProperties: false
  base_dir:
    type: string
    description: >-
      Directory, relative to the wiki root (wiki/), where instances of this
      type are written - e.g. `entities`. Required on every instantiable
      type; omit only for types that are never instantiated as pages (e.g.
      type-spec itself). Combined with `layout:` for subtype-driven
      placement, giving wiki/<base_dir>/<layout[subtype].dir>/<Title>.md.
    pattern: "^[a-z][a-z0-9/_-]*$"
  title_prefix:
    type: string
    description: >-
      Optional prefix prepended to a page's title/filename at scaffold time
      (e.g. `Source - ` for source pages). Defaults to no prefix.
    minLength: 1
  page_ref_fields:
    type: array
    description: >-
      Frontmatter fields on instances of this type whose entries are wiki page
      titles (e.g. `related`, `sources`, `entities`). `wikitool lint` checks
      every entry resolves to an existing page, and `wikitool rename`/`rm`
      rewrite them. Declared here rather than hardcoded in Python so a new
      type needs no code change. Omit for types with no page-reference fields.
    items:
      type: string
      pattern: "^[a-z][a-z0-9_]*$"
  capture_fields:
    type: array
    description: >-
      Frontmatter fields on instances of this type that are fixed at capture
      time and never correctable afterwards except by re-capturing the source
      (e.g. `fidelity`, `authority` for a source page). `raw accept`,
      `new source` and `touch --set` read this instead of a hardcoded field
      list. Omit for types with no capture-time fields.
    items:
      type: string
      pattern: "^[a-z][a-z0-9_]*$"
  root:
    type: string
    description: >-
      Which root a `base_dir:` resolves against - `kb` (the default, so
      omitting this field is equivalent to `kb`) for a page this instance
      writes, or `repo` for a type whose artifacts are legitimately not
      knowledge (e.g. `instruction`).
    enum: [kb, repo]
  guidance:
    type: string
    description: >-
      Repo-relative path to a `types/type-guidance.md`-shaped document
      holding this type's stack-owned authoring prose. Meaningful only on a
      `root: kb` type-spec; omit for a type an instance writes entirely for
      itself.
    pattern: "^types/.*\\.md$"
required:
  - type
  - name
  - description
  - schema
additionalProperties: false