torben
55f65c1ab1
Files changed: - CHANGES.md - VERSION - instructions/dev/doc-pull-through.md - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/tests/test_docs_verify.py - types/type-spec.md - types/type-spec.schema.yaml
104 lines
3.7 KiB
YAML
104 lines
3.7 KiB
YAML
# 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 |