# title
RTFM JSON Schema Mapping (rtfm-mapping-v1)

# description
Declarative mapping consumed by the RTFM open retrieval layer. Drop a file conforming to this schema in .rtfm/mappings/ and any JSON document matching match.schema_url or match.discriminator is extracted into typed chunks at sync time. Full reference: https://roomi-fields.github.io/rtfm/json-mappings/

# properties.name.description
Stable identifier for this mapping. Used for deduplication on registration — two mappings with the same name replace each other (most-recently-loaded wins). Conventionally kebab-case with a version suffix, e.g. nblm-answer-v1.

# properties.match.description
Rules used to detect that a JSON document should be processed by this mapping. A mapping matches when ANY declared rule matches.

# properties.match.properties.schema_url.description
Match if the document's $schema or $id field equals this URL. Preferred when the producing project publishes a formal JSON Schema.

# properties.match.properties.discriminator.description
Match if every entry { field_path: expected_value } resolves to the expected value in the document. Field paths use dotted notation (a.b.c) and walk into nested dicts and list indices.

# properties.match.properties.discriminator.additionalProperties.description
Expected value (any JSON scalar — string, number, boolean, null).

# properties.chunks.description
Ordered list of chunk specifications. Each spec emits zero or more chunks at sync time. Required: at least one spec.

# properties.edges.description
Optional edge specifications. Each spec emits zero or more EdgeCandidates with the declared relation_type. Edge resolution to the database depends on the existing sync layer (import/link/include resolve to indexed files; custom relations like cites are produced but currently not materialized).

# $defs.chunkSpec.properties.title.description
Template for the chunk's chapter_title. Supports {{ dotted.path }} placeholders evaluated against the current context (root document, or each item if foreach is set).

# $defs.chunkSpec.properties.content.description
Template for the chunk content. Required and non-empty after rendering — empty content is silently skipped. Supports {{ dotted.path }} placeholders.

# $defs.chunkSpec.properties.foreach.description
Dotted path resolving to a list. When set, one chunk is emitted per item, and templates inside this spec evaluate against each item.

# $defs.chunkSpec.properties.metadata.description
Key-value pairs stored in chunks.metadata (JSON column). String values are template-rendered; non-string values pass through unchanged.

# $defs.edgeSpec.properties.relation.description
Stored as relation_type in the edges table. Standard values: import, link, include (resolved by sync layer). Custom values are produced as EdgeCandidates but not yet materialized.

# $defs.edgeSpec.properties.foreach.description
Like chunk-spec foreach: walks a list, emits one edge per item.

# $defs.edgeSpec.properties.target.description
Template for the edge target reference. Supports {{ dotted.path }} placeholders. Resolution semantics depend on relation type.

# $defs.edgeSpec.properties.target_kind.description
Informational hint about the kind of reference produced by target. Stored in EdgeCandidate.source_detail; future versions of the resolver may use it for resolution heuristics.